Audiences Endpoints

Introduction

Audiences give the ability to advertisers to define subsets of retailer 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.

⚠️

The corresponding App should have the "Audiences Manage" permission enabled for all endpoints on this page.

🚧

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.

📘

The endpoints and functionalities covered in this page refers to features available exclusively in Preview for now, which doesn't mean that they are the only ones available for this domain/scope.

For more complete information about our API capabilities, check the Stable version in Welcome to Criteo Retail Media API

📘

Partial Approvals

Bulk operations (create, update, delete) use a partial approval model. Even if some items in the request fail, the response will return 200 OK. Any failed items will be listed in the error section of the response with an error code and details.

Examples of possible error 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

VerbEndpointDescription
POST/accounts/{account-id}/audiences/createCreate audience(s)
PATCH/accounts/{account-id}/audiencesUpdate audience(s)
POST/accounts/{account-id}/audiences/deleteDelete audience(s)

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, arbitrary and changeable. Must be unique in the account level.

Accepted values: up to 256 chars string
Writeable? Y / Nullable? N

description

string

Audience description, arbitrary and changeable.

Accepted values: up to 500 chars string
Writeable? Y / Nullable? Y

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, generated internally by Criteo. Once created, the associated retailer cannot be changed

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

algebra*

object

Algebra node with the definition of how the different audience segments are combined to create the audience, using logical operators and, or and not

Accepted values: see Algebra Nodes
Writeable? Y / Nullable? N

channels

list<enum>

Channels associated to the audience

Accepted values: Onsite, Offsite
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 create operations

📘

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.

Create Audiences

This endpoint allows the creation of one or multiple audiences in a single request.

Each audience must contain the required attributes marked above and is built of one or multiple segments.

https://api.criteo.com/preview/retail-media/accounts/{account-id}/audiences/create

Sample Request

curl -L -X POST 'https://api.criteo.com/preview/retail-media/accounts/625702934721171442/audiences/create' \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'Authorization: Bearer <MY_ACCESS_TOKEN>' \
-d '{
  "data": [
    {
      "attributes": {
        "name": "Audience made of CRM users list",
        "description": "Simple audience made of a single segment of CRM list",
        "retailerId": "1234",
        "algebra": {
          "audienceSegmentId": "735693505849913344"
        }
      }
    },
    {
      "attributes": {
        "name": "Audience of recent users from retailer not in CRM list",
        "description": "Combination of segments from User Events but not in CRM list",
        "retailerId": "4567",
        "algebra": {
          "and": [
            {
              "or": [
                {
                  "audienceSegmentId": "738406687217913856" 
                },
                {
                  "audienceSegmentId": "738406688413290496"
                }
              ]
            },
            {
              "not": { 
                "audienceSegmentId": "735693505849913344" 
              }
            }
          ]
        }
      }
    }
  ]
}'
import http.client
import json
conn = http.client.HTTPSConnection("api.criteo.com")
payload = json.dumps({
  "data": [
    {
      "attributes": {
        "name": "Audience made of CRM users list",
        "description": "Simple audience made of a single segment of CRM list",
        "retailerId": "1234",
        "algebra": {
          "audienceSegmentId": "735693505849913344"
        }
      }
    },
    {
      "attributes": {
        "name": "Audience of recent users from retailer not in CRM list",
        "description": "Combination of segments from User Events but not in CRM list",
        "retailerId": "4567",
        "algebra": {
          "and": [
            {
              "or": [
                {
                  "audienceSegmentId": "738406687217913856" 
                },
                {
                  "audienceSegmentId": "738406688413290496"
                }
              ]
            },
            {
              "not": { 
                "audienceSegmentId": "735693505849913344" 
              }
            }
          ]
        }
      }
    }
  ]
})
headers = {
  'Content-Type': 'application/json',
  'Accept': 'application/json',
  'Authorization': 'Bearer <TOKEN>'
}
conn.request("POST", "https://api.criteo.com/preview/retail-media/accounts/625702934721171442/audiences/create", payload, headers)
res = conn.getresponse()
data = res.read()
print(data.decode("utf-8"))
OkHttpClient client = new OkHttpClient().newBuilder()
  .build();
MediaType mediaType = MediaType.parse("application/json");
RequestBody body = RequestBody.create(mediaType, '{"data":[{"attributes":{"name":"Audience made of CRM users list","description":"Simple audience made of a single segment of CRM list","retailerId":"1234","algebra":{"audienceSegmentId":"735693505849913344"}}},{"attributes":{"name":"Audience of recent users from retailer not in CRM list","description":"Combination of segments from User Events but not in CRM list","retailerId":"4567","algebra":{"and":[{"or":[{"audienceSegmentId":"738406687217913856"},{"audienceSegmentId":"738406688413290496"}]},{"not":{"audienceSegmentId":"735693505849913344"}}]}}}]}');
Request request = new Request.Builder()
  .url("https://api.criteo.com/preview/retail-media/accounts/625702934721171442/audiences/create")
  .method("POST", body)
  .addHeader("Content-Type", "application/json")
  .addHeader("Accept", "application/json")
  .addHeader("Authorization", "Bearer <TOKEN>")
  .build();
Response response = client.newCall(request).execute();
<?php
require_once 'HTTP/Request2.php';
$request = new HTTP_Request2();
$request->setUrl('https://api.criteo.com/preview/retail-media/accounts/625702934721171442/audiences/create');
$request->setMethod(HTTP_Request2::METHOD_POST);
$request->setConfig(array(
  'follow_redirects' => TRUE
));
$request->setHeader(array(
  'Content-Type' => 'application/json',
  'Accept' => 'application/json',
  'Authorization' => 'Bearer <TOKEN>'
));
$request->setBody('{"data":[{"attributes":{"name":"Audience made of CRM users list","description":"Simple audience made of a single segment of CRM list","retailerId":"1234","algebra":{"audienceSegmentId":"735693505849913344"}}},{"attributes":{"name":"Audience of recent users from retailer not in CRM list","description":"Combination of segments from User Events but not in CRM list","retailerId":"4567","algebra":{"and":[{"or":[{"audienceSegmentId":"738406687217913856"},{"audienceSegmentId":"738406688413290496"}]},{"not":{"audienceSegmentId":"735693505849913344"}}]}}}]}');
try {
  $response = $request->send();
  if ($response->getStatus() == 200) {
    echo $response->getBody();
  }
  else {
    echo 'Unexpected HTTP status: ' . $response->getStatus() . ' ' .
    $response->getReasonPhrase();
  }
}
catch(HTTP_Request2_Exception $e) {
  echo 'Error: ' . $e->getMessage();
}

Sample Response

{
    "data": [
        {
            "id": "740206991503921152",
            "type": "RetailMediaAudience",
            "attributes": {
                "accountId": "625702934721171442",
                "name": "Audience made of CRM users list",
                "description": "Simple audience made of a single segment of CRM list",
                "retailerId": "1234",
                "createdById": "514277",
                "createdAt": "2025-08-04T13:31:36.84Z",
                "updatedAt": "2025-08-04T13:31:36.84Z",
                "channels": [
                    "Onsite",
                    "Offsite"
                ],
                "algebra": {
                    "audienceSegmentId": "735693505849913344"
                }
            }
        },
        {
            "id": "740200271713996800",
            "type": "RetailMediaAudience",
            "attributes": {
                "accountId": "625702934721171442",
                "name": "Audience of recent users from retailer not in CRM list",
                "description": "Combination of segments from User Events but not in CRM list",
                "retailerId": "4567",
                "createdById": "514277",
                "createdAt": "2025-08-04T13:31:36.84Z",
                "updatedAt": "2025-08-04T13:31:36.84Z",
                "channels": [
                    "Offsite"
                ],
                "algebra": {
                    "and": [
                        {
                            "or": [
                                {
                                    "audienceSegmentId": "738406687217913856"
                                },
                                {
                                    "audienceSegmentId": "738406688413290496"
                                }
                            ]
                        },
                        {
                            "not": {
                                "audienceSegmentId": "735693505849913344"
                            }
                        }
                    ]
                }
            }
        }
    ],
    "warnings": [],
    "errors": []
}

Update Audiences

This endpoint allows the modification of one or multiple audiences in a single request.

https://api.criteo.com/preview/retail-media/accounts/{account-id}/audiences

Sample Request

curl -L -X PATCH 'https://api.criteo.com/preview/retail-media/accounts/625702934721171442/audiences' \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'Authorization: Bearer <MY_ACCESS_TOKEN>' \
-d '{
  "data": [
    {
      "id": "740219868425748480",
      "type": "RetailMediaAudience",
      "attributes": {
        "name": "Audience made of CRM users list (new name)",
        "description": {
          "value": "Simple audience made of a single segment of CRM list (new description)"
        },
        "algebra": {
          "audienceSegmentId": "735693505849913344"
        }
      }
    },
    {
      "id": "740200271713996800",
      "type": "RetailMediaAudience",
      "attributes": {
        "name": "Audience of recent users from retailer not in CRM list (new name)",
       "description": {
          "value": "Combination of segments from User Events but not in CRM list (new description)"
        },
        "retailerId": "4567",
        "algebra": {
          "and": [
            {
              "or": [
                {
                  "audienceSegmentId": "738406687217913856" 
                },
                {
                  "audienceSegmentId": "738406688413290496"
                }
              ]
            },
            {
              "not": { 
                "audienceSegmentId": "735693505849913344" 
              }
            }
          ]
        }
      }
    }
  ]
}'
import http.client
import json
conn = http.client.HTTPSConnection("api.criteo.com")
payload = json.dumps({
  "data": [
    {
      "id": "740219868425748480",
      "type": "RetailMediaAudience",
      "attributes": {
        "name": "Audience made of CRM users list (new name)",
        "description": "Simple audience made of a single segment of CRM list (new description)",
        "retailerId": "1234",
        "algebra": {
          "audienceSegmentId": "735693505849913344"
        }
      }
    },
    {
      "id": "740200271713996800",
      "type": "RetailMediaAudience",
      "attributes": {
        "name": "Audience of recent users from retailer not in CRM list (new name)",
        "description": "Combination of segments from User Events but not in CRM list (new description)",
        "retailerId": "4567",
        "algebra": {
          "and": [
            {
              "or": [
                {
                  "audienceSegmentId": "738406687217913856" 
                },
                {
                  "audienceSegmentId": "738406688413290496"
                }
              ]
            },
            {
              "not": { 
                "audienceSegmentId": "735693505849913344" 
              }
            }
          ]
        }
      }
    }
  ]
})
headers = {
  'Content-Type': 'application/json',
  'Accept': 'application/json',
  'Authorization': 'Bearer <TOKEN>'
}
conn.request("PATCH", "https://api.criteo.com/preview/retail-media/accounts/625702934721171442/audiences", payload, headers)
res = conn.getresponse()
data = res.read()
print(data.decode("utf-8"))
OkHttpClient client = new OkHttpClient().newBuilder()
  .build();
MediaType mediaType = MediaType.parse("application/json");
RequestBody body = RequestBody.create(mediaType, '{"data":[{"id":"740219868425748480","type":"RetailMediaAudience","attributes":{"name":"Audience made of CRM users list (new name)","description":"Simple audience made of a single segment of CRM list (new description)","retailerId":"1234","algebra":{"audienceSegmentId":"735693505849913344"}}},{"id":"740200271713996800","type":"RetailMediaAudience","attributes":{"name":"Audience of recent users from retailer not in CRM list (new name)","description":"Combination of segments from User Events but not in CRM list (new description)","retailerId":"4567","algebra":{"and":[{"or":[{"audienceSegmentId":"738406687217913856"},{"audienceSegmentId":"738406688413290496"}]},{"not":{"audienceSegmentId":"735693505849913344"}}]}}}]}');
Request request = new Request.Builder()
  .url("https://api.criteo.com/preview/retail-media/accounts/625702934721171442/audiences")
  .method("PATCH", body)
  .addHeader("Content-Type", "application/json")
  .addHeader("Accept", "application/json")
  .addHeader("Authorization", "Bearer <TOKEN>")
  .build();
Response response = client.newCall(request).execute();
<?php
require_once 'HTTP/Request2.php';
$request = new HTTP_Request2();
$request->setUrl('https://api.criteo.com/preview/retail-media/accounts/625702934721171442/audiences');
$request->setMethod(HTTP_Request2::METHOD_PATCH);
$request->setConfig(array(
  'follow_redirects' => TRUE
));
$request->setHeader(array(
  'Content-Type' => 'application/json',
  'Accept' => 'application/json',
  'Authorization' => 'Bearer <TOKEN>'
));
$request->setBody('{"data":[{"id":"740219868425748480","type":"RetailMediaAudience","attributes":{"name":"Audience made of CRM users list (new name)","description":"Simple audience made of a single segment of CRM list (new description)","retailerId":"1234","algebra":{"audienceSegmentId":"735693505849913344"}}},{"id":"740200271713996800","type":"RetailMediaAudience","attributes":{"name":"Audience of recent users from retailer not in CRM list (new name)","description":"Combination of segments from User Events but not in CRM list (new description)","retailerId":"4567","algebra":{"and":[{"or":[{"audienceSegmentId":"738406687217913856"},{"audienceSegmentId":"738406688413290496"}]},{"not":{"audienceSegmentId":"735693505849913344"}}]}}}]}');
try {
  $response = $request->send();
  if ($response->getStatus() == 200) {
    echo $response->getBody();
  }
  else {
    echo 'Unexpected HTTP status: ' . $response->getStatus() . ' ' .
    $response->getReasonPhrase();
  }
}
catch(HTTP_Request2_Exception $e) {
  echo 'Error: ' . $e->getMessage();
}

Sample Response

{
    "data": [
        {
            "id": "740219868425748480",
            "type": "RetailMediaAudience",
            "attributes": {
                "accountId": "625702934721171442",
                "name": "Audience made of CRM users list (new name)",
                "description": {
      					  "value": "Simple audience made of a single segment of CRM list (new description)"
   					 	  },
                "createdById": "514277",
                "createdAt": "2025-08-04T14:49:29.04Z",
                "updatedAt": "2025-08-04T14:54:20.38Z",
                "channels": [
                    "Onsite",
                    "Offsite"
                ],
                "algebra": {
                    "audienceSegmentId": "735693505849913344"
                }
            }
        },
        {
            "id": "740200271713996800",
            "type": "RetailMediaAudience",
            "attributes": {
                "accountId": "625702934721171442",
                "name": "Audience of recent users from retailer not in CRM list (new name)",
                "description": {
      					  "value": "Combination of segments from User Events but not in CRM list (new description)"
   					 	  },
                "retailerId": "4567",
                "createdById": "514277",
                "createdAt": "2025-08-04T13:31:36.84Z",
                "updatedAt": "2025-08-04T14:54:20.38Z",
                "channels": [
                    "Offsite"
                ],
                "algebra": {
                    "and": [
                        {
                            "or": [
                                {
                                    "audienceSegmentId": "738406687217913856"
                                },
                                {
                                    "audienceSegmentId": "738406688413290496"
                                }
                            ]
                        },
                        {
                            "not": {
                                "audienceSegmentId": "735693505849913344"
                            }
                        }
                    ]
                }
            }
        }
    ],
    "warnings": [],
    "errors": []
}

Delete Audiences

This endpoint enables clients to delete one or multiple audiences in a single request.

https://api.criteo.com/preview/retail-media/accounts/{account-id}/audiences/delete

Sample Request

curl -L -X POST 'https://api.criteo.com/preview/retail-media/accounts/625702934721171442/audiences/delete' \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'Authorization: Bearer <MY_ACCESS_TOKEN>' \
-d '{
  "data": [
    {
      "id": "740197499249692672",
      "type": "RetailMediaAudience",
      "attributes": {}
    }
  ]
}'
import http.client
import json
conn = http.client.HTTPSConnection("api.criteo.com")
payload = json.dumps({
  "data": [
    {
      "id": "740197499249692672",
      "type": "RetailMediaAudience",
      "attributes": {}
    },
    {
      "id": "740206991503921152",
      "type": "RetailMediaAudience",
      "attributes": {}
    }
  ]
})
headers = {
  'Content-Type': 'application/json',
  'Accept': 'application/json',
  'Authorization': 'Bearer <TOKEN>'
}
conn.request("POST", "/preview/retail-media/accounts/625702934721171442/audiences/delete", payload, headers)
res = conn.getresponse()
data = res.read()
print(data.decode("utf-8"))
OkHttpClient client = new OkHttpClient().newBuilder()
  .build();
MediaType mediaType = MediaType.parse("application/json");
RequestBody body = RequestBody.create(mediaType, '{"data":[{"id":"740197499249692672","type":"RetailMediaAudience","attributes":{}},{"id":"740206991503921152","type":"RetailMediaAudience","attributes":{}}],"warnings":[],"errors":[]}');
Request request = new Request.Builder()
  .url("https://api.criteo.com/preview/retail-media/accounts/625702934721171442/audiences/delete")
  .method("POST", body)
  .addHeader("Content-Type", "application/json")
  .addHeader("Accept", "application/json")
  .addHeader("Authorization", "Bearer <TOKEN>")
  .build();
Response response = client.newCall(request).execute();
<?php
require_once 'HTTP/Request2.php';
$request = new HTTP_Request2();
$request->setUrl('https://api.criteo.com/preview/retail-media/accounts/625702934721171442/audiences/delete');
$request->setMethod(HTTP_Request2::METHOD_POST);
$request->setConfig(array(
  'follow_redirects' => TRUE
));
$request->setHeader(array(
  'Content-Type' => 'application/json',
  'Accept' => 'application/json',
  'Authorization' => 'Bearer <TOKEN>'
));
$request->setBody('{"data":[{"id":"740197499249692672","type":"RetailMediaAudience","attributes":{}},{"id":"740206991503921152","type":"RetailMediaAudience","attributes":{}}],"warnings":[],"errors":[]}');
try {
  $response = $request->send();
  if ($response->getStatus() == 200) {
    echo $response->getBody();
  }
  else {
    echo 'Unexpected HTTP status: ' . $response->getStatus() . ' ' .
    $response->getReasonPhrase();
  }
}
catch(HTTP_Request2_Exception $e) {
  echo 'Error: ' . $e->getMessage();
}

Sample Response (200)

{
    "data": [
        {
            "id": "740197499249692672",
            "type": "RetailMediaAudience",
            "attributes": {}
        }
    ],
    "warnings": [],
    "errors": []
}

Responses

Responses

Description

🔵

200

Success. All audiences operations were performed successfully; some warnings/errors may be returned inline.

🔴

400

Bad request. Check request body formatting or missing required parameters.

🔴

401

Authentication error. Verify the API token.

🔴

403

Forbidden. The API client is not authorized to access this resource.


Errors and warnings

Request Structure Errors

empty-data-object

Error: Cannot have an empty data object
Message: The request must have at least one element in the data object.


empty-attributes-object

Error: Cannot have an empty attributes object
Message: The request must have the attributes object provided.


non-parsable-id

Error: One or more IDs cannot be parsed
Message: All IDs in the audience object must be a valid numerical ID.


duplicate-id

Error: Audience ID cannot be duplicated
Message: The data object must not have multiple audience objects with the same ID.


invalid-audience-type

Error: Audience type is invalid
Message: abcdef is not a valid audience type.


payload-too-big

Error: Cannot create more than 10 audiences at a time
Message: Each request must have at most 10 audience objects.


multiple-algebra-operators

Error: Cannot have an algebra node with multiple operators defined
Message: Each algebra node must have exactly one operator defined.


audience-algebra-cannot-be-null-or-empty

Error: Algebra cannot be null or empty
Message: You must provide a definition for the algebra.


audience-algebra-too-deep

Error: Audience algebra too deep
Message: The audience algebra tree cannot have a depth greater than 10.


audience-algebra-has-too-many-segments

Error: Audience algebra has too many segments
Message: The audience algebra can include at most 10 segments defined inside.


Validation Errors

duplicate-name

Error: Cannot have duplicated audience names
Message: Each audience in the request must have a unique name.


name-must-not-be-empty

Error: Audience name property must not be empty
Message: Cannot have an empty name in a create audience entity.


name-must-not-be-too-long

Error: Audience name property must not be too long
Message: Audience names must be no longer than 10 characters.


name-must-be-unique

Error: Audience name must be unique
Message: Another audience exists with the name: abcdef.


audiences-limit-reached

Error: Too many audiences
Message: Advertiser(s) 30, 40 have reached the number of allowed audiences.


audience-algebra-must-be-limited

Error: Audience algebra must be limited
Message: The audience algebra does not limit the amount of users it targets.


audience-algebra-and-or-nodes-must-include-more-than-one-node

Error: "And"/"or" nodes must include more than one node
Message: The audience algebra "and" and "or" nodes must include more than one node, otherwise use an audienceSegmentId node.


audience-channel-must-be-valid

Error: Audience channel must be valid
Message: The audience's algebra contains incompatible segment channels.


audience-channel-must-match-line-item-channel

Error: Audience channel must match line item channel
Message: Your audience algebra contains segments which are incompatible with one or more line items.


audience-retailer-must-match-segment-retailers

Error: Audience retailer must match segment retailers
Message: The segments: 30, 40 don't match the audience retailer. You must include only segments with the same retailer as the audience.


audience-must-contain-only-existing-segments

Error: Audience must contain only existing segments
Message: The segments: 30, 40 don't exist. You must include only existing segments.


audience-must-not-be-used-in-line-item

Error: Audience must not be used in a line item
Message: The audience must be removed from all line items to be able to delete it.


Account & Retailer Errors

account-must-exist

Error: Account must exist
Message: The account used must exist.


account-must-be-active

Error: Account must be active
Message: The account used must be active.


account-must-be-supply

Error: Account must be supply
Message: The account used must be a supply account.


retailer-must-be-authorized

Error: Retailer must be authorized
Message: The retailer associated with the account must be authorized.


retailer-must-be-live

Error: Retailer must be live
Message: The retailer used must be live.


Pagination Errors

pagination-is-required

Error: Pagination is required
Message: Pagination is required when no entity IDs are provided in the filters.


pagination-limit-cannot-be-zero

Error: Pagination limit cannot be zero
Message: Pagination limit must be greater than 0 when offset is positive.


pagination-limit-invalid

Error: Pagination limit is invalid
Message: Pagination limit must be a positive number lower than 10 (current limit set to 10).


pagination-offset-invalid

Error: Pagination offset is invalid
Message: Pagination offset must be a positive number.