GuidesAPI ReferenceChangelog
GuidesAPI ReferenceChangelog
GuidesAPI ReferenceChangelogLog In
Guides

Audience Segment Endpoints

Suggest Edits

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 together using logical Algebra Nodes to defined the desired target audience for your campaigns.

🚧

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.

Endpoints

VerbEndpointDescription
POST/accounts/{account-id}/audience-segments/createCreate a new Audience Segment
PATCH/accounts/{account-id}/audience-segmentsUpdate an Audience Segment
POST/accounts/{account-id}/audience-segments/deleteDelete an Audience Segment
POST/accounts/{account-id}/audience-segments/searchSearch for Audience Segments by segment IDs, retailer IDs and/or segment types
GET/accounts/{account-id}/audience-segments/{audience-segment-id}/contact-listRetrieve contact list statistics
POST/audience-segments/{audience-segment-id}/contact-list/add-removeAdd/remove identifiers in contact list Audience Segment
POST/audience-segments/{audience-segment-id}/contact-list/clearClear all identifiers in contact list Audience Segment

Audience Segment Attributes

AttributeData TypeDescription
idstringAudience Segment ID, generated internally by Criteo

Accepted values: string of int64
Writeable? N / Nullable? N
name*stringAudience Segment name

Accepted values: string
Writeable? Y / Nullable? N
descriptionstringDescription of the Audience Segment

Accepted values: string
Writeable? Y / Nullable? N
accountIdstringAccount ID associated with the Audience Segment, generated internally by Criteo

Accepted values: string of int64
Writeable? N / Nullable? N
retailerId*stringRetailer ID, associated with the Audience Segment, generated internally by Criteo

Accepted values: string of int64
Writeable? N / Nullable? N
typeenumType 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
contactListobjectSetting 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
eventsobjectSettings 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
createdAttimestampTimestamp of Audience Segment creation, in UTC

Accepted values: yyyy-mm-ddThh:mm:ss.msZ (in ISO-8601 )
Writeable? N / Nullable? N
createdByIdstringUser ID who created the Audience Segment (null if created by a service)

Accepted values: string
Writeable? N / Nullable? Y
updatedAttimestampTimestamp of last Audience Segment update, in UTC

Accepted values: yyyy-mm-ddThh:mm:ss.msZ(in ISO-8601)
Writeable? N / Nullable? N
channelslistChannels associated to the audience

Accepted values: Onsite, Offsite, Unknown
Writeable? N / Nullable? N

* Required at create operation

Contact List Attributes

AttributeData TypeDescription
isReadOnlybooleanIndicates if the contact list can be edited

Accepted values: true, false
Writeable? N / Nullable? N
identifierTypeenumUser identifier type from Contact list

Accepted values: Email, UserIdentifier, IdentityLink, CustomerId, Unknown
Writeable? N / Nullable? N

Events Attributes

AttributeData TypeDescription
shopperActivity*enumActivity type performed by the desired target users in the retailer's environment

Accepted values: View, Buy, AddToCart, Unknown
Writeable? Y / Nullable? N
lookbackDays*enumTimeframe 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
categoryIdslistDefine users interested in specific categories from retailer's Catalog.
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

Accepted values: array of strings/int64
Writeable? Y / Nullable? Y
brandIdslistDefine users who performed the activity type above in specific brands from retailer's Catalog.
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

Accepted values: array of strings/int64
Writeable? Y / Nullable? Y
minPricedecimalDefine users who interact with products whose prices are greater than minPrice

Accepted values: minPrice ≥ 0.0 (or null)
Writeable? Y / Nullable? Y
maxPricedecimalDefine 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

Create Audience Segment

This endpoints allows to create Audience Segments, either from Contact List or Users Events type.

Note: 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

https://api.criteo.com/{version}/retail-media/accounts/{account-id}/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 endpoints allows to update Audience Segments, either from Contact List or Users Events type.

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.

https://api.criteo.com/{version}/retail-media/accounts/{account-id}/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 endpoints allows to delete Audience Segments, either one by one or multiple of them.

Note: the corresponding App should have the "Audiences Manage" permission enabled.

https://api.criteo.com/{version}/retail-media/accounts/{account-id}/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": []
}

Search for Audience Segments

This endpoints allows to search 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, respective - see API Response

https://api.criteo.com/{version}/retail-media/accounts/{account-id}/audience-segments/search?offset={offset}&limit={limit)

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 <TOKEN>'
}
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 <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/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 <TOKEN>'
));
$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 endpoints allows to retrieve statistics from Contact List segments.

https://api.criteo.com/{version}/retail-media/accounts/{account-id}/audience-segments/{audience-segment-id}/contact-list

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.

AttributeData TypeDescription
operationenumOperation required for the sub-set of users provided in the request

Accepted values: add, remove
Writeable? N / Nullable? N
https://api.criteo.com/{version}/retail-media/audience-segments/{audience-segment-id}/contact-list/add-remove

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": [
        "[email protected]",
        "[email protected]",
        "[email protected]"
      ]
    }
  }
}'

import http.client
import json
conn = http.client.HTTPSConnection("api.criteo.com")
payload = json.dumps({
{
  "data": {
    "type": "AddRemoveContactlist",
    "attributes": {
      "operation": "add",
      "identifierType": "email",
      "identifiers": [
        "[email protected]",
        "[email protected]",
        "[email protected]",
      ]
    }
  }
}
headers = {
  'Content-Type': 'application/json',
  'Accept': 'application/json',
  'Authorization': 'Bearer <TOKEN>'
}
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":["[email protected]","[email protected]","[email protected]"]}}}');
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 <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/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 <TOKEN>'
));
$request->setBody('{"data":{"type":"AddRemoveContactlist","attributes":{"operation":"add","identifierType":"email","identifiers":["[email protected]","[email protected]","[email protected]"]}}}');
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": [
        "[email protected]"
      ]
    }
  }
}'

import http.client
import json
conn = http.client.HTTPSConnection("api.criteo.com")
payload = json.dumps({
{
  "data": {
    "type": "ContactlistAmendment",
    "attributes": {
        "operation": "remove",
        "identifierType": "email",
        "identifiers": [
            "[email protected]"
        ]
    }
  }
}
headers = {
  'Content-Type': 'application/json',
  'Accept': 'application/json',
  'Authorization': 'Bearer <TOKEN>'
}
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":["[email protected]"]}}}');
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 <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/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 <TOKEN>'
));
$request->setBody('{"data":{"type":"ContactlistAmendment","attributes":{"operation":"remove","identifierType":"email","identifiers":["[email protected]"]}}}');
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 Limit

Note 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 endpoints resets a Contact List segment, erasing all existing users identifiers.

Note: the corresponding App should have the "Audiences Manage" permission enabled.

https://api.criteo.com/{version}/retail-media/audience-segments/{audience-segment-id}/contact-list/clear

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.

🚧

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.

Updated 4 days ago