GuidesAPI ReferenceChangelog
GuidesAPI ReferenceChangelog
GuidesAPI ReferenceChangelogLog In
Guides

Audiences Endpoints

Suggest Edits

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.

📘

The endpoints and functionalities covered in this page refers to features available exclusively in Preview for now, which doesn't mean that 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

Endpoint

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

AttributeData TypeDescription
idstringAudience ID, generated internally by Criteo

Accepted values: string of int64
Writeable? N / Nullable? N
name*stringAudience name, arbitrary and changeable. Must be unique in the account level.

Accepted values: up to 256 chars string
Writeable? Y / Nullable? N
descriptionstringAudience description, arbitrary and changeable.

Accepted values: up to 500 chars string
Writeable? Y / Nullable? Y
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, generated internally by Criteo. Once created, the associated retailer cannot be changed

Accepted values: string of int64
Writeable? N / Nullable? N
algebra*objectAlgebra 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
channelslistChannels associated to the audience

Accepted values: Onsite, Offsite, Unknown
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 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": "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" 
              }
            }
          ]
        }
      }
    }
  ]
}'

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": "Simple audience made of a single segment of CRM list (new description)",
                "retailerId": "1234",
                "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": "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": {}
    },
    {
      "id": "740206991503921152",
      "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": {}
        },
        {
            "id": "740206991503921152",
            "type": "RetailMediaAudience",
            "attributes": {}
        }
    ],
    "warnings": [],
    "errors": []
}

Responses

ResponsesDescription
🔵 200Success. All audiences operations were performed successfully; some warnings/errors may be returned inline.
🔴 400Bad request. Check request body formatting or missing required parameters.
🔴 401Authentication error. Verify the API token.
🔴 403Forbidden. The API client is not authorized to access this resource.

Updated 1 day ago