[Audiences] Managing Users In An Audience

Adding and Removing Users in an Audience

https://api.criteo.com/legacy/marketing/v1/audiences/userlist/{audienceId}

Users can be added or removed from an audience with a PATCH request to the audience user list endpoint with the specific audience id in the URL path. The payload requires the type of operation, the schema of the identifiers, the list of identifiers to be added, and the gumCallerId if GUM IDs are being added.

📘

Please reach out to your Criteo account team for the appropriate gumCallerId, if needed.

Adding Users

To add users to an audience, use the 'add' operation in the PATCH payload as detailed below:

curl --request PATCH \
  --url https://api.criteo.com/legacy/marketing/v1/audiences/userlist/7654 \
  --header 'Accept: application/json' \
  --header 'Content-Type: text/json' \
  --data '{"identifiers":["[email protected]","[email protected]","[email protected]","[email protected]"],"operation":"add","schema":"email"}'

The API will respond with the number of identifiers that are valid or invalid.

{
  "operation": "add",
  "requestDate": "2020-09-09T18:21:16.383Z",
  "schema": "email",
  "nbValidIdentifiers": 3,
  "nbInvalidIdentifiers": 1,
  "sampleInvalidIdentifiers": [
    "jkl@gmail"
  ]
}

Removing Users

To remove users from an audience, use the 'remove' operation in the PATCH payload as detailed below:

curl --request PATCH \
  --url https://api.criteo.com/legacy/marketing/v1/audiences/userlist/7654 \
  --header 'Accept: application/json' \
  --header 'Content-Type: text/json' \
  --data '{"identifiers":["[email protected]","[email protected]","[email protected]","[email protected]"],"operation":"remove","schema":"email"}'

The API will respond similarly to the add users call, but with 'remove' as the operation.

{
  "operation": "remove",
  "requestDate": "2020-09-09T18:21:16.383Z",
  "schema": "email",
  "nbValidIdentifiers": 3,
  "nbInvalidIdentifiers": 1,
  "sampleInvalidIdentifiers": [
    "jkl@gmail"
  ]
}

❗️

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.

A full list of all available filters is available on the Add/Remove users to an Audience page.

Deleting All Users From an Audience

To delete all users from an audience, a DELETE request can be made to the audience user list endpoint with the specified audience id in the URL path.

https://api.criteo.com/legacy/marketing/v1/audiences/userlist/{audienceId}/users

curl --request DELETE \
  --url https://api.criteo.com/legacy/marketing/v1/audiences/userlist/7654/users \
  --header 'Accept: application/json'

The API will not return a response message. A 204 HTTP status code will be returned to confirm that the all of the users have been wiped from the audience.

📘

Note that this will only wipe all of the users from the audience and will not delete the audience itself.