Create a custom activity definition (create)
The create
Ortto endpoint of the definitions
entity is used to create one custom activity definitions in Ortto’s customer data platform (CDP).
This endpoint is designed to create a custom activity and its attributes.
Once this activity is created, you can then use the v1/activities/create
endpoint described in the Custom activities guide to create an activity event (such as where you wish to send a person’s login activity to Ortto).
All field types are supported when creating a custom activity definition, and follow the same rules and limits as when creating a field the Ortto app.
The amount of custom activities you can create depends on your Ortto plan. |
This page provides descriptions of this endpoint’s:
-
valid parameters, headers, and request body values, as well as
-
the response payload.
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 fields in your Ortto account’s CDP.
Duplicate name values are not allowed.
|
{
"name": "act1",
"icon_id": "happy-illustration-icon",
"track_conversion_value": false,
"touch": true,
"filterable": true,
"visible_in_feeds": true,
"display_style": {
"type": "activity_attribute",
"title": "",
"attribute_name": "attr1",
"attribute_field_id": ""
},
"attributes": [
{
"name": "attr1",
"display_type": "text"
},
{
"name": "attr2",
"display_type": "integer",
"field_id": ""
},
{
"name": "attr3",
"display_type": "single_select",
"field_id": "do-not-map"
},
{
"name": "attr5",
"display_type": "text",
"field_id": "str::first"
}
]
}
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 icon shown against the activity in the Ortto app. |
|
|
|
If |
|
|
|
If |
|
|
|
If |
|
|
|
If |
|
|
|
The activity can just display as-is (e.g. Placed order), with an attribute (e.g. Placed order #123), or with a custom code (e.g. Placed order #123 for $45,678). The * * * If using |
|
|
|
||
|
|
||
|
|
The attribute to be included in the activity event output (where |
|
|
|
The field ID for the custom activity attribute. (Note this is independent of person field IDs.) |
|
|
array of objects |
The names, types and IDs of the activity’s attributes. |
|
|
|
The activity attribute name. |
|
|
|
The attribute’s field type. Learn more about the available types and their descriptions under Attributes in the Custom activities guide. |
|
|
|
Values can be:
|
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.
{
"custom_activity": {
"name": "act1",
"activity_field_id": "act:cm:act1",
"state": "awaiting_implementation",
"display_mode": {
"type": "activity_attribute",
"attribute_field_id": "str:cm:attr1"
},
"attributes": [
{
"name": "attr1",
"field_id": "str:cm:attr1",
"display_type": "text",
"liquid_name": "activity.custom.act1.attr1"
},
{
"name": "attr2",
"field_id": "int:cm:attr2",
"display_type": "integer",
"liquid_name": "activity.custom.act1.attr2"
},
{
"name": "attr3",
"field_id": "str:cm:attr3",
"display_type": "single_select",
"liquid_name": "activity.custom.act1.attr3"
},
{
"name": "attr5",
"field_id": "str:cm:attr5",
"cdp_field_id": "str::first",
"display_type": "text",
"liquid_name": "activity.custom.act1.attr5"
}
],
"icon_id": "happy-illustration-icon",
"track_conversion_value": false,
"touch": true,
"filterable": true,
"visible_in_feeds": true,
"created_by": "Public API",
"created_at": "2022-08-11T01:47:40.149Z",
"edited_at": "2022-08-11T01:47:40.149Z"
}
}
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 name of the custom activity. |
||
|
|
The field ID for the custom activity. Learn more about Ortto’s field ID format in person fields. |
||
|
|
Identifies the status of the custom activity. Once created, the custom activity will remain at |
||
|
|
The activity design (determined as |
||
|
|
The activity display type, e.g. activity and attribute. |
||
|
|
The field ID of the attribute to be included in the activity event output (set at |
||
|
|
The |
||
|
|
The attribute name. |
||
|
|
The field ID for the custom activity attribute. |
||
|
|
The ID for CDP field the the custom activity attribute is mapped to. |
||
|
|
The attribute’s field type. Learn more about the available types and their descriptions under Attributes in the Custom activities guide |
||
|
|
The Liquid syntax for the custom activity attribute. |
||
|
|
The ID for the icon shown against the activity in the Ortto app. |
||
|
|
If |
||
|
|
If |
||
|
|
If |
||
|
|
If |
||
|
|
How the custom activity definition was created. |
||
|
|
The date and time the custom activity definition was created. Format is ISO 8601. |
||
|
|
The date and time the custom activity definition was edited. Format is ISO 8601. |