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

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

{
    "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

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`.

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

[
    {
        "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

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.

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.