Create a custom activity event (create)
The create
Ortto endpoint of the activities
entity is used to create one or more custom activity events in Ortto’s customer data platform (CDP).
Creating and managing activity definitions is handled using the activity
entity.
All field types are supported when creating a custom activity definition, and follow the same rules and limits as when creating a field in the Ortto app.
This page provides descriptions of this endpoint’s:
-
valid parameters, headers, and request body values, as well as
-
the response payload.
HTTP method and request resources
POST https://api.ap3api.com/v1/activities/create
Ortto customers who have their instance region set to Australia or Europe will need to use specific service endpoints relative to the region:
For example: https://api.eu.ap3api.com/v1/<entity/endpoint> All other Ortto users will use the default service endpoint (https://api.ap3api.com/). |
Headers
This endpoint requires a custom API key and content type (application/json
for the request body) in the header of the request:
-
X-Api-Key: CUSTOM-PRIVATE-API-KEY
-
Content-Type: application/json
Request body
The request body consists of a JSON object with the valid elements listed in the table below.
The following JSON objects are examples of requests to create custom activities in your Ortto account’s CDP.
{
"activities": [
{
"activity_id": "act:cm:flight-booked",
"attributes": {
"int::v": 15300,
"str:cm:destination": "London",
"str:cm:carrier": "Easy Jet"
},
"fields": {
"str::first": "Billie",
"str::last": "Holiday",
"str::email": "billie.holiday@email.com"
},
"location": {
"source_ip": "172.217.4.1",
"custom": null,
"address": null
}
}
],
"merge_by": [
"str::email"
]
}
Depending on the merge strategy configured for your custom API key, sending activity data for a person who does not match an existing contact in your CDP may create that person as a new contact. By default, all people added via the API are considered to be "opted in" for email subscription permission.
To send an create an activity event that contains an email subscription permission, include in fields
:
bol::p
— a field representing permission that takes a value of true
or false
str::s-ctx
— a field used to create a message identifying how the person was subscribed/unsubscribed.
In an activity event request, that would look like:
{
"activities": [
{
"activity_id":"act:cm:logged-in",
"attributes": {
"str:cm:payment-plan": "Free plan",
"bol:cm:account-owner": true,
"str:cm:web-browser": "Netscape Navigator"
},
"fields": {
"str::first": "Chris",
"str::last": "Smith",
"str::email": "chris.smith@example.com",
"bol::p": false,
"str::u-ctx": "Unsubscribed via internal API"
}
}
]
}
Learn more about email permission and activities.
If necessary, you can override your API key’s merge strategy by including merge_strategy
and the required value (1
— append only, 2
— overwrite existing, or 3
— ignore) in the request.
Learn more about setting a merge strategy.
For asynchronous activity ingestion, add the "async": true flag to the request.
Learn more about asynchronous activity ingestion.
|
Custom activity request limits
It is possible to send up to 100 activities in the one payload to Ortto. The limits are as follows:
-
100 activities max
-
2 MB total payload size
In addition to the above, the number of activities per contact per day is limited. The limit is 50 activity events per activity per contact per 24 hours. See an example illustrating this limit under Custom activity request limits in the Custom activities guide.
Valid request body elements
The following table lists all valid request body elements (arrays, objects, or fields), which are available to this endpoint.
Element | Type | Description | |
---|---|---|---|
|
|
The * * |
|
|
|
The ID for the custom activity. |
|
|
Object containing activity attributes |
The field IDs for the custom activity attributes. (Note this is independent of person field IDs.) The conversion value is set at |
|
Object containing person fields. |
The object containing the fields for a person being created or updated in your Ortto account’s CDP.
|
||
|
Object containing location field data |
The The |
|
|
The When the value of the person field ID (determined by the relevant These values override the default person fields associated with the custom API key with the |
Response payload
The response payload consists of a JSON object with the elements listed in the table below.
The following JSON object is an example of people’s data that Ortto retrieves from your Ortto account’s CDP after a request to this endpoint.
{
"activities": [
{
"person_id": "0063f2c474449cd58a4c5600",
"status": "ingested",
"person_status": "created",
"activity_id": "0063f2c474bc15d72affcdcc"
}
]
}
Response payload elements
The following table lists all elements (arrays, objects, or fields) in the response from a request to this endpoint.
Element | Type | Description | ||
---|---|---|---|---|
|
|
The The list of responses correlates to the array of activity events that were sent in the request. So if you sent 2 activities in your request, index 2 in the response is your result for index 2 in the request. See an example of sending multiple activities and the responses under Custom activity request limits. |
||
|
|
The unique identifier for the CDP contact. |
||
|
|
The If you used the |
||
|
|
Identifies the status of the person associated with the activity.
Learn more about If you used the |
||
|
|
The unique identifier for the activity event. |