Audience Endpoints

Endpoints

Verb	Endpoint	Description
POST	`/retail-media/accounts/{account-id}/audiences/search`	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.

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/preview/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/preview/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/preview/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": []
}