Audience

Retrieving Audiences for a Specific Advertiser

Audiences created through Criteo's API will be returned for the designated advertiser ID.

https://api.criteo.com/2021-10/audiences?advertiser-id={advertiserId}

The API will return an array of the IDs, names, description, date of creation, date of last update, number of lines in the contact list, as well as the number of matched emails in the contact list associated with the specified advertiser ID. Please note that the advertiser ID is required in the request URL.

{
  "data": [
    {
      "type": "AudienceContactlist",
      "id": "1",
      "attributes": {
        "advertiserId": "18",
        "name": "Audience name",
        "description": "An Audience description",
        "createdAt": "2020-10-20T08:35:22.000Z",
        "updatedAt": "2020-10-20T08:35:22.000Z",
        "nbLines": 100,
        "nbLinesEmail": 10,
        "nbMatchesEmail": 10
      }
    }
  ],
    "errors": [],
    "warnings": []
}

Creating A New Audience

A new audience can be created for a specific advertiser by making a POST call to the audience endpoint. The request body should specify the advertiser id, name, and description of the new audience.

https://api.criteo.com/2023-01/audiences

{
  "data": {
    "type": "Audience",
    "attributes": {
        "advertiserId": "1",
        "name": "audienceX",
        "description": "audience X targets people who like shoes"
    }
  }
}

The API will return a unique audience id associated with the newly created audience.

{
    "data": {
      "id": "12",
      "type": "Audience"
    },
    "errors": [],
    "warnings": []
}

Deleting An Audience

An audience can be deleted by specifying the audience id in the URL path of a DELETE call to the audiences endpoint.

https://api.criteo.com/2023-01/audiences/{audienceId}

The API will return an array with the audience ID that was deleted.

{
    "data": {
      "id": "12",
      "type": "Audience"
    },
    "errors": [],
    "warnings": []
}

Updating Audience Metadata

The audience name and description can be updated by making a PATCH request to the audiences endpoint with a specific audience ID in the URL path. The request body should include the updated name and description of the audience.

https://api.criteo.com/2023-01/audiences/{audienceId}

{
  "data": {
    "type": "Audience",
    "attributes": {
        "name": "audienceY",
        "description": "audience Y targets people who like pants"
    }
  }
}

The API will return an array of the updated name and description of the specified audience ID.

{
    "data": {
      "type": "Audience",
      "id": "12",
      "attributes": {
          "name": "audienceY",
          "description": "audience Y targets people who like pants"
      }
    },
    "errors": [],
    "warnings": []
}

In addition to general API errors, you may encounter validation errors when creating or managing Audiences.

Below is a list of error codes for Audience validation and a more detailed description of their meaning.

Audience Validation Errors

body-data-type-invalid
The data-type provided cannot be accepted. The message will detail expected data type.


audience-invalid-name
Invalid audience name.


invalid-audience-name-duplicated
Given audience name already exists for the requested advertiser


invalid-schema
Bad schema name. Please check the list of allowed schemas on Managing Audiences


invalid-operation
Bad operation name. Please check the list of allowed operations on Managing Audiences


empty-identifiers
None or invalid identifiers have been supplied with the request


invalid
Request is invalid or the server wasn't able to process the request due to a serialization error.