Audience Endpoints
Introduction
Audiences give the ability to advertisers to define subsets of retailers visitors to be targeted in their campaigns.
Audiences are built of one or multiple audience segments that can be combined using logical Algebra Nodes to define target campaigns' audiences.
Note on Audience Computation
Audience updates are processed daily at 0h UTC and 12h UTC and can take around 5 hours to reflect on a live campaign. This is important for audiences that are frequently updated as changes should be ready for processing prior to these two times.
Partial Approvals
Bulk operations (
create,update,delete) use a partial approval model. Even if some items in the request fail, the response will return200 OK. Any failed items will be listed in the warnings section of the response with an error code and details.Examples of possible warning codes:
audience-not-found→ Audience is not found.name-must-be-unique→ Audience name must be unique.name-must-not-be-empty→ Audience name property must not be empty.This list is not exhaustive. Additional warnings may be returned depending on the request context.
Endpoints
| Verb | Endpoint | Description |
|---|---|---|
| POST | /accounts/{accountId}/audiences/search | Search for audiences by audience IDs, retailer IDs and/or segment IDs. |
Audience Attributes
| Attribute | Data Type | Description |
|---|---|---|
id | string | Audience ID, generated internally by Criteo Accepted values: string of int64 Writeable? N / Nullable? N |
name | string | Audience name Accepted values: string Writeable? Y / Nullable? N |
description | string | Description of the Audience Accepted values: string Writeable? Y / Nullable? N |
accountId | string | Account ID associated with the Audience, generated internally by Criteo Accepted values: string of int64 Writeable? N / Nullable? N |
retailerId* | string | Retailer ID, associated with the Audience Segment, generated internally by Criteo Accepted values: string of int64 Writeable? N / Nullable? N |
algebra | object | Algebra node with the definition of how the different audience segments are combined together to create the audience, using logical operators and, or and notAccepted values: see Algebra Nodes Writeable? N / Nullable? N |
createdAt | timestamp | Timestamp of Audience creation, in UTC Accepted values: yyyy-mm-ddThh:mm:ss.msZ (in ISO-8601 )Writeable? N / Nullable? N |
createdById | string | User ID who created the Audience (null if created by a service)Accepted values: string Writeable? N / Nullable? Y |
updatedAt | timestamp | Timestamp of last Audience update, in UTC Accepted values: yyyy-mm-ddThh:mm:ss.msZ(in ISO-8601)Writeable? N / Nullable? N |
* Required for the create operation
Field Definitions
- Writeable (Y/N): Indicates if the field can be modified in requests.
- Nullable (Y/N): Indicates if the field can accept null/empty values.
- Primary Key: A unique, immutable identifier of the entity, generated internally by Criteo. Primary keys are typically ID fields (e.g.,
retailerId,campaignId,lineItemId) and are usually required in the URL path.
Search Audiences
This endpoint returns a list of audiences that match the provided filters. If present, the filters are AND'ed together when applied. You can search audiences by audience IDs, retailer IDs and/or segment IDs.
Results are paginated using offset and limit query parameters; if omitted, defaults to 0 and 500, respective - see API Response
https://api.criteo.com/{version}/retail-media/accounts/{accountId}/audiences/search?offset={offset}&limit={limit)
Sample Request: searching by Retailer ID only
curl -L -X POST 'https://api.criteo.com/{version}/retail-media/accounts/625702934721171442/audiences/search' \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'Authorization: Bearer <MY_ACCESS_TOKEN>'
-d '{
"data": {
"type": "Audience",
"attributes": {
"audienceIds": null,
"retailerIds": [
"12"
],
"audienceSegmentIds": null
}
}
}
Sample Response
{
"meta": {
"totalItems": 400,
"limit": 50,
"offset": 0
},
"data": [
{
"attributes": {
"name": "My audience A",
"description": null,
"createdAt": "2024-01-12T11:46:13.77Z",
"updatedAt": "2024-02-12T11:46:13.77Z",
"accountId": "625702934721171442",
"retailerId": "12",
"algebra": {
"audienceSegmentId": "56159923678901880"
},
"createdById": "j.doe"
},
"id": "258216562069631686",
"type": "RetailMediaAudience"
},
// ...
{
"attributes": {
"name": "My audience B",
"description": null,
"createdAt": "2024-01-22T14:41:32.489Z",
"updatedAt": "2024-01-22T14:41:32.489Z",
"accountId": "625702934721171442",
"retailerId": "12",
"algebra": {
"audienceSegmentId": "225702933721195672"
},
"createdById": "a.jack"
},
"id": "920472839472539402",
"type": "RetailMediaAudience"
}
],
/* omitted if no errors */
"errors": [],
/* omitted if no warnings */
"warnings": []
}
Sample Request: searching by multiple filters
curl -L -X POST 'https://api.criteo.com/{version}/retail-media/accounts/625702934721171442/audiences/search' \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'Authorization: Bearer <MY_ACCESS_TOKEN>'
-d '{
"data": {
"type": "Audience",
"attributes": {
"audienceIds": [
"920472839472539402"
],
"retailerIds": [
"12"
],
"audienceSegmentIds": [
"225702933721195672"
]
}
}
}
Sample Response
{
"meta": {
"totalItems": 400,
"limit": 50,
"offset": 0
},
"data": [
{
"attributes": {
"name": "My audience",
"description": null,
"createdAt": "2024-01-22T14:41:32.489Z",
"updatedAt": "2024-01-22T14:41:32.489Z",
"accountId": "625702934721171442",
"retailerId": "12",
"algebra": {
"audienceSegmentId": "225702933721195672"
},
"createdById": "a.jack"
},
"id": "920472839472539402",
"type": "RetailMediaAudience"
}
],
/* omitted if no errors */
"errors": [],
/* omitted if no warnings */
"warnings": []
}
Updated 17 days ago