> ## Documentation Index
> Fetch the complete documentation index at: https://developers.criteo.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Contact List

export const EndpointBadge = ({method = "GET", children}) => {
  const METHOD_STYLES = {
    GET: {
      bg: "mint-bg-[#2AB673]"
    },
    POST: {
      bg: "mint-bg-[#3064E3]"
    },
    PUT: {
      bg: "mint-bg-[#C28C30]"
    },
    PATCH: {
      bg: "mint-bg-[#DA622B]"
    },
    DELETE: {
      bg: "mint-bg-[#CB3A32]"
    },
    API: {
      bg: "mint-bg-black"
    }
  };
  const key = method.toUpperCase();
  const styles = METHOD_STYLES[key] ?? METHOD_STYLES.API;
  return <div className="relative mt-7">
      <span className={`absolute -top-2 -left-2 z-10 ${styles.bg} text-white px-2.5 py-0.5 rounded-full text-xs font-bold tracking-wide`}>
        {key}
      </span>
      {children}
    </div>;
};

## **Adding and Removing Users in an Audience**

<EndpointBadge method="patch">
  ```http theme={null}
  https://api.criteo.com/2023-07/audiences/{audienceId}/contactlist
  ```
</EndpointBadge>

Users can be added or removed from an audience with a PATCH request to the audience contact list endpoint with the specific audience id in the URL path. The request body requires the type of operation, the schema of the identifiers, and the list of the user identifiers to be added. In addition, if the identifier type is 'gum', an additional parameter, the `gumCallerId`, must also be included. Please note that the supported identifier types for Criteo audiences include: 'email' (Email Address), 'madid' (Mobile Ad Identifier), 'identityLink' (a user's LiveRamp Identity Link), 'gum' (Criteo GUM cookie identifier) and 'customerid' (only for Retail Media Customer Lists).

<Info>
  GUM ID's allow clients to maintain a correspondence between their user identification system and Criteo's user identification (UID) if they are unable to send emails or mobile ad identifiers.

  Please reach out to your Criteo account team for the appropriate `gumCallerId` or to get more information on this GUM sync, if needed.
</Info>

 

 

## Adding Users

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

<CodeGroup>
  ```json JSON theme={null}
  {
    "data": {
      "type": "ContactlistAmendment",
      "attributes": {
          "operation": "add",
          "identifierType": "email",
          "identifiers": [
              "example1@gmail.com"
          ]
      }
    }
  }
  ```
</CodeGroup>

The API will respond with an array of the **audienceId**, **operation**, **date of request**, **identifierType**, number of valid or invalid identifiers, and a sample of invalid identifiers if applicable.

<CodeGroup>
  ```json JSON theme={null}
  {
     "data": {
      "type": "ContactlistAmendment",
      "attributes": {
         "contactListId": "12",
         "operation": "add",
         "requestDate": "2018-12-10T10:00:50.000Z",
         "identifierType": "email",
         "nbValidIdentifiers": 7343,
         "nbInvalidIdentifiers": 13,
         "sampleInvalidIdentifiers": [
               "InvalidIdentifier"
               ]
         }
     },
     "errors": [],
     "warnings": []
  }
  ```
</CodeGroup>

 

## Removing Users

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

<CodeGroup>
  ```json JSON theme={null}
  {
    "data": {
      "type": "ContactlistAmendment",
      "attributes": {
          "operation": "remove",
          "identifierType": "email",
          "identifiers": [
              "example1@gmail.com"
          ]
      }
    }
  }
  ```
</CodeGroup>

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

<CodeGroup>
  ```json JSON theme={null}
  {
     "data": {
      "type": "ContactlistAmendment",
      "attributes": {
         "contactListId": "12",
         "operation": "remove",
         "requestDate": "2018-12-10T10:00:50.000Z",
         "identifierType": "email",
         "nbValidIdentifiers": 7342,
         "nbInvalidIdentifiers": 13,
         "sampleInvalidIdentifiers": [
               "InvalidIdentifier"
         ]
      }
    },
     "errors": [],
     "warnings": []
  }
  ```
</CodeGroup>

 

 

<Warning>
  **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.
</Warning>

 

 

## **Deleting All Users From an Audience**

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

<EndpointBadge method="delete">
  ```http theme={null}
  https://api.criteo.com/2023-07/audiences/{audienceId}/contactlist
  ```
</EndpointBadge>

The API will return an array with the specified **audienceId** where all of the users were deleted from.

<CodeGroup>
  ```json JSON theme={null}
  {
      "data": {
          "type": "Audience",
          "id": "12"
      },
      "errors": [],
      "warnings": []
  }
  ```
</CodeGroup>

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

<Warning>
  **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.
</Warning>