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:

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:

  • 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 custom activities in your Ortto account’s CDP.

Example create custom activity event request body
{
    "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:

Example create custom activity event with subscription permission request body
{
    "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

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 and location objects.

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 person 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 person fields.

The object containing the fields for a person being created or updated in your Ortto account’s CDP.
This person is either created or updated in Ortto’s CDP based on these criteria:

  • If this fields object contains a person field ID whose value matches the merge_by ID value submitted in this request, and this person field’s value does not match that of an existing person in Ortto’s CDP, then Ortto creates this person as a new record.

  • Otherwise, if the person field ID value does already match that of an existing person in Ortto’s CDP, then Ortto updates the fields of that person’s record in the Ortto CDP, according to the merge_strategy set for your Ortto custom API data source.

location

Object containing location field data

The location object either accepts a single IP address (as a source_ip field member) or a full address (in either a custom or address object).

The location object provides more flexible options for specifying a person’s location and address details rather than having to specify this information via geo-type person fields in a fields object.

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 person fields used to determine whether the people’s records are either created or updated in your Ortto account’s CDP.

When the value of the person field ID (determined by the relevant merge_by value), submitted in this request matches that of an existing person in Ortto’s CDP, then this person’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 person’s record in the CDP.

These values override the default person 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 person field values are utilized instead.
The first of these values determines the main merge_by person field utilized by Ortto in the request, whereas the second (optional) value determines the fallback merge_by person field (which behaves as a backup should the first field - e.g. a custom field - not be available within the person’s 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 people’s data that Ortto retrieves from your Ortto account’s CDP after a request to this endpoint.

Example create custom activity event response payload from Ortto’s CDP
{
    "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

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.

person_id

string

The unique identifier for the CDP contact.

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.

person_status

string

Identifies the status of the person associated with the activity. Learn more about person_status values under Create activity response.

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

activity_id

string

The unique identifier for the activity event.