Commerce Grid Audience Segments Endpoints

Introduction

Audience Segments represent a groups of users to target.

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

⚠️
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

Verb	Endpoint	Description
POST	`/commerce-grid/audience-segments/create`	Create a new Audience Segment
PATCH	`/commerce-grid/audience-segments`	Update an Audience Segment
POST	`/commerce-grid/audience-segments/delete`	Delete an Audience Segment
POST	`/commerce-grid/audience-segments/search`	Search for Audience Segments by segment IDs, data provider IDs and/or segment types
GET	`/commerce-grid/audience-segments/{audienceSegmentId}/contact-list/statistics`	Retrieve contact list statistics
POST	`/commerce-grid/audience-segments/{audienceSegmentId}/contact-list/add-remove`	Add/remove identifiers in contact list Audience Segment
POST	`/commerce-grid/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
`dataProviderId`*	string	Data Provider ID associated with the Audience Segment, generated internally by Criteo Accepted values: string of int64 Writeable? N / Nullable? N
`type`	enum	Type of segment Read-only value, which can be one of: `ContactList`: users segment defined by list of contact identifiers, manageable by the other endpoints Writeable? N / Nullable? N
`contactList`	object	Setting to target users with contact list. 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
`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

*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
`remoteId`	string	ID owned by the client and used to identify the Audience Segment. If none is provided, one will be generated internally by Criteo Accepted values: string Writeable? Y / Nullable? N

Attribute

Data Type

Description

remoteId

string

ID owned by the client and used to identify the Audience Segment. If none is provided, one will be generated internally by Criteo

Accepted values: string
Writeable? Y / 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.

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

https://api.criteo.com/{version}/commerce-grid/audience-segments/create

Sample Request

curl -L -X POST 'https://api.criteo.com/{version}/commerce-grid/audience-segments/create' \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'Authorization: Bearer <MY_ACCESS_TOKEN>' \
-d '{
  "data": [
    {
      "type": "CommerceGridAudienceSegment",
      "attributes": {
        "name": "CRM Users 2025",
        "description": "Segment made of CRM user emails",
        "dataProviderId": "94",
        "contactList": {
          "remoteId": "crm_users.csv"
        }
      }
    },
  ]
}'

Sample Response

{
  "data": [
    {
      "attributes": {
        "name": "CRM Users 2025",
        "description": "Segment made of CRM user emails",
        "type": "ContactList",
        "createdAt": "2025-12-12T13:44:53.29Z",
        "updatedAt": "2025-12-12T13:44:53.29Z",
        "dataProviderId": "94",
        "remoteId": "crm_users.csv",
        "contactList": {}
      },
      "id": "787314040225128448",
      "type": "CommerceGridAudienceSegment"
    }
  ],
  "warnings": [],
  "errors": []
}

Sample Request - auto-generated remoteId

curl -L -X POST 'https://api.criteo.com/{version}/commerce-grid/audience-segments/create' \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'Authorization: Bearer <MY_ACCESS_TOKEN>' \
-d '{
  "data": [
    {
      "type": "CommerceGridAudienceSegment",
      "attributes": {
        "name": "CRM Users 2024",
        "description": "Segment made of CRM user emails",
        "dataProviderId": "94",
        "contactList": {}
      }
    },
  ]
}'

Sample Response

{
  "data": [
    {
      "attributes": {
        "name": "CRM Users 2024",
        "description": "Segment made of CRM user emails",
        "type": "ContactList",
        "createdAt": "2025-12-12T13:58:12.5366667Z",
        "updatedAt": "2025-12-12T13:58:12.5366667Z",
        "dataProviderId": "94",
        "remoteId": "787317394479550464",
        "contactList": {}
      },
      "id": "787317394479550464",
      "type": "CommerceGridAudienceSegment"
    }
  ],
  "warnings": [],
  "errors": []
}

Partial `200 OK` response

{
    "data": [],
    "warnings": [],
    "errors": [
        {
            "traceId": "0ab8cdc52e17ecfd1ba9e5d1dacd102a",
            "traceIdentifier": "0ab8cdc52e17ecfd1ba9e5d1dacd102a",
            "type": "validation",
            "code": "name-must-be-unique",
            "instance": "@data/0",
            "title": "Segment name must be unique",
            "detail": "Another segment exists with the name: CRM users 2025"
        }
    ]
}

Update Audience Segment

This endpoint allows updating Audience Segments.

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

https://api.criteo.com/{version}/commerce-grid/audience-segments

Sample Request

curl -L -X PATCH 'https://api.criteo.com/{version}/commerce-grid/audience-segments' \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'Authorization: Bearer <MY_ACCESS_TOKEN>' \
-d '{
  "data": [
    {
      "id": "738406688413290496",
      "type": "CommerceGridAudienceSegment",
      "attributes": {
        "name": "CRM User E-mails 2025 (Updated)",
        "description": {
          "value": "Segment made of CRM user e-mails (Updated)"
        }
      }
    }
  ]
}'

Sample Response

{
  "data": [
    {
      "attributes": {
        "name": "CRM User E-mails 2025 (Updated)",
        "description": "Segment made of CRM user e-mails (Updated)",
        "type": "ContactList",
        "createdAt": "2025-12-12T13:44:53.29Z",
        "updatedAt": "2025-12-12T13:46:39.4833333Z",
        "dataProviderId": "94",
        "remoteId": "crm_users.csv",
        "contactList": {}
      },
      "id": "787314040225128448",
      "type": "CommerceGridAudienceSegment"
    }
  ],
  "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}/commerce-grid/audience-segments/delete

Sample Request

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

Sample Response

{
    "data": [
        {
            "id": "738406561971802112",
            "type": "CommerceGridAudienceSegment"
        }
    ],
    "warnings": [],
    "errors": []
}

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 to0 and 50 respectively. The maximum limit is 100.

https://api.criteo.com/{version}/commerce-grid/audience-segments/search?offset={offset}&limit={limit)

Sample Request:

curl -L -X POST 'https://api.criteo.com/{version}/commerce-grid/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": "CommerceGridAudienceSegmentSearch",
    "attributes": {
      "dataProviderIds": [
        "94"
      ],
      "audienceSegmentTypes": [
        "ContactList"
      ]
    }
  }
}'

Sample Response

{
    "meta": {
        "totalItems": 400,
        "limit": 50,
        "offset": 0
    },
    "data": [
        {
            "id": "203134567785554216",
            "type": "CommerceGridAudienceSegment",
            "attributes": {
                "name": "Segment Name",
                "type": "ContactList",
                "createdAt": "2024-01-15T12:23:18.180Z",
                "updatedAt": "2024-01-15T12:23:18.180Z",
                "dataProviderId": "94",
                "remoteId": "users.csv",
                "contactList": { }
            }
        },
        // ...
        {
            "id": "225702933721171456",
            "type": "CommerceGridAudienceSegment",
            "attributes": {
                "name": "Segment Name",
                "type": "ContactList",
                "createdAt": "2024-01-23T09:33:40.822Z",
                "updatedAt": "2024-01-23T09:33:40.822Z",
                "dataProviderId": "94",
                "remoteId": "some-other-id",
                "contactList": { }
            }
        }
    ],
    "errors": [],
    "warnings": []
}

Get Contact List Segment Statistics

This endpoint allows retrieving statistics from a contact list Audience Segment.

https://api.criteo.com/{version}/commerce-grid/audience-segments/{audienceSegmentId}/contact-list/statistics

Sample Request

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

Sample Response

{
    "data": {
        "id": "225702933721171456",
        "identifierType": "CommerceGridContactListStatistics",
        "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 Audience Segment.

❗️
Set Add or Remove in the operation attribute in the request to indicate if you want to add or remove the list of identifiers from the contact list.

⚠️
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? Y / Nullable? N
`identifierType`	enum	Type of identifiers that are being uploaded Accepted values: `Email`, `MadId`, `UserIdentifier`, `IdentityLink` (LiveRamp IDs), `BidSwitchId`, `FTrackId`, `PanoramaId`, `HadronId`, `IpAddressV4`, `PageUrl`, `PageDomain`, `AppId` Writeable? Y / Nullable? N
`identifiers`	string[]	Array of identifiers represented as strings

Attribute

Data Type

Description

operation

enum

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

Accepted values: Add, Remove
Writeable? Y / Nullable? N

identifierType

enum

Type of identifiers that are being uploaded

Accepted values: Email, MadId, UserIdentifier, IdentityLink (LiveRamp IDs), BidSwitchId, FTrackId, PanoramaId, HadronId, IpAddressV4, PageUrl, PageDomain, AppId
Writeable? Y / Nullable? N

identifiers

string[]

Array of identifiers represented as strings

https://api.criteo.com/{version}/commerce-grid/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}/commerce-grid/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]"
      ]
    }
  }
}'

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

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 endpoint resets a contact list Audience Segment, erasing all existing users identifiers.

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

https://api.criteo.com/{version}/commerce-grid/audience-segments/{audienceSegmentId}/contact-list/clear

Sample Request

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

Sample Response

🟢 204 No Content (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.

Introduction

Partial Approvals

Endpoints

Audience Segment Attributes

Field Definitions

Contact List Segment Attributes

Field Definitions

Create Audience Segment

Partial 200 OK response

Update Audience Segment

Delete Audience Segment

Search for Audience Segments

Get Contact List Segment Statistics

Add/Remove identifiers in Contact List Audience Segment

Identifier List Size Limit

Clear all identifiers in Contact List Audience Segment

Note on Audience Computation

Partial `200 OK` response