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

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 `not` Accepted 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 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/{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": []
}

Introduction

🚧Note on Audience Computation

Endpoints

Audience Attributes

Search Audiences

🚧
Note on Audience Computation