Audience Segment Endpoints

Introduction

Audience Segments represent groups of users, defined through Contact Lists provided externally. Multiple Audience Segments can be combined using logical Algebra Nodes to define the desired target audience for your campaigns.

Partial ApprovalsBulk 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.

Note on event-based targetingEvent-based targeting is currently not supported in the Stable version of this API.
For event-based targeting, please refer to the Preview documentation.

Note on Audience ComputationAudience 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}/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
POST	`/accounts/{accountId}/audience-segments/search`	Search for Audience Segments by segment IDs, retailer IDs and/or segment types
GET	`/accounts/{accountId}/audience-segments/{audienceSegmentId}/contact-list`	Retrieve contact list statistics
POST	`/audience-segments/{audienceSegmentId}/contact-list/add-remove`	Add/remove identifiers in contact list Audience Segment
POST	`/audience-segments/{audienceSegmentId}/contact-list/clear`	Clear all identifiers in contact list 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	AccountID associated with the Audience Segment, generated internally by Criteo Accepted values: string of int64 Writeable? N / Nullable? N
`retailerId`*	string	RetailerID, 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 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
`createdAt`	timestamp	Timestamp of Audience Segment creation, in UTC Accepted values:`yyyy-mm-ddThh:mm:ss.msZ`(inISO-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`(inISO-8601) Writeable? N / Nullable? N
`channels`	list`<enum>`	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

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.

Create Audience Segment

This endpoint allows creating Audience Segments from Contact List.

The corresponding App should have the “Audiences Manage” permission enabled.

As of now, it is only possible to create Contact List segments through our API. For Users Events Segments, users can rely on the C-Max UI - for more details, check (Onsite Display) Build an Audience

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"
        }
      }
    },
  ]
}'

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"
        }
      }
    },
  ]
})
headers = {
  'Content-Type': 'application/json',
  'Accept': 'application/json',
  'Authorization': 'Bearer &lt;TOKEN&gt;'
}
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\"}}}]}");
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 &lt;TOKEN&gt;")
  .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 &lt;TOKEN&gt;'
));
$request->setBody('{"data":[{"type":"AudienceSegment","attributes":{"name":"CRM Users 2025","description":"Segment made of CRM user emails","retailerId":"1234","contactList":{"identifierType":"Email"}}}]}');
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": "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 Segmentsfrom Contact List. Note: 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, create a new segment with the new desired identifier type.

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"
        }
      }
    }
  ]
}'

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"
        }
      }
    }
  ]
})
headers = {
  'Content-Type': 'application/json',
  'Accept': 'application/json',
  'Authorization': 'Bearer &lt;TOKEN&gt;'
}
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\"}}}]}"
);
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 &lt;TOKEN&gt;")
  .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 &lt;TOKEN&gt;'
));
$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"}}}]}');
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": "738406688413290496",
            "type": "RetailMediaAudienceSegment",
            "attributes": {
                "accountId": "4",
                "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-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.

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 &lt;TOKEN&gt;'
}
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 &lt;TOKEN&gt;")
  .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 &lt;TOKEN&gt;'
));
$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.

{
    "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"
        }
    ]
}

Search for Audience Segments

This endpoint allows searching for existing Audience Segments that satisfy one or multiple attributes at the same time. Results are paginated using offset and limit query parameters; if omitted, defaults to 0 and 500, respectively. See API Response. Sample Request:

curl -L -X POST 'https://api.criteo.com/{version}/retail-media/accounts/625702934721171442/audience-segments/search?limit=50&offset=0' \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'Authorization: Bearer <MY_ACCESS_TOKEN>' \
-d '{
  "data": {
    "type": "AudienceSegment",
    "attributes": {
    "audienceSegmentIds": null,
    "retailerIds": [
      "12"
    ],
    "audienceSegmentTypes": [
      "ContactList",
      "Events"
    ]
  }
}'

import http.client
import json
conn = http.client.HTTPSConnection("api.criteo.com")
payload = json.dumps({
{
  "data": {
    "type": "AudienceSegment",
    "attributes": {
      "audienceSegmentIds": None
      "retailerIds": [
        "12"
      ],
      "audienceSegmentTypes": [
        "ContactList",
        "Events"
      ]
    }
  }
}
headers = {
  'Content-Type': 'application/json',
  'Accept': 'application/json',
  'Authorization': 'Bearer &lt;TOKEN&gt;'
}
conn.request("POST", "/{version}/retail-media/accounts/625702934721171442/audience-segments/search?limit=50&offset=0", 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":{"audienceSegmentIds":null,"retailerIds":["12"],"audienceSegmentTypes":["ContactList","Events"]}}}');
Request request = new Request.Builder()
  .url("https://api.criteo.com/{version}/retail-media/accounts/625702934721171442/audience-segments/search?limit=50&offset=0")
  .method("POST", body)
  .addHeader("Content-Type", "application/json")
  .addHeader("Accept", "application/json")
  .addHeader("Authorization", "Bearer &lt;TOKEN&gt;")
  .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/search?limit=50&offset=0');
$request->setMethod(HTTP_Request2::METHOD_POST);
$request->setConfig(array(
  'follow_redirects' => TRUE
));
$request->setHeader(array(
  'Content-Type' => 'application/json',
  'Accept' => 'application/json',
  'Authorization' => 'Bearer &lt;TOKEN&gt;'
));
$request->setBody('{"data":{"type":"AudienceSegment","attributes":{"audienceSegmentIds":null,"retailerIds":["12"],"audienceSegmentTypes":["ContactList","Events"]}}}');
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

{
    "meta": {
        "totalItems": 400,
        "limit": 50,
        "offset": 0
    },
    "data": [
        {
            "id": "203134567785554216",
            "type": "AudienceSegment",
            "attributes": {
                "name": "Segment Name",
                "type": "Events",
                "createdAt": "2024-01-15T12:23:18.180Z",
                "updatedAt": "2024-01-15T12:23:18.180Z",
                "accountId": "625702934721171442",
                "retailerId": "12",
                "events": {
                    "shopperActivity": "View",
                    "lookbackDays": "Last90Days",
                    "categoryIds": [
                        "3590922"
                    ],
                    "brandIds": []
                }
            }
        },
        // ...
        {
            "id": "225702933721171456",
            "type": "AudienceSegment",
            "attributes": {
                "name": "Segment Name",
                "type": "ContactList",
                "createdAt": "2024-01-23T09:33:40.822Z",
                "updatedAt": "2024-01-23T09:33:40.822Z",
                "accountId": "625702934721171442",
                "retailerId": "12",
                "contactList": {
                    "isReadOnly": "true",
                    "identifierType": "Email"
                }
            }
        }
    ],
    "errors": [],
    "warnings": []
}

Get Contact List Segment Statistics

This endpoint allows retrieving statistics from Contact List segments. Sample Request

curl -L -X GET 'https://api.criteo.com/{version}/retail-media/accounts/625702934721171442/audience-segments/225702933721171456/contact-list' \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'Authorization: Bearer <MY_ACCESS_TOKEN>'

import http.client
conn = http.client.HTTPSConnection("api.criteo.com")
headers = {
  'Accept': 'application/json',
  'Authorization': 'Bearer <MY_ACCESS_TOKEN>'
}
conn.request("GET", "/{version}/retail-media/accounts/625702934721171442/audience-segments/225702933721171456/contact-list",  headers)
res = conn.getresponse()
data = res.read()
print(data.decode("utf-8"))

OkHttpClient client = new OkHttpClient().newBuilder()
  .build();
MediaType mediaType = MediaType.parse("text/plain");
Request request = new Request.Builder()
  .url("https://api.criteo.com/{version}/retail-media/accounts/625702934721171442/audience-segments/225702933721171456/contact-list")
  .method("GET")
  .addHeader("Accept", "application/json")
  .addHeader("Authorization", "Bearer <MY_ACCESS_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/225702933721171456/contact-list');
$request->setMethod(HTTP_Request2::METHOD_GET);
$request->setConfig(array(
  'follow_redirects' => TRUE
));
$request->setHeader(array(
  'Accept' => 'application/json',
  'Authorization' => 'Bearer MY_ACCESS_TOKEN>'
));
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": "225702933721171456",
        "identifierType": "AudienceSegment",
        "attributes": {
            "numberOfIdentifiers": 10000,
            "numberOfMatches": 5000,
            "matchRate": 0.5
        }
    },
    "errors": [],
    "warnings": []
}

Add/Remove identifiers in Contact List Audience Segment

This endpoint allows to add/remove users in a specific Contact List segment. Note: the corresponding App should have the “Audiences Manage” permission enabled.

Attribute	Data Type	Description
`operation`	enum	Operation required for the sub-set of users provided in the request Accepted values:`add`,`remove` Writeable? N / Nullable? N

Attribute

Data Type

Description

operation

enum

Operation required for the sub-set of users provided in the request

Accepted values:add,remove

Writeable? N / Nullable? N

Sample Request - adding users to existing audience segment

curl -L -X POST 'https://api.criteo.com/{version}/retail-media/audience-segments/225702933721171456/contact-list/add-remove' \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'Authorization: Bearer <MY_ACCESS_TOKEN>' \
-d '{
  "data": {
    "type": "AddRemoveContactlist",
    "attributes": {
      "operation": "add",
      "identifierType": "email",
      "identifiers": [
        "abc@gmail.com",
        "def@gmail.com",
        "aef@gmail.com"
      ]
    }
  }
}'

import http.client
import json
conn = http.client.HTTPSConnection("api.criteo.com")
payload = json.dumps({
{
  "data": {
    "type": "AddRemoveContactlist",
    "attributes": {
      "operation": "add",
      "identifierType": "email",
      "identifiers": [
        "abc@gmail.com",
        "def@gmail.com",
        "aef@gmail.com",
      ]
    }
  }
}
headers = {
  'Content-Type': 'application/json',
  'Accept': 'application/json',
  'Authorization': 'Bearer &lt;TOKEN&gt;'
}
conn.request("POST", "/{version}/retail-media/audience-segments/225702933721171456/contact-list/add-remove", 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":"AddRemoveContactlist","attributes":{"operation":"add","identifierType":"email","identifiers":["abc@gmail.com","def@gmail.com","aef@gmail.com"]}}}');
Request request = new Request.Builder()
  .url("https://api.criteo.com/{version}/retail-media/audience-segments/225702933721171456/contact-list/add-remove")
  .method("POST", body)
  .addHeader("Content-Type", "application/json")
  .addHeader("Accept", "application/json")
  .addHeader("Authorization", "Bearer &lt;TOKEN&gt;")
  .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/audience-segments/225702933721171456/contact-list/add-remove');
$request->setMethod(HTTP_Request2::METHOD_POST);
$request->setConfig(array(
  'follow_redirects' => TRUE
));
$request->setHeader(array(
  'Content-Type' => 'application/json',
  'Accept' => 'application/json',
  'Authorization' => 'Bearer &lt;TOKEN&gt;'
));
$request->setBody('{"data":{"type":"AddRemoveContactlist","attributes":{"operation":"add","identifierType":"email","identifiers":["abc@gmail.com","def@gmail.com","aef@gmail.com"]}}}');
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": {
        "type": "AddRemoveContactlistResult",
        "attributes": {
            "contactListId": 523103620165619700,
            "operation": "add",
            "requestDate": "2024-04-22T14:29:07.994Z",
            "identifierType": "email",
            "nbValidIdentifiers": 3,
            "nbInvalidIdentifiers": 0,
            "sampleInvalidIdentifiers": []
        }
    },
    /* omitted if no errors */
    "errors": [],
    /* omitted if no warnings */
    "warnings": []
}

Sample Request - removing users from existing audience segment

curl -L -X POST 'https://api.criteo.com/{version}/retail-media/audience-segments/225702933721171456/contact-list/add-remove' \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'Authorization: Bearer <MY_ACCESS_TOKEN>' \
-d '{
  "data": {
    "type": "ContactlistAmendment",
    "attributes": {
      "operation": "remove",
      "identifierType": "email",
      "identifiers": [
        "example1@gmail.com"
      ]
    }
  }
}'

import http.client
import json
conn = http.client.HTTPSConnection("api.criteo.com")
payload = json.dumps({
{
  "data": {
    "type": "ContactlistAmendment",
    "attributes": {
        "operation": "remove",
        "identifierType": "email",
        "identifiers": [
            "example1@gmail.com"
        ]
    }
  }
}
headers = {
  'Content-Type': 'application/json',
  'Accept': 'application/json',
  'Authorization': 'Bearer &lt;TOKEN&gt;'
}
conn.request("POST", "/{version}/retail-media/audience-segments/225702933721171456/contact-list/add-remove", 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":"ContactlistAmendment","attributes":{"operation":"remove","identifierType":"email","identifiers":["example1@gmail.com"]}}}');
Request request = new Request.Builder()
  .url("https://api.criteo.com/{version}/retail-media/audience-segments/225702933721171456/contact-list/add-remove")
  .method("POST", body)
  .addHeader("Content-Type", "application/json")
  .addHeader("Accept", "application/json")
  .addHeader("Authorization", "Bearer &lt;TOKEN&gt;")
  .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/audience-segments/225702933721171456/contact-list/add-remove');
$request->setMethod(HTTP_Request2::METHOD_POST);
$request->setConfig(array(
  'follow_redirects' => TRUE
));
$request->setHeader(array(
  'Content-Type' => 'application/json',
  'Accept' => 'application/json',
  'Authorization' => 'Bearer &lt;TOKEN&gt;'
));
$request->setBody('{"data":{"type":"ContactlistAmendment","attributes":{"operation":"remove","identifierType":"email","identifiers":["example1@gmail.com"]}}}');
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": {
        "type": "ContactlistAmendment",
        "attributes": {
            "operation": "remove",
            "requestDate": "2018-12-10T10:00:50.000Z",
            "identifierType": "email",
            "nbValidIdentifiers": 7342,
            "nbInvalidIdentifiers": 13,
            "sampleInvalidIdentifiers": [
                "InvalidIdentifier"
            ]
        }
    },
    /* omitted if no errors */
    "errors": [],
    /* omitted if no warnings */
    "warnings": []
}

Identifier List Size LimitNote that there is a limit of 50,000 identifiers per single request. If you are adding more than 50,000 users, please split them into chunks of 50,000 and make multiple requests.

Clear all identifiers in Contact List Audience Segment

This endpoint resets a Contact List segment, erasing all existing users identifiers.

The corresponding App should have the “Audiences Manage” permission enabled.

Sample Request

curl -L -X POST 'https://api.criteo.com/{version}/retail-media/audience-segments/225702933721171456/contact-list/clear' \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'Authorization: Bearer <MY_ACCESS_TOKEN>'

import http.client

conn = http.client.HTTPSConnection("api.criteo.com")
payload = ''
headers = {
  'Accept': 'application/json',
  'Authorization': 'Bearer <MY_ACCESS_TOKEN>'
}
conn.request("POST", "/{version}/retail-media/audience-segments/225702933721171456/contact-list/clear", payload, headers)
res = conn.getresponse()
data = res.read()
print(data.decode("utf-8"))

OkHttpClient client = new OkHttpClient().newBuilder()
  .build();
MediaType mediaType = MediaType.parse("text/plain");
RequestBody body = RequestBody.create(mediaType, "");
Request request = new Request.Builder()
  .url("https://api.criteo.com/{version}/retail-media/audience-segments/225702933721171456/contact-list/clear")
  .method("POST", body)
  .addHeader("Accept", "application/json")
  .addHeader("Authorization", "Bearer <MY_ACCESS_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/audience-segments/225702933721171456/contact-list/clear');
$request->setMethod(HTTP_Request2::METHOD_POST);
$request->setConfig(array(
  'follow_redirects' => TRUE
));
$request->setHeader(array(
  'Accept' => 'application/json',
  'Authorization' => 'Bearer MY_ACCESS_TOKEN>'
));
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 🟢 201 Created (empty response body)

Note that this will only wipe all of the users from the audience segment and will not delete the audience segment itself.

Introduction

Getting Started

API Troubleshooting

Concepts

Resources

Guides for Retail Media API

Audience Segment Endpoints

Introduction

Endpoints

Audience Segment Attributes

Contact List Segment Attributes

Create Audience Segment

Update Audience Segment

Delete Audience Segment

Partial `200 OK` response

Search for Audience Segments

Get Contact List Segment Statistics

Add/Remove identifiers in Contact List Audience Segment

Clear all identifiers in Contact List Audience Segment

​Introduction

​Endpoints

​Audience Segment Attributes

​Contact List Segment Attributes

​Create Audience Segment

​Update Audience Segment

​Delete Audience Segment

​Partial 200 OK response

​Search for Audience Segments

​Get Contact List Segment Statistics

​Add/Remove identifiers in Contact List Audience Segment

​Clear all identifiers in Contact List Audience Segment

Introduction

Endpoints

Audience Segment Attributes

Contact List Segment Attributes

Create Audience Segment

Update Audience Segment

Delete Audience Segment

Partial `200 OK` response

Search for Audience Segments

Get Contact List Segment Statistics

Add/Remove identifiers in Contact List Audience Segment

Clear all identifiers in Contact List Audience Segment