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.
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.
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.
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
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.
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" } ]}
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:
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
Sample Request - adding users to existing audience segment
{ "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.
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 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.
