Audience Segments Endpoints

Introduction

Audience Segments represent groups of users, defined either explicitly through Contact Lists provided externally or by User Events intent behaviors automatically collected through our retailers integrations.

Multiple Audience Segments can be combined using logical Algebra Nodes to define the desired target audience for your campaigns.

📘
About Audience Segments in Preview
The Audience Segment endpoints documented here are part of the 2025 Preview versionof the Retail Media API. Only the create, update, and delete endpoints are included because they now support event-based targeting, which is not available in the stable API.
Other endpoints (e.g., search, contact-list management) remain unchanged and are documented in the stable version of 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.

📘
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 warnings section of the response with an error code and details.
Examples of possible warning codes:

segment-not-found → Segment is not found.

name-must-be-unique → Segment name must be unique.

name-must-not-be-empty → Segment name property must not be empty.

This list is not exhaustive. Additional warnings may be returned depending on the request context.

Endpoints

Verb	Endpoint	Description
POST	`/accounts/{accountId}/audience-segments/create`	Create a new Audience Segment
PATCH	`/accounts/{accountId}/audience-segments`	Update an Audience Segment
POST	`/accounts/{accountId}/audience-segments/delete`	Delete an Audience Segment

Audience Segment Attributes

Attribute	Data Type	Description
`id` / `audienceSegmentId`	string	Audience Segment ID, generated internally by Criteo Accepted values: string of int64 Writeable? N / Nullable? N
`name`*	string	Audience Segment name Accepted values: string Writeable? Y / Nullable? N
`description`	string	Description of the Audience Segment Accepted values: string Writeable? Y / Nullable? N
`accountId`	string	Account ID associated with the Audience Segment, 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
`type`	enum	Type of segment Accepted values: * `ContactList`: users segment defined by list of contact identifiers, manageable by the other endpoints * `Events`: users segment defined by a combination of events collected in the retailer's environment Writeable? Y / Nullable? N
`contactList`	object	Setting to target users with contact list. Note, either one of `contactList` or `events` is required, however both cannot be leveraged at the same time See below for more details
`events`	object	Settings to target users based on their events. Note, either one of `contactList` or `events` is required, however both cannot be leveraged at the same time See below for more details
`createdAt`	timestamp	Timestamp of Audience Segment 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 Segment (`null` if created by a service) Accepted values: string Writeable? N / Nullable? Y
`updatedAt`	timestamp	Timestamp of last Audience Segment update, in UTC Accepted values: `yyyy-mm-ddThh:mm:ss.msZ`(in ISO-8601) Writeable? N / Nullable? N
`channels`	list	Channels associated to the audience Accepted values: `Onsite`, `Offsite`, `Unknown` Writeable? N / Nullable? N

* Required at create operation

📘
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.

Contact List Segment Attributes

Attribute	Data Type	Description
`isReadOnly`	boolean	Indicates if the contact list can be edited Accepted values: `true`, `false` Writeable? N / Nullable? N
`identifierType`	enum	User identifier type from Contact list Accepted values: `Email`, `UserIdentifier`, `IdentityLink`, `CustomerId`, `Unknown` Writeable? N / Nullable? N

📘
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.

Events Segment Attributes

Attribute	Data Type	Description
`shopperActivity`*	enum	Activity type performed by the desired target users in the retailer's environment Accepted values: `View`, `Buy`, `AddToCart`, `Unknown` Writeable? Y / Nullable? N
`lookbackDays`*	enum	Timeframe of the interaction performed by the desired target users in the retailer's environment Accepted values: `Last7Days`, `Last14Days`, `Last30Days`, `Last45Days`, `Last60Days`, `Last90Days`, `Last120Days`, `Last150Days`, `Last180Days` Writeable? Y / Nullable? N
`categoryIds`	list	Define users interested in specific categories using Search Category. Note, either one of `categoryIds` or `brandIds` must be included. Both can be included as well, but the request will fail if neither are included. See the dedicated section right below for more details. Accepted values: array of strings/int64 Writeable? Y / Nullable? Y
`brandIds`	list	Define users who performed the activity type above in specific brands. Note, either one of `categoryIds` or `brandIds` must be included. Both can be included as well, but the request will fail if neither are included. See the dedicated section right below for more details. Accepted values: array of strings/int64 Writeable? Y / Nullable? Y
`minPrice`	decimal	Define users who interact with products whose prices are greater than `minPrice` Accepted values: `minPrice` ≥ 0.0 (or `null`) Writeable? Y / Nullable? Y
`maxPrice`	decimal	Define users who interact with products whose prices are smaller than `maxPrice` Accepted values: `maxPrice` ≥ 0.0 (or `null`) Writeable? Y / Nullable? Y

* Required at create operation

📘
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.

Sourcing Category and Brand IDs

To populate the categoryId and brandId attributes when creating or updating audience segments, use the following endpoints:

`categoryID`

Use the Search Categories endpoint to find category IDs relevant to your campaign. This method offers a faster lookup than navigating the full product catalog.

`brandID`

Two endpoints should be used together to accurately source brandId:

/brands/search – retrieves all available brands.
/accounts/{accountId}/brands – retrieves only the brands mapped to a specific account.

To avoid targeting conflicts, ensure that the brandId used is mapped to the account associated with the audience segment. A best practice is to cross-reference both the brandId and the intended retailerId to verify eligibility for targeting.

Create Audience Segment

This endpoint allows creating Audience Segments, either from Contact List or Users Events type.

⚠️
The corresponding App should have the "Audiences Manage" permission enabled.

https://api.criteo.com/{version}/retail-media/accounts/{accountId}/audience-segments/create

Sample Request:

curl -L -X POST 'https://api.criteo.com/{version}/retail-media/accounts/625702934721171442/audience-segments/create' \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'Authorization: Bearer <MY_ACCESS_TOKEN>' \
-d '{
  "data": [
    {
      "type": "AudienceSegment",
      "attributes": {
        "name": "CRM Users 2025",
        "description": "Segment made of CRM user emails",
        "retailerId": "1234",
        "contactList": {
          "identifierType": "Email"
        }
      }
    },
    {
      "type": "AudienceSegment",
      "attributes": {
        "name": "Buyers Last 7D Brand ABC",
        "description": "Segment of buyer users of brand ABC in the last 7 days",
        "retailerId": "1234",
        "events": {
          "shopperActivity": "Buy",
          "lookbackDays": "Last7Days",
          "brandIds": [
            "123456"
          ]
        }
      }
    }
  ]
}'

import http.client
import json
conn = http.client.HTTPSConnection("api.criteo.com")
payload = json.dumps({
  "data": [
    {
      "type": "AudienceSegment",
      "attributes": {
        "name": "CRM Users 2025",
        "description": "Segment made of CRM user emails",
        "retailerId": "1234",
        "contactList": {
          "identifierType": "Email"
        }
      }
    },
    {
      "type": "AudienceSegment",
      "attributes": {
        "name": "Buyers Last 7D Brand ABC",
        "description": "Segment of buyer users of brand ABC in the last 7 days",
        "retailerId": "1234",
        "events": {
          "shopperActivity": "Buy",
          "lookbackDays": "Last7Days",
          "brandIds": [
            "123456"
          ]
        }
      }
    }
  ]
})
headers = {
  'Content-Type': 'application/json',
  'Accept': 'application/json',
  'Authorization': 'Bearer <TOKEN>'
}
conn.request("POST", "/{version}/retail-media/accounts/625702934721171442/audience-segments/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":[{"type":"AudienceSegment","attributes":{"name":"CRM Users 2025","description":"Segment made of CRM user emails","retailerId":"1234","contactList":{"identifierType":"Email"}}},{"type":"AudienceSegment","attributes":{"name":"Buyers Last 7D Brand ABC","description":"Segment of buyer users of brand ABC in the last 7 days","retailerId":"1234","events":{"shopperActivity":"Buy","lookbackDays":"Last7Days","brandIds":["123456"]}}}]}');
Request request = new Request.Builder()
  .url("https://api.criteo.com/{version}/retail-media/accounts/625702934721171442/audience-segments/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/{version}/retail-media/accounts/625702934721171442/audience-segments/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":[{"type":"AudienceSegment","attributes":{"name":"CRMUsers2025","description":"SegmentmadeofCRMuseremails","retailerId":"1234","contactList":{"identifierType":"Email"}}},{"type":"AudienceSegment","attributes":{"name":"BuyersLast7DBrandABC","description":"SegmentofbuyerusersofbrandABCinthelast7days","retailerId":"1234","events":{"shopperActivity":"Buy","lookbackDays":"Last7Days","brandIds":["123456"]}}}]}');
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": "738406687217913856",
            "type": "RetailMediaAudienceSegment",
            "attributes": {
                "accountId": "625702934721171442",
                "name": "Buyers Last 7D Brand ABC",
                "description": "Segment of buyer users of brand ABC in the last 7 days",
                "retailerId": "1234",
                "type": "Events",
                "createdAt": "2025-07-30T14:44:32.81Z",
                "updatedAt": "2025-07-30T14:44:32.81Z",
                "createdById": "514277",
                "events": {
                    "shopperActivity": "Buy",
                    "lookbackDays": "Last7Days",
                    "categoryIds": [],
                    "brandIds": [
                        "123456"
                    ],
                    "minPrice": null,
                    "maxPrice": null
                },
                "channels": [
                    "Onsite",
                    "Offsite"
                ]
            }
        },
        {
            "id": "738406688413290496",
            "type": "RetailMediaAudienceSegment",
            "attributes": {
                "accountId": "625702934721171442",
                "name": "CRM Users 2025",
                "description": "Segment made of CRM user emails",
                "retailerId": "1234",
                "type": "ContactList",
                "createdAt": "2025-07-30T14:44:32.81Z",
                "updatedAt": "2025-07-30T14:44:32.81Z",
                "createdById": "514277",
                "contactList": {
                    "isReadOnly": false,
                    "identifierType": "Email",
                    "sharingStatus": "NotShared"
                },
                "channels": [
                    "Offsite"
                ]
            }
        }
    ],
    "warnings": [],
    "errors": []
}

Update Audience Segment

This endpoint allows updating Audience Segments, either from Contact List or Users Events type.

⚠️
The corresponding App should have the "Audiences Manage" permission enabled.

📘
For Contact List segments, it's possible to update their metadata (name and description) but not their identity types. For those cases, please create a new segment with the new desired identifier type.

https://api.criteo.com/{version}/retail-media/accounts/{accountId}/audience-segments

Sample Request

curl -L -X PATCH 'https://api.criteo.com/{version}/retail-media/accounts/625702934721171442/audience-segments' \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'Authorization: Bearer <MY_ACCESS_TOKEN>' \
-d '{
  "data": [
    {
      "id": "738406688413290496",
      "type": "AudienceSegment",
      "attributes": {
        "name": "CRM User E-mails 2025 ",
        "description": "Segment made of CRM user e-mails",
        "retailerId": "1234",
        "contactList": {
          "identifierType": "Email"
        }
      }
    },
    {
      "id": "738406687217913856",
      "type": "AudienceSegment",
      "attributes": {
        "name": "Cart Abandoned Last 7D Brand ABC",
        "description": "Segment of cart users with brand ABC in the last 7 days",
        "retailerId": "1234",
        "events": {
          "shopperActivity": "AddToCart",
          "lookbackDays": "Last7Days",
          "brandIds": [
            "123456"
          ]
        }
      }
    }
  ]
}'

import http.client
import json
conn = http.client.HTTPSConnection("api.criteo.com")
payload = json.dumps({
  "data": [
    {
      "id": "738406688413290496",
      "type": "AudienceSegment",
      "attributes": {
        "name": "CRM User E-mails 2025 ",
        "description": "Segment made of CRM user e-mails",
        "retailerId": "1234",
        "contactList": {
          "identifierType": "Email"
        }
      }
    },
    {
      "id": "738406687217913856",
      "type": "AudienceSegment",
      "attributes": {
        "name": "Cart Abandoned Last 7D Brand ABC",
        "description": "Segment of cart users with brand ABC in the last 7 days",
        "retailerId": "1234",
        "events": {
          "shopperActivity": "AddToCart",
          "lookbackDays": "Last7Days",
          "brandIds": [
            "123456"
          ]
        }
      }
    }
  ]
})
headers = {
  'Content-Type': 'application/json',
  'Accept': 'application/json',
  'Authorization': 'Bearer <TOKEN>'
}
conn.request("PATCH", "/{version}/retail-media/accounts/625702934721171442/audience-segments", 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":"738406688413290496","type":"AudienceSegment","attributes":{"name":"CRM User E-mails 2025","description":"Segment made of CRM user e-mails","retailerId":"1234","contactList":{"identifierType":"Email"}}},{"id":"738406687217913856","type":"AudienceSegment","attributes":{"name":"Cart Abandoned Last 7D Brand ABC","description":"Segment of cart users with brand ABC in the last 7 days","retailerId":"1234","events":{"shopperActivity":"AddToCart","lookbackDays":"Last7Days","brandIds":["123456"]}}}]}');
Request request = new Request.Builder()
  .url("https://api.criteo.com/{version}/retail-media/accounts/625702934721171442/audience-segments")
  .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/{version}/retail-media/accounts/625702934721171442/audience-segments');
$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":"738406688413290496","type":"AudienceSegment","attributes":{"name":"CRM User E-mails 2025","description":"Segment made of CRM user e-mails","retailerId":"1234","contactList":{"identifierType":"Email"}}},{"id":"738406687217913856","type":"AudienceSegment","attributes":{"name":"Cart Abandoned Last 7D Brand ABC","description":"Segment of cart users with brand ABC in the last 7 days","retailerId":"1234","events":{"shopperActivity":"AddToCart","lookbackDays":"Last7Days","brandIds":["123456"]}}}]}');
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": "738406687217913856",
            "type": "RetailMediaAudienceSegment",
            "attributes": {
                "accountId": "4",
                "name": "Cart Abandoned Last 7D Brand ABC",
                "description": "Segment of cart users with brand ABC in the last 7 days",
                "retailerId": "1234",
                "type": "Events",
                "createdAt": "2025-07-30T14:44:32.81Z",
                "updatedAt": "2025-07-30T15:14:19.3566667Z",
                "createdById": "514277",
                "events": {
                    "shopperActivity": "AddToCart",
                    "lookbackDays": "Last7Days",
                    "categoryIds": [],
                    "brandIds": [
                        "123456"
                    ],
                    "minPrice": null,
                    "maxPrice": null
                },
                "channels": [
                    "Onsite",
                    "Offsite"
                ]
            }
        },
        {
            "id": "738406688413290496",
            "type": "RetailMediaAudienceSegment",
            "attributes": {
                "accountId": "4",
                "name": "CRM User E-mails 2025",
                "description": "Segment made of CRM user e-mails",
                "retailerId": "1234",
                "type": "ContactList",
                "createdAt": "2025-07-30T14:44:32.81Z",
                "updatedAt": "2025-07-30T15:14:19.3566667Z",
                "createdById": "514277",
                "contactList": {
                    "isReadOnly": false,
                    "identifierType": "Email",
                    "sharingStatus": "NotShared"
                },
                "channels": [
                    "Offsite"
                ]
            }
        }
    ],
    "warnings": [],
    "errors": []
}

Delete Audience Segment

This endpoint allows deleting Audience Segments, either one by one or multiple of them.

⚠️
The corresponding App should have the "Audiences Manage" permission enabled.

https://api.criteo.com/{version}/retail-media/accounts/{accountId}/audience-segments/delete

Sample request

curl -L -X POST 'https://api.criteo.com/{version}/retail-media/accounts/625702934721171442/audience-segments/delete' \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'Authorization: Bearer <MY_ACCESS_TOKEN>' \
-d '{
  "data": [
    {
      "id": "738406561971802112"
    }
  ]
}'

import http.client
import json
conn = http.client.HTTPSConnection("api.criteo.com")
payload = json.dumps({
  "data": [
    {
      "id": "738406561971802112"
    }
  ]
})
headers = {
  'Content-Type': 'application/json',
  'Accept': 'application/json',
  'Authorization': 'Bearer <TOKEN>'
}
conn.request("POST", "/{version}/retail-media/accounts/625702934721171442/audience-segments/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":"225702933721171456"}]}');
Request request = new Request.Builder()
  .url("https://api.criteo.com/{version}/retail-media/accounts/625702934721171442/audience-segments/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/{version}/retail-media/accounts/625702934721171442/audience-segments/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":"225702933721171456"}]}');
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": "738406561971802112",
            "type": "RetailMediaAudienceSegment",
            "attributes": {}
        }
    ],
    "warnings": [],
    "errors": []
}

Partial `200 OK` response

⚠️
Audience Segments cannot be deleted once they have served impressions. Attempts to delete them will return 200 OK but include a warning indicating the segment must first be removed from all audiences.
Please note that this is not the only use case that might return a partial 200 OK response.

{
    "data": [],
    "warnings": [],
    "errors": [
        {
            "traceId": "0ab8cdc52e17ecfd1ba9e5d1dacd102a",
            "traceIdentifier": "0ab8cdc52e17ecfd1ba9e5d1dacd102a",
            "type": "validation",
            "code": "segment-must-not-be-used-in-audience",
            "instance": "@data/0",
            "title": "Segment must not be used in an audience",
            "detail": "The segment must be removed from all audiences to be able to delete it"
        }
    ]
}

Audience Segments Endpoints

Introduction

📘
About Audience Segments in Preview

⚠️
Note on Audience Computation

📘
Partial Approvals

Endpoints

Audience Segment Attributes

📘
Field Definitions

Contact List Segment Attributes

📘
Field Definitions

Events Segment Attributes

📘
Field Definitions

Sourcing Category and Brand IDs

`categoryID`

`brandID`

Create Audience Segment

⚠️

Update Audience Segment

⚠️

📘

Delete Audience Segment

⚠️

Partial `200 OK` response

⚠️

Introduction

📘About Audience Segments in Preview

⚠️Note on Audience Computation

📘Partial Approvals

Endpoints

Audience Segment Attributes

📘Field Definitions

Contact List Segment Attributes

📘Field Definitions

Events Segment Attributes

📘Field Definitions

Sourcing Category and Brand IDs

categoryID

brandID

Create Audience Segment

⚠️

Update Audience Segment

⚠️

📘

Delete Audience Segment

⚠️

Partial 200 OK response

⚠️

📘
About Audience Segments in Preview

⚠️
Note on Audience Computation

📘
Partial Approvals

📘
Field Definitions

📘
Field Definitions

📘
Field Definitions

`categoryID`

`brandID`

Partial `200 OK` response