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.

Endpoints

VerbEndpointDescription
POST/accounts/{account-id}/audiences/searchSearch for audiences by audience IDs, retailer IDs and/or segment IDs.

Audience Attributes

AttributeData TypeDescription
idstringAudience ID, generated internally by Criteo

Accepted values: string of int64
Writeable? N / Nullable? N
namestringAudience name

Accepted values: string
Writeable? Y / Nullable? N
descriptionstringDescription of the Audience

Accepted values: string
Writeable? Y / Nullable? N
accountIdstringAccount ID associated with the Audience, generated internally by Criteo

Accepted values: string of int64
Writeable? N / Nullable? N
retailerId*stringRetailer ID, associated with the Audience Segment, generated internally by Criteo

Accepted values: string of int64
Writeable? N / Nullable? N
algebraobjectAlgebra node with the definition of how the different audience segments are combined together to create the audience, using logical operators and, or and not

Accepted values: see Algebra Nodes
Writeable? N / Nullable? N
createdAttimestampTimestamp of Audience creation, in UTC

Accepted values: yyyy-mm-ddThh:mm:ss.msZ (in ISO-8601 )
Writeable? N / Nullable? N
createdByIdstringUser ID who created the Audience (null if created by a service)

Accepted values: string
Writeable? N / Nullable? Y
updatedAttimestampTimestamp of last Audience update, in UTC

Accepted values: yyyy-mm-ddThh:mm:ss.msZ(in ISO-8601)
Writeable? N / Nullable? N

* Required at create operation

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/{account-id}/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": []
}