Create an account custom activity event (create)
The create
Ortto endpoint of the accounts/activities
entity is used to create one or more custom account activity events in Ortto.
This page provides descriptions of this endpoint’s:
- the response payload.
HTTP method and request resources
POST https://api.ap3api.com/v1/accounts/activities/create
NOTE: Ortto customers who have their instance region set to Australia or Europe will need to use specific service endpoints relative to the region:
Australia: https://api.au.ap3api.com/ Europe: https://api.eu.ap3api.com/For example: https://api.eu.ap3api.com/v1/<entity/endpoint>
All other Ortto users will use the default service endpoint (https://api.ap3api.com/).
Path and query parameters
This endpoint takes no additional path and/or query parameters.
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 account custom activities in your Ortto account.
Example create an account custom activity event request body
json
{ "activities": [ { "activity_id": "act:oc:flight-booked", "attributes": { "int::v": 17500, "str:cm:carrier": "Easy Jet", "str:cm:destination": "London" }, "fields": { "str:o:name": "CompanyName" } } ], "merge_by": [ "str:o:name" ] }
You can also merge account records using the Account ID. This approach restricts the updates you can make to the account at the same time as raising the activity, but it results in much faster processing since the direct account is known and doesn't need to be looked up using a filter.
NOTE: If merging by the Account ID, simply provide a
str:o:organization_id
value, when doing this, you do not need to include themerge_by
field. Also, any data passed in via thefields
object will be ignored if merging viastr:o:organization_id
.Example create account custom activity event request body and merge by Account ID
json
{ "activities": [ { "activity_id": "act:cm:flight-booked", "str:o:organization_id": "00671822e88c13e21abf2302", "attributes": { "int::v": 15300, "str:cm:destination": "London", "str:cm:carrier": "Easy Jet" } } ] }
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 sizeIn addition to the above, the number of activities per account per day is limited. The limit is 50 activity events per activity per account per 24 hours.
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
activities
array
of objectsThe
activities
array consists of an array of objects where each object contains data associated with an activity event being created in your Ortto account’s CDP. Each of these objects can contain:•
activity_id
and activityattributes
objects•
fields
object.
activity_id
string
The ID for the custom activity.
attributes
Object containing activity attributes
The field IDs for the custom activity attributes. (Note this is independent of account field IDs).
The conversion value is set at
int::v
. The value is currency and must be multiplied by 1000. Using the example above,"int::v": 15300
, sets the conversion value attributed to the activity at $15.30
fields
Object containing account fields.
The object containing the fields for a account being created or updated in your Ortto account’s CDP. This account is either created or updated in Ortto’s CDP based on these criteria:
If thisfields
object contains a account field ID whose value matches themerge_by
ID value submitted in this request, and this account field’s value does not match that of an existing account in Ortto’s CDP, then Ortto creates this account as a new record. Otherwise, if the account field ID value does already match that of an existing account in Ortto’s CDP, then Ortto updates the fields of that account record in the Ortto CDP, according to themerge_strategy
set for your Ortto custom API data source.
merge_by
array
of one or twostring
valuesThe
merge_by
element’s array allows up to two field ID values that specify the account fields used to determine whether the account records are either created or updated in your Ortto account’s CDP.When the value of the account field ID (determined by the relevant
merge_by
value), submitted in this request matches that of an existing account in Ortto, then this account's record is updated in the CDP and where appropriate, existing field values are merged according to themerge_strategy
set for your Ortto custom API data source. Otherwise, Ortto creates a new account record.These values override the default account fields associated with the custom API key with the
merge_by
fields submitted in this request. These default field values are defined by the Merge strategy associations configured for this custom API key. If amerge_by
element is not specified in the request, then these default account field values are utilized instead. The first of these values determines the mainmerge_by
account field utilized by Ortto in the request, whereas the second (optional) value determines the fallbackmerge_by
account field (which behaves as a backup should the first field - e.g. a custom field - not be available within the account record of Ortto’s CDP).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 account data that Ortto retrieves from your Ortto account after a request to this endpoint.
Example create account custom activity event response payload from Ortto’s CDP
json
{ "activities": [ { "account_id": "1068629810d60d04d18af600", "status": "ingested", "account_status": "merged", "activity_id": "0068629af6fee095c7834342" } ] }
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
activities
array
of objectsThe
activities
array consists of the activity event data.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.
account_id
string
The unique identifier for the account.
status
string
The
status
valueingested
indicates that the activity event has been synchronously ingested.If you used the
"async": true
flag in the request, then thestatus
value will bequeued
.
account_status
string
Identifies the status of the account associated with the activity. Learn more about
account_status
values under Create activity response.If you used the
"async": true
flag in the request, then theaccount_status
value will bequeued
.
activity_id
string
The unique identifier for the activity event.
Backdating activities
If you would like to backdate activity data, you can use the
created
field in your request to specify the date on which the activity occurred. Ortto allows you to send in backdated events up to 90 days in the past, or if you have data retention enabled on your activity, you may provide backdated events up to your selected data retention period.In addition, to make sure you do not backfill the same piece of data more than once, you can include a
key
attribute, which gets combined with thecreated
date to create a unique identifier for each activity. If you provide the same pair forkey
andcreated
multiple times (such as if you need to run your backfill scripts multiple times), it will merge those requests so you do not get duplicate activities created.json
{ "activities": [ { "activity_id": "act:cm:flight-booked", "created": "2025-06-30T01:30:17.601Z", "key": "125432", "str:o:organization_id": "00671822e88c13e21abf2302", "attributes": { "int::v": 15300, "str:cm:destination": "London", "str:cm:carrier": "Easy Jet" } } ] }
As this documentation will age, if you copy the above example verbatim you might get a response like below:
json
{ "request_id": "19ccd5c1-112d-4dfa-bf80-0a3312896742", "code": 400, "error":" Created date is more than 90 days ago" }
If you provide a
created
date within the last 90 days (or within your activity’s selected data retention period), you will receive a successful response:json
{ "activities": [ { "account_id":"00602c446af92b7aa1f77a00", "status":"ingested", "account_status":"created", "activity_id":"00602c71a9b346c32c9b7473" } ] }
If you provide a
created
date outside of the activity’s selected data retention period, you will receive an error response:json
{ "request_id": "19ccd5c1-112d-4dfa-bf80-0a3312896742", "code": 400, "error":" Created date is outside of activity cold storage" }
NOTE: Activities that are more than 90 days old and within the activity’s selected data retention period will be added to a queue for processing which may take up to an hour.
Learn more about configuring data retention.