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:


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 the merge_by field. Also, any data passed in via the fields object will be ignored if merging via str: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 size

In 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 objects

The 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 activity attributes 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 this fields object contains a account field ID whose value matches the merge_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 the merge_strategy set for your Ortto custom API data source.

merge_by



array of one or two string values

The 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 the merge_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 a merge_by element is not specified in the request, then these default account field values are utilized instead. The first of these values determines the main merge_by account field utilized by Ortto in the request, whereas the second (optional) value determines the fallback merge_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 objects

The 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 value ingested indicates that the activity event has been synchronously ingested.

If you used the "async": true flag in the request, then the status value will be queued.



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 the account_status value will be queued.



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 the created date to create a unique identifier for each activity. If you provide the same pair for key and created 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.