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.

NOTE: The amount of custom activities you can create depends on your Ortto plan.

This page provides descriptions of this endpoint’s:

request resource and method,
valid parameters, headers, and request body values, as well as
the response payload.

HTTP method and request resources


 POST https://api.ap3api.com/v1/definitions/activity/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 custom fields in your Ortto account’s CDP.

NOTE: Duplicate name values are not allowed.

Example create custom activity definition request body

json
 {
"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
`name`		`string`	The `name` for the custom field specified in the request body.
`icon_id`		`string`	The ID for the icon shown against the activity in the Ortto app. You can find a list of icons and their ID values in the table under Activity icons.
`track_conversion_value`		`boolean`	If `true`, the activity can be assigned a conversion value to be considered as the value attributed to the activity. If `false`, conversion value is not enabled.
`touch`		`boolean`	If `true`, this will update the `first seen` and `last seen` values for the person associated with the activity. Learn more about track as touch. If `false`, touch is not enabled.
`filterable`		`boolean`	If `true`, this will allow users to create filters and generate reports using the activity. Otherwise, `false`.
`visible_in_fields`		`boolean`	If `true`, the activity will be displayed in feeds throughout the app (such as in the Activities feed in a person’s view). Otherwise, `false`.
`display_style`		`array` of strings	`display_style` determines how the activity value displays in activity feeds. 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 `display_style` is specified at `type`. `type` can be: * `activity` (activity only) * `activity_attribute` (activity and attribute) * `activity_template` (custom code) If using `activity_template` you need to specify a `title`, which is the value you wish to use as your custom activity output, such as one of the activity attributes. This value needs to be specified as a variable, e.g. `title: "Placed order {{attribute.order_id}} for {{attribute.value}}"`(where `order_id` and `value` are the attribute names).
	`type`	`string`
	`title`	`string`
	`attribute_name`	`string`	The attribute to be included in the activity event output (where `type` is set to `activity_attribute`).
	`attribute_field_id`	`string`	The field ID for the custom activity attribute. (Note this is independent of person field IDs.)
`attributes`		`array` of objects	The names, types and IDs of the activity’s attributes.
	`name`	`string`	The activity attribute name.
	`display_type`	`string`	The attribute’s field type. Learn more about the available types and their descriptions under Attributes in the Custom activities guide. Display types can be set as follows: `"display_type": "email"` `"display_type": "text"` `"display_type": "large_text"` `"display_type": "integer"` `“display_type": "decimal"` `"display_type": "currency"` `"display_type": "date"` `"display_type": "time"` `"display_type": "bool"` `"display_type": "phone"` `“display_type": "single_select"` `"display_type": "multi_select"` `"display_type": "link"` `"display_type": "object"`
	`field_id`	`string`	`field_id` is optional if the attribute is not mapped to a CDP field. Values can be: empty (e.g. `""`) — this will result in an attribute with no value, `do-not-map` — the attribute is not mapped to a custom or system CDP field, or a field ID, e.g. `str::first` — this specifies the CDP field ID to populate as the attribute value. In this example, `str::first` would populate the attribute value with the first name of the person who performed the activity.

Activity icons

The following table details the icons for activity definitions.

Icon	Icon ID
	calendar-illustration-icon
	caution-illustration-icon
	clicked-illustration-icon
	coupon-illustration-icon
	download-illustration-icon
	email-illustration-icon
	eye-illustration-icon
	flag-activities-illustration-icon
	happy-illustration-icon
	moneys-illustration-icon
	page-illustration-icon
	phone-illustration-icon
	reload-illustration-icon
	tag-illustration-icon
	time-illustration-icon

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 definition response payload from Ortto’s CDP

json
 {
    "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
`custom_activity`			`array` of strings	The `custom_activity` array consists of the activity definition data.
	`name`		`string`	The name of the custom activity.
	`activity_field_id`		`string`	The field ID for the custom activity. Learn more about Ortto’s field ID format in person fields.
	`state`		`string`	Identifies the status of the custom activity. Once created, the custom activity will remain at `awaiting_implementation` (seen as `Setup` in the app) until the first event for that activity has occurred (such as via the `v1/activities/create` endpoint described in the Custom activities guide), then will move to `live`.
	`display_mode`		`string`	The activity design (determined as `display_style` in the request body).
		`type`	`string`	The activity display type, e.g. activity and attribute.
		`attribute_field_id`	`string`	The field ID of the attribute to be included in the activity event output (set at `type`).
	`attributes`		`array` of objects	The `attributes` array consists of an array of objects, where each object contains data for the custom activity attributes.
		`name`	`string`	The attribute name.
		`field_id`	`string`	The field ID for the custom activity attribute.
		`cdp_field_id`	`string`	The ID for CDP field the the custom activity attribute is mapped to.
		`display_type`	`string`	The attribute’s field type. Learn more about the available types and their descriptions under Attributes in the Custom activities guide.
		`liquid_name`	`string`	The Liquid syntax for the custom activity attribute.
	icon_id		`string`	The ID for the icon shown against the activity in the Ortto app.
	`track_conversion_value`		`boolean`	If `true`, the activity can be assigned a conversion value to be considered as the value attributed to the activity. If `false`, conversion value is not enabled.
	touch		`boolean`	If `true`, this will update the `first seen` and `last seen` values for the person associated with the activity. Learn more about track as touch. If `false`, touch is not enabled.
	filterable		`boolean`	If `true`, this will allow users to create filters and generate reports using the activity. Otherwise, `false`.
	`visible_in_feeds`		`boolean`	If `true`, the activity will be displayed in feeds throughout the app (such as in the Activities feed in a person’s view). Otherwise, `false`.
	`created_by`		`string`	How the custom activity definition was created.
	`created_at`		`string`	The date and time the custom activity definition was created. Format is ISO 8601.
	`edited_at`		`string`	The date and time the custom activity definition was edited. Format is ISO 8601.