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:
-
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 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.
{
"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 |
---|---|---|
|
|
The term used to search for audience names. |
|
|
|
|
|
The This value also represents the "page" length of audiences (for pagination purposes). This element can be used in conjunction with |
|
|
The |
|
|
If |
|
|
If |
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.
[
{
"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 |
|
A string identifying the audience by its unique ID number. |
instance_id |
|
The name of the Ortto instance (account) the audience belongs to. |
icon_id |
|
The ID for the icon displayed against the audience in the Ortto app. |
building |
|
If |
ready |
|
If |
is_public |
|
If |
sms_is_public |
|
If |
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 |
|
The filter conditions used to enter contacts into the audience. |
created |
|
The date and time the audience was created. Format is ISO 8601. |
created_by_id |
|
A unique ID for the user who created the audience. |
create_by_name |
|
The name of the user who created the audience. |
edited_at |
|
The date and time the audience was last edited. Format is ISO 8601. |
name |
|
The name of the audience (this may be different to the |
public_name |
|
The public name of the audience shown in the email preference center. |
public_description |
|
The public name of the audience shown in the email preference center. |
template_id |
|
Audiences that are Ortto system audiences, or ones created from data source integrations, have a |
exit_selection |
|
The condition/s by which members exit the audience. An empty value represents the default 'They no longer meet the entry criteria' option. |
destinations |
|
If the audience is being sent to any destinations (such as Google), the value will be populated. Otherwise, |
sms_opted_in |
|
The count of audience members who are opted in to receive SMS communications. |
subscribers |
|
The count of audience members who are valid subscribers. |
members |
|
The count of audience members. |
added_last_30_days |
|
The count of audience members added in the last 30 days. |