Modify a custom activity definition (modify)

The modify Ortto endpoint of the activity entity is used to modify one custom activity definition in Ortto’s customer data platform (CDP).

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

This page provides descriptions of this endpoint’s:

HTTP method and request resources

PUT https://api.ap3api.com/v1/definitions/activity/modify

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.

Duplicate name values are not allowed.
Example modify custom activity definition request body
{
"name": "act1",
"activity_field_id": "act:cm:act1",
"state": "live",
"icon_id": "happy-illustration-icon",
"track_conversion_value": false,
"touch": false,
"filterable": true,
"visible_in_feeds": false,
"display_style": {
    "type": "activity_attribute",
    "title": "",
    "attribute_name": "attr1",
    "attribute_field_id": "str:cm:attr1"
},
"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": "attr4",
        "display_type": "single_select",
        "field_id": "str:cm:cfieldsin"
    },
    {
        "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.

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.

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 will 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 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 name of the activity attribute.

display_type

string

The attribute’s field type. Learn more about the available types and their descriptions under Attributes in the Custom activities guide.

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.

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 modify custom activity definition response payload from Ortto’s CDP
{
    "custom_activity": {
        "name": "act1",
        "activity_field_id": "act:cm:act1",
        "state": "live",
        "display_mode": {
            "type": "activity_attribute",
            "attribute_name": "attr1",
            "attribute_field_id": "str:cm:attr1"
        },
        "attributes": [
            {
                "name": "attr1",
                "field_id": "str:cm:attr1",
                "cdp_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": "attr4",
                "field_id": "str:cm:attr4",
                "display_type": "single_select",
                "liquid_name": "activity.custom.act1.attr4"
            },
            {
                "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": false,
        "filterable": true,
        "visible_in_feeds": false,
        "created_by": "",
        "created_at": "0001-01-01T00:00:00Z",
        "edited_at": "2022-08-31T05:27:33.321213397Z"
    }
}

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_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 of the attribute to be included in the activity event output (where type is set to activity_attribute).

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.