Skip to main content

​
Endpoints

VerbEndpointDescription
POST/retail-media/accounts/{account-id}/audience-segments/createCreate a new Audience Segment
PATCH/retail-media/accounts/{account-id}/audience-segmentsUpdate an Audience Segment
POST/retail-media/accounts/{account-id}/audience-segments/deleteDelete an Audience Segment
POST/retail-media/accounts/{account-id}/audience-segments/searchReturns a list of segments that match the provided filters. If present, the filters are AND’ed together when applied. You can search segments by segment IDs, retailer IDs and/or segment types
GET/retail-media/accounts/{account-id}/audience-segments/{audience-segment-id}/contact-listRetrieve contact list statistics
POST/retail-media/audience-segments/{audience-segment-id}/contact-list/add-removeAdd/remove identifiers in contact list Audience Segment
POST/retail-media/audience-segments/{audience-segment-id}/contact-list/clearClear all identifiers in contact list Audience Segment

​
Audience Segment Attributes

​
id
Data Type: stringValues: int64Nullable? NoDescription: Audience Segment ID
​
name
Data Type: stringValues: stringNullable? NoDescription: Audience Segment name
​
description
Data Type: stringValues: stringNullable? YesDescription: Description of the Audience Segment
​
createdAt
Data Type: stringValues: YYYY-MM-DDTHH:mm:ss:msZNullable? NoDescription: Timestamp (in UTC) of Audience Segment creation
​
createdById
Data Type: stringValues: int64Nullable? YesDescription: User ID of the Audience Segment creator (null if created by a service)
​
updatedAt
Data Type: stringValues: YYYY-MM-DDTHH:mm:ss:msZNullable? NoDescription: Timestamp (in UTC) of Audience Segment update
​
accountID
Data Type: stringValues: int64Nullable? NoDescription: Account associated with the Audience Segment
​
retailerId
Data Type: stringValues: intNullable? NoDescription: ID of the retailer. To retrieve the RetailerID associated to your Supply account you can use the GET call found here
​
channels
Data Type: list of stringValues: Unknown, Onsite, OffsiteNullable? NoDescription: Channels associated to the audience
​
contactList
Data Type: objectValues:Nullable? NoDescription: Setting to target users with contact list. Note, either one of Contact List or Events is required, however both cannot be leveraged at the same time
​
events
Data Type: objectValues:Nullable? NoDescription: Settings to target users based on their events. Note, either one of Contact List or Events is required, however both cannot be leveraged at the same time

​
Contact List Attributes

​
IsReadOnly
Data Type: booleanValues: True/FalseNullable? NoDescription: Indicate if the contact list can be edited
​
identifierType
Data Type: enumValues: Unknown, Email, UserIdentifier, IdentityLink, CustomerIdDescription: Contact list type

​
Events Attributes

​
shopperActivity
Data Type: stringValues: Unknown, View, Buy, AddToCartNullable? NoDescription: Reach people who performed specific action
​
lookbackDays
Data Type: stringValues: Unknown, Last7Days, Last14Days, Last30Days, Last45Days, Last60Days, Last90Days, Last120Days, Last150Days, Last180DaysNullable? NoDescription: Reach people who interact with the website in the timeframe define in the lookbackDays value
​
categoryIds
Data Type: stringValues: intNullable? NoDescription: Reach people interested in the list of categories defined. Note, either one of categoryId or brandId must be included. Both can be included as well, but the request will fail if neither are included.
​
brandIds
Data Type: stringValues: intNullable? NoDescription: Reach people interested in the list of brands defined. Note, either one of categoryId or brandId must be included. Both can be included as well, but the request will fail if neither are included.
​
MinPrice
Data Type: stringValues: intNullable? NoDescription: Reach people who interact with products costing more than MinPrice
​
MaxPrice
Data Type: stringValues: intNullable? NoDescription: Reach people who interact with products costing less than MaxPrice

​
Create Audience Segment

When creating a segment, the parameter RetailerID is mandatory. Additionally, the corresponding App should have the “Audiences Viewer” 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": "Segment Name",
        "description": "Segment Description",
        "retailerId": "1234",
        "contactList": {
          "identifierType": "Email"
        }
      }
    }
  ]
}'
Sample Response 
{
    "data": [
        {
            "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": "1234",
                "contactList": {
                    "isReadOnly": "true",
                    "identifierType": "Email"
                }
            }
        }
    ],
    /* omitted if no errors */
    "errors": [],
    /* omitted if no warnings */
    "warnings": []
}

​
Update Audience Segment

It is only possible to update contact list 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": [
    {
      "attributes": {
        "name": "New Name",
        "description": {
          "value": "New Description"
        },
        "contactList": {
        }
      },
      "id": "225702933721171456",
      "identifierType": "AudienceSegment"
    }
  ]
}'
Sample Response 
{
    "data": [
        {
            "id": "225702933721171456",
            "type": "AudienceSegment",
            "attributes": {
                "name": "New Name",
                "description": "New Description",
                "type": "ContactList",
                "createdAt": "2024-01-23T09:33:40.822Z",
                "updatedAt": "2024-01-23T09:33:40.822Z",
                "accountId": "625702934721171442",
                "retailerId": "1234",
                "contactList": {
                    "isReadOnly": "true",
                    "identifierType": "Email"
                }
            }
        }
    ],
    /* omitted if no errors */
    "errors": [],
    /* omitted if no warnings */
    "warnings": []
}

​
Delete Audience Segment

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": "225702933721171456",
      "identifierType": "Audience Segment"
    }
  ]
}'
Sample Response 
{
    "data": [
        {
            "id": "225702933721171456",
            "identifierType": "Audience Segment"
        }
    ],
    /* omitted if no errors */
    "errors": [],
    /* omitted if no warnings */
    "warnings": []
}

​
Search for Audience Segments

Sample Request: searching by Retailer ID only 
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": null
  }
}'
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"
                }
            }
        }
    ],
    /* omitted if no errors */
    "errors": [],
    /* omitted if no warnings */
    "warnings": []
}
Sample Request: searching by multiple filters 
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": ["225702933721171456"],
      "retailerIds": [
        "12"
      ],
      "audienceSegmentTypes": ["ContactList"]
    }
  }
}'
Sample Response 
{
    "meta": {
        "totalItems": 400,
        "limit": 50,
        "offset": 0
    },
    "data": [
        {
            "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"
                }
            }
        }
    ],
    /* omitted if no errors */
    "errors": [],
    /* omitted if no warnings */
    "warnings": []
}

​
Get Contact List Segment Statistics

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>'
Sample Response 
{
    "data": {
        "attributes": {
            "numberOfIdentifiers": 10000,
            "numberOfMatches": 5000,
            "matchRate": 0.5
        },
        "id": "225702933721171456",
        "identifierType": "AudienceSegment"
    },
    /* omitted if no errors */
    "errors": [],
    /* omitted if no warnings */
    "warnings": []
}

​
Add/Remove Identifiers in Contact List Audience Segment

To add users to an audience segment, use the ‘add’ operation in the POST request as detailed below: Sample Request 
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"
      ]
    }
  }
}'
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": []
}
To remove users from an audience segment, use the remove operation in the POST request as detailed below: Sample Request 
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"
      ]
    }
  }
}'
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

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>'
Sample Response 
{
    "data": {
        "type": "ContactListAudienceSegment",
        "id": "225702933721171456"
    },
    /* omitted if no errors */
    "errors": [],
    /* omitted if no warnings */
    "warnings": []
}
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 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.