Retrieve a list of audiences (get)

The get Ortto endpoint of the audiences entity is used to retrieve one or more audiences in Ortto’s customer data platform (CDP).

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 resource


 POST https://api.ap3api.com/v1/audiences/get

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 object is an example of field and object data that Ortto can recognize to get data from one or more person records in your Ortto account’s CDP.

Example retrieve audiences request body from Ortto’s CDP

json
 {
    "search_term": "subscribers",
    "with_filter": true,
    "limit": 10,
    "offset": 0
}

Valid request body elements

The following table lists all valid, optional request body elements (arrays, objects, or fields), which are available to this endpoint.

Element	Type	Description
`search_term`	`string`	The term used to search for audience names.
`with_filter`	`boolean`	`False` by default. If `true`, return in the response payload the filter condition used as the entry criteria for the audience.
`limit`	`integer`	The `limit` value determines the number of audiences to be returned by Ortto from the request. Both the default and maximum values are `40`. This value also represents the "page" length of audiences (for pagination purposes). This element can be used in conjunction with `offset` to retrieve subsequent pages of audience records. If this limit element is not specified in the request, or an integer value beyond the permitted maximum is specified, then this value is assumed to be `50`.
`offset`	`integer`	The `offset` element represents the count of audiences in your Ortto account’s CDP for pagination purposes, and is the point from which the next page of people (defined by the limit member value) is retrieved. The `offset` value determines how many of the first audiences will be skipped in the response.
`archived`	`boolean`	If `true`, return in the response payload archived audiences. Otherwise, `false`.
`retention`	`boolean`	If `true`, return in the response payload audiences which are retention audiences. Otherwise, `false`.

Response payload

The response payload consists of a JSON object whose elements are listed in the table below.

The following JSON object is an example of an audience that Ortto retrieves from your Ortto account’s CDP after a request to this endpoint.

Example retrieve audiences response payload from Ortto’s CDP

json
 [
    {
        "id": "624bd7905a9d367aaf824083",
        "instance_id": "myorttoaccount",
        "icon_id": "mobile-illustration-icon",
        "type": "permanent",
        "building": false,
        "ready": true,
        "is_public": false,
        "sms_is_public": false,
        "sms_public_name": "",
        "sms_public_description": "",
        "filter": {
            "$and": [
                {
                    "$and": [
                        {
                            "$has_any_value": {
                                "label": "SMS permission is true",
                                "field_id": "phn::phone",
                                "timezone": "Australia/Sydney"
                            }
                        }
                    ]
                }
            ]
        },
        "created": "2022-04-05T05:45:52.52Z",
        "created_by_id": "",
        "created_by_name": "",
        "edited_at": "2022-05-17T02:01:02.282Z",
        "name": "SMS subscribers",
        "public_name": "",
        "public_description": "",
        "template_id": "000000000700000000000200",
        "exit_selection": "",
        "new_exit_criteria_filter": null,
        "destinations": null,
        "sms_opted_in": 53,
        "subscribers": 53,
        "members": 53,
        "added_last_30_days": 3
    }
]

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
`id`	`string`	A string identifying the audience by its unique ID number.
`instance_id`	`string`	The name of the Ortto instance (account) the audience belongs to.
`icon_id`	`string`	The ID for the icon displayed against the audience in the Ortto app.
`building`	`boolean`	If `true`, the audience is in a `building` state due to a change in entry or exit criteria. Otherwise, `false`.
`ready`	`boolean`	If `true`, the audience has finished building. Otherwise, `false`.
`is_public`	`boolean`	If `true`, the audience is included in the email preference center. Otherwise, `false`.
`sms_is_public`	`boolean`	If `true`, the audience is included in the SMS preference center. Otherwise, `false`.
`sms_public_name`	string	The public name of the audience shown in the SMS preference center.
`sms_public_description`	string	The public description of the audience shown in the SMS preference center.
`filter`	`array` of `objects`	The filter conditions used to enter contacts into the audience.
`created`	`string`	The date and time the audience was created. Format is ISO 8601.
`created_by_id`	`string`	A unique ID for the user who created the audience.
`create_by_name`	`string`	The name of the user who created the audience.
`edited_at`	`string`	The date and time the audience was last edited. Format is ISO 8601.
`name`	`string`	The name of the audience (this may be different to the `public_name`, if set).
`public_name`	`string`	The public name of the audience shown in the email preference center.
`public_description`	`string`	The public name of the audience shown in the email preference center.
`template_id`	`string`	Audiences that are Ortto system audiences, or ones created from data source integrations, have a `template_ID`.
`exit_selection`	`string`	The condition/s by which members exit the audience. An empty value represents the default 'They no longer meet the entry criteria' option.
`destinations`	`object` or `null`	If the audience is being sent to any destinations (such as Google), the value will be populated. Otherwise, `null`.
`sms_opted_in`	`integer`	The count of audience members who are opted in to receive SMS communications.
`subscribers`	`integer`	The count of audience members who are valid subscribers.
`members`	`integer`	The count of audience members.
`added_last_30_days`	`integer`	The count of audience members added in the last 30 days.