> ## 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.

# Audience Segments

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>;
};

Audience Segments are the building blocks of Audiences, as you can mix them together to ensure you target your desired customer base.

An audience segment is the association of an audience segment type with an audience segment value.

## **Audience Segment types**

<Info>
  **Static Values on Audience Segments**

  Some of the parameters required to define an Audience Segment can take predefined values.

  For example, to get the different values that the field **In-market Brand Id** can take, use the **/audience-segments/in-market-brands** endpoint.
</Info>

Regardless of the Segment type, segments share the following fields. Some of them are *calculated* so you don't need to define them at the creation but can read them after the Segment is created.

<table>
  <thead>
    <tr>
      <th>
        <p>
          Field name and type
        </p>
      </th>

      <th>
        <p>
          Possible value
        </p>
      </th>

      <th>
        <p>
          Optional / Required / Computed
        </p>
      </th>

      <th>
        <p>
          Description
        </p>
      </th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>
        <p>
          id (*String*)
        </p>
      </td>

      <td />

      <td>
        <p>
          Required
        </p>
      </td>

      <td>
        <p>
          Unique ID of the segment
        </p>
      </td>
    </tr>

    <tr>
      <td>
        <p>
          name (*String*)
        </p>
      </td>

      <td />

      <td>
        <p>
          Required
        </p>
      </td>

      <td>
        <p>
          Name of the segment. It must be unique per advertiser.
        </p>
      </td>
    </tr>

    <tr>
      <td>
        <p>
          description (*String*)
        </p>
      </td>

      <td />

      <td>
        <p>
          Optional
        </p>
      </td>

      <td>
        <p>
          Description of the segment
        </p>
      </td>
    </tr>

    <tr>
      <td>
        <p>
          type (*AudienceSegmentType*)
        </p>
      </td>

      <td>
        <p>
          <code>
            AudienceSegment
          </code>
        </p>
      </td>

      <td>
        <p>
          Computed
        </p>
      </td>

      <td>
        <p>
          Type of audience segment (read-only). Once created, the type cannot be changed.
        </p>
      </td>
    </tr>

    <tr>
      <td>
        <p>
          createdAt (*String*)
        </p>
      </td>

      <td />

      <td>
        <p>
          Computed
        </p>
      </td>

      <td>
        <p>
          ISO-8601 timestamp in UTC of segment creation (read-only)
        </p>
      </td>
    </tr>

    <tr>
      <td>
        <p>
          updatedAt (*String*)
        </p>
      </td>

      <td />

      <td>
        <p>
          Computed
        </p>
      </td>

      <td>
        <p>
          ISO-8601 timestamp in UTC of segment update (read-only)
        </p>
      </td>
    </tr>

    <tr>
      <td>
        <p>
          advertiser Id (*String*)
        </p>
      </td>

      <td />

      <td>
        <p>
          Required
        </p>
      </td>

      <td>
        <p>
          Advertiser associated to the segment
        </p>
      </td>
    </tr>
  </tbody>
</table>

### In-market

In-market segments can be used to target users based on high shopping intents and demographics.

<table>
  <thead>
    <tr>
      <th>
        <p>
          Field name
        </p>
      </th>

      <th>
        <p>
          Type
        </p>
      </th>

      <th>
        <p>
          Optional / Required / Computed
        </p>
      </th>

      <th>
        <p>
          Description
        </p>
      </th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>
        <p>
          <b>
            In-market
          </b>
        </p>
      </td>

      <td>
        <p>
          In-market
        </p>
      </td>

      <td>
        <p>
          Optional
        </p>
      </td>

      <td>
        <p>
          Indicates that this should be an Audience Segment of type

          <b>
            In-market
          </b>
        </p>
      </td>
    </tr>
  </tbody>
</table>

A **In-market** object has the following parameters:

<table>
  <thead>
    <tr>
      <th>
        <p>
          Field name
        </p>
      </th>

      <th>
        <p>
          Type
        </p>
      </th>

      <th>
        <p>
          Optional / Required / Computed
        </p>
      </th>

      <th>
        <p>
          Description
        </p>
      </th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>
        <p>
          country
        </p>
      </td>

      <td>
        <p>
          String
        </p>

        <p>
          The ISO 3166-1 alpha-2 country code
        </p>
      </td>

      <td>
        <p>
          Required (if In-market is set)
        </p>
      </td>

      <td>
        <p>
          Reach people of a specific country.
        </p>
      </td>
    </tr>

    <tr>
      <td>
        <p>
          buyingPower
        </p>
      </td>

      <td>
        <p>
          BuyingPower array
        </p>

        <p>
          BuyingPower can be:
        </p>

        <ul>
          <li>
            <code>
              Low
            </code>
          </li>

          <li>
            <code>
              Medium
            </code>
          </li>

          <li>
            <code>
              High
            </code>
          </li>

          <li>
            <code>
              VeryHigh
            </code>
          </li>
        </ul>
      </td>

      <td>
        <p>
          Optional
        </p>
      </td>

      <td>
        <p>
          Reach people who frequently purchase high price range items to lower price range items. If empty, don't filter people based on buying power.
        </p>
      </td>
    </tr>

    <tr>
      <td>
        <p>
          gender
        </p>
      </td>

      <td>
        <p>
          Gender
        </p>

        <p>
          Gender can be:
        </p>

        <ul>
          <li>
            <code>
              Male
            </code>
          </li>

          <li>
            <code>
              Female
            </code>
          </li>
        </ul>
      </td>

      <td>
        <p>
          Optional
        </p>
      </td>

      <td>
        <p>
          Reach people who’ve shown interest in products made for a specific gender. If empty, don't filter people based on gender.
        </p>
      </td>
    </tr>

    <tr>
      <td>
        <p>
          <a href="/marketing-solutions/v2025.10/docs/audience-segments#operations">
            interestIds
          </a>
        </p>
      </td>

      <td>
        <p>
          String array
        </p>
      </td>

      <td>
        <p>
          Required (if In-market is set)
        </p>
      </td>

      <td>
        <p>
          Reach new people based on their commercial interests
        </p>
      </td>
    </tr>

    <tr>
      <td>
        <p>
          <a href="/marketing-solutions/v2025.10/docs/audience-segments#operations">
            brandIds
          </a>
        </p>
      </td>

      <td>
        <p>
          String array
        </p>
      </td>

      <td>
        <p>
          Required (if In-market is set)
        </p>
      </td>

      <td>
        <p>
          Choose the commercial brands your segment might be interested in
        </p>
      </td>
    </tr>

    <tr>
      <td>
        <p>
          priceRange
        </p>
      </td>

      <td>
        <p>
          PriceRange array
        </p>

        <p>
          PriceRange can be:
        </p>

        <ul>
          <li>
            <code>
              Low
            </code>
          </li>

          <li>
            <code>
              Medium
            </code>
          </li>

          <li>
            <code>
              High
            </code>
          </li>
        </ul>
      </td>

      <td>
        <p>
          Optional
        </p>
      </td>

      <td>
        <p>
          Reach people who’ve shown interest in products within a specific price range. If empty, don't filter people based on price range.
        </p>
      </td>
    </tr>
  </tbody>
</table>

```json Example theme={null}
{
    "type": "AudienceSegment",
    "attributes": {
        "name": "My In-market  segment",
        "description": "This is a segment for men in France who look for high priced products",
        "inMarket": {
            "country":"FR",
            "gender": "Male",
            "interestIds": ["928"],
            "brandIds": ["289"],
            "priceRange": ["High"]
        }
    }
}
```

### Contact List

Contact List segments can be used to target people from your contact lists. First, you define the segment and update the data using other endpoints.

<table>
  <thead>
    <tr>
      <th>
        <p>
          Field name
        </p>
      </th>

      <th>
        <p>
          Type
        </p>
      </th>

      <th>
        <p>
          Optional / Required / Computed
        </p>
      </th>

      <th>
        <p>
          Description
        </p>
      </th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>
        <p>
          <b>
            contactList
          </b>
        </p>
      </td>

      <td>
        <p>
          ContactList
        </p>
      </td>

      <td>
        <p>
          Optional
        </p>
      </td>

      <td>
        <p>
          Indicates that this should be an Audience Segment of type

          <b>
            Contact List
          </b>
        </p>
      </td>
    </tr>
  </tbody>
</table>

<Warning>
  The *contactList* parameter should be empty on the creation of this type of audience segment. More details on [Manage Contact Lists](/marketing-solutions/v2025.10/docs/audience-segments#manage-contact-lists).
</Warning>

A \*\*Contact List \*\* object has the following parameters:

<table>
  <thead>
    <tr>
      <th>
        <p>
          Field name
        </p>
      </th>

      <th>
        <p>
          Type
        </p>
      </th>

      <th>
        <p>
          Optional / Required / Computed
        </p>
      </th>

      <th>
        <p>
          Description
        </p>
      </th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>
        <p>
          isReadOnly
        </p>
      </td>

      <td>
        <p>
          Boolean
        </p>
      </td>

      <td>
        <p>
          Computed
        </p>
      </td>

      <td>
        <p>
          True if the contact list-specific information cannot be edited through the public API, false otherwise.
        </p>

        <p>
          Contact Lists can be created through the Public API or through Commerce Growth, and this determines where they’re editable: if created through the Public API, they can only be edited through the Public API; same for Commerce Growth.
        </p>

        <p>
          Segments created in Commerce Growth will show up as

          <code>
            "isReadOnly": true
          </code>

          on the Public API.
        </p>
      </td>
    </tr>
  </tbody>
</table>

```json Example theme={null}
{
            "type": "AudienceSegment",
            "attributes": {
                "name": "My contact list segment",
                "description": "An audience segment which targets my customer's database",
                "advertiserId": "4949",
                "contactList": { },
            }
}
```

### Location

Location Segments can be used to target users in specific locations.

<table>
  <thead>
    <tr>
      <th>
        <p>
          Field name
        </p>
      </th>

      <th>
        <p>
          Type
        </p>
      </th>

      <th>
        <p>
          Optional / Required / Computed
        </p>
      </th>

      <th>
        <p>
          Description
        </p>
      </th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>
        <p>
          <b>
            location
          </b>
        </p>
      </td>

      <td>
        <p>
          Location
        </p>
      </td>

      <td>
        <p>
          Optional
        </p>
      </td>

      <td>
        <p>
          Indicates that this should be an Audience Segment of type

          <b>
            Location
          </b>
        </p>
      </td>
    </tr>
  </tbody>
</table>

A **Location** object has the following parameters:

<table>
  <thead>
    <tr>
      <th>
        <p>
          Field name
        </p>
      </th>

      <th>
        <p>
          Type
        </p>
      </th>

      <th>
        <p>
          Optional / Required / Computed
        </p>
      </th>

      <th>
        <p>
          Description
        </p>
      </th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>
        <p>
          registryType
        </p>
      </td>

      <td>
        <p>
          RegistryType
        </p>

        <p>
          RegistryType can take only one value (for now):
        </p>

        <ul>
          <li>
            <code>
              PointsOfInterest
            </code>
          </li>
        </ul>
      </td>

      <td>
        <p>
          Required (if location set)
        </p>
      </td>

      <td>
        <p>
          The type of location audience segment
        </p>
      </td>
    </tr>

    <tr>
      <td>
        <p>
          pointsOfInterest
        </p>
      </td>

      <td>
        <p>
          PointsOfInterest array.
        </p>

        <p>
          Each point has a name, latitude and longitude
        </p>
      </td>

      <td>
        <p>
          Required (if location set)
        </p>
      </td>

      <td>
        <p>
          Reach users which have been historically located in the given coordinates
        </p>
      </td>
    </tr>

    <tr>
      <td>
        <p>
          → name
        </p>
      </td>

      <td>
        <p>
          String
        </p>
      </td>

      <td>
        <p>
          Required
        </p>
      </td>

      <td>
        <p>
          Name of the point of interest
        </p>
      </td>
    </tr>

    <tr>
      <td>
        <p>
          → latitude
        </p>
      </td>

      <td>
        <p>
          Decimal
        </p>
      </td>

      <td>
        <p>
          Required
        </p>
      </td>

      <td>
        <p>
          ISO-6709 latitude
        </p>
      </td>
    </tr>

    <tr>
      <td>
        <p>
          → longitude
        </p>
      </td>

      <td>
        <p>
          Decimal
        </p>
      </td>

      <td>
        <p>
          Required
        </p>
      </td>

      <td>
        <p>
          ISO-6709 longitude
        </p>
      </td>
    </tr>

    <tr>
      <td>
        <p>
          radiusInKm
        </p>
      </td>

      <td>
        <p>
          Integer
        </p>
      </td>

      <td>
        <p>
          Required (if location set)
        </p>
      </td>

      <td>
        <p>
          The expected maximum distance in kilometers between a user and a point of interest
        </p>
      </td>
    </tr>
  </tbody>
</table>

```json Example theme={null}
{
    "type": "AudienceSegment",
    "attributes": {
        "name": "My Location Segment",
        "description": "Customers close to our main store",
        "advertiserId": "12345",
        "location": {
            "registryType": "PointsOfInterest",
            "pointsOfInterest": [{
                "name": "main store",
                "latitude": 56.6,
                "longitude": 40.2
            },{
                "name": "second store",
                "latitude": 30.6,
                "longitude": 20.4
            }],
            "radiusInKm": 10
        }

    }
}
```

### Behavioral

Criteo-provided pre-built segments.

These segments are not created by the user but provided by Criteo. You cannot edit them or delete them, but you can use them to build Audiences (e.g. "People that like shoes", "People that go often to the theater", etc.).

<table>
  <thead>
    <tr>
      <th>
        <p>
          Field name
        </p>
      </th>

      <th>
        <p>
          Type
        </p>
      </th>

      <th>
        <p>
          Optional / Required / Computed
        </p>
      </th>

      <th>
        <p>
          Description
        </p>
      </th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>
        <p>
          <b>
            behavioral
          </b>
        </p>
      </td>

      <td>
        <p>
          Behavioral
        </p>
      </td>

      <td>
        <p>
          Computed
        </p>
      </td>

      <td>
        <p>
          Indicates that this should be an Audience Segment of type

          <b>
            Behavioral
          </b>
        </p>
      </td>
    </tr>
  </tbody>
</table>

A **Behavioral** object has the following parameters:

<table>
  <thead>
    <tr>
      <th>
        <p>
          Field name
        </p>
      </th>

      <th>
        <p>
          Type
        </p>
      </th>

      <th>
        <p>
          Optional / Required / Computed
        </p>
      </th>

      <th>
        <p>
          Default Value
        </p>
      </th>

      <th>
        <p>
          Description
        </p>
      </th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>
        <p>
          country
        </p>
      </td>

      <td>
        <p>
          String
        </p>
      </td>

      <td>
        <p>
          Computed
        </p>
      </td>

      <td />

      <td>
        <p>
          The user's country
        </p>
      </td>
    </tr>

    <tr>
      <td>
        <p>
          category
        </p>
      </td>

      <td>
        <p>
          BehavioralCategory.
        </p>

        <p>
          Can take any of these values:
        </p>

        <ul>
          <li>
            <code>
              Lifestyles
            </code>
          </li>

          <li>
            <code>
              LifeEvents
            </code>
          </li>

          <li>
            <code>
              Seasonal
            </code>
          </li>

          <li>
            <code>
              BuyingPatterns
            </code>
          </li>
        </ul>
      </td>

      <td>
        <p>
          Computed
        </p>
      </td>

      <td />

      <td>
        <p>
          The behavioral's category
        </p>
      </td>
    </tr>

    <tr>
      <td>
        <p>
          startDate
        </p>
      </td>

      <td>
        <p>
          DateTime
        </p>
      </td>

      <td>
        <p>
          Computed (can be empty)
        </p>
      </td>

      <td>
        <p>
          Empty
        </p>
      </td>

      <td>
        <p>
          The date when this audience segment will start to be filled with audience data
        </p>
      </td>
    </tr>

    <tr>
      <td>
        <p>
          endDate
        </p>
      </td>

      <td>
        <p>
          DateTime
        </p>
      </td>

      <td>
        <p>
          Computed (can be empty)
        </p>
      </td>

      <td>
        <p>
          Empty
        </p>
      </td>

      <td>
        <p>
          The date when this audience segment will be cleaned of audience data
        </p>
      </td>
    </tr>
  </tbody>
</table>

<Info>
  **List of Behavioral Segments**

  To get the list of the available Behavioral segments you can use the Search endpoint filtering by `Behavioral` type.
</Info>

### Prospecting

Prospecting segments are used to include users similar to the buyers of the advertiser.

<table>
  <thead>
    <tr>
      <th>
        <p>
          Field name
        </p>
      </th>

      <th>
        <p>
          Type
        </p>
      </th>

      <th>
        <p>
          Optional / Required / Computed
        </p>
      </th>

      <th>
        <p>
          Description
        </p>
      </th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>
        <p>
          <b>
            Prospecting
          </b>
        </p>
      </td>

      <td>
        <p>
          Prospecting
        </p>
      </td>

      <td>
        <p>
          Optional
        </p>
      </td>

      <td>
        <p>
          Indicates that this should be an Audience Segment of type

          <b>
            Prospecting
          </b>
        </p>
      </td>
    </tr>
  </tbody>
</table>

A Prospecting object does not have any attributes, so you need to declare it empty.

`"prospecting":{}`

```json Example theme={null}
{
    "type": "AudienceSegment",
    "attributes": {
      "name": "My Prospecting Segment",
        "description": "Customers that are similar to my current website visitors",
        "advertiserId": "12345",
        "prospecting": {}
    }
}
```

### Lookalike

Lookalike segments allow you to reach users that are similar to a given segment seed. You will be able to reach people who look like, behave like, or are interested in things similar to another segment.

<table>
  <thead>
    <tr>
      <th>
        <p>
          Field name
        </p>
      </th>

      <th>
        <p>
          Type
        </p>
      </th>

      <th>
        <p>
          Optional / Required / Computed
        </p>
      </th>

      <th>
        <p>
          Description
        </p>
      </th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>
        <p>
          <b>
            Lookalike
          </b>
        </p>
      </td>

      <td>
        <p>
          Lookalike
        </p>
      </td>

      <td>
        <p>
          Optional
        </p>
      </td>

      <td>
        <p>
          Indicates that this should be an Audience Segment of type

          <b>
            Lookalike
          </b>
        </p>
      </td>
    </tr>
  </tbody>
</table>

A Lookalike Segment object has the following parameters:

<table>
  <thead>
    <tr>
      <th>
        <p>
          Field
        </p>
      </th>

      <th>
        <p>
          Type
        </p>
      </th>

      <th>
        <p>
          Mandatory
        </p>
      </th>

      <th>
        <p>
          Description
        </p>
      </th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>
        <p>
          seedSegmentId
        </p>
      </td>

      <td>
        <p>
          string
        </p>
      </td>

      <td>
        <p>
          Yes
        </p>
      </td>

      <td>
        <p>
          Id of existing Contact List or Event segment that will be treated as a seed.
        </p>
      </td>
    </tr>

    <tr>
      <td>
        <p>
          targetSize
        </p>
      </td>

      <td>
        <p>
          int64
        </p>
      </td>

      <td>
        <p>
          No
        </p>
      </td>

      <td>
        <p>
          The target size of the resulting segment after computation.
        </p>
      </td>
    </tr>
  </tbody>
</table>

```json Example theme={null}
{
  "id": "367783",
  "type": "AudienceSegment",
  "attributes": {
    "name": "Sample lookalike",
    "description": "Sample lookalike segment",
    "type": "Lookalike",
    "createdAt": "2023-01-26T19:21:30.76",
    "updatedAt": "2023-01-26T19:21:30.76",
    "advertiserId": "44981",
    "lookalike": {
      "seedSegmentId": "324415",
      "targetSize": 5000000
    }
  },
},
```

<Warning>
  **Updating Lookalike segments**

  It's not possible to update the seed of a lookalike segment, if you need to use another seed, create a new segment instead.
</Warning>

### Retargeting

The retargeting segments enable you to focus on specific groups of website visitors based on the timeframes since their last visit. You have the option to target buyers, non-buyers, or all visitors.

<table>
  <thead>
    <tr>
      <th>
        <p>
          Field name
        </p>
      </th>

      <th>
        <p>
          Type
        </p>
      </th>

      <th>
        <p>
          Optional / Required / Computed
        </p>
      </th>

      <th>
        <p>
          Description
        </p>
      </th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>
        <p>
          <b>
            Retargeting
          </b>
        </p>
      </td>

      <td>
        <p>
          Retargeting
        </p>
      </td>

      <td>
        <p>
          Optional
        </p>
      </td>

      <td>
        <p>
          Indicates that this should be an Audience Segment of type

          <b>
            Retargeting
          </b>
        </p>
      </td>
    </tr>
  </tbody>
</table>

<table>
  <thead>
    <tr>
      <th>
        <p>
          Name
        </p>
      </th>

      <th>
        <p>
          Type
        </p>
      </th>

      <th>
        <p>
          Optional/Required
        </p>
      </th>

      <th>
        <p>
          Description
        </p>
      </th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>
        <p>
          visitorsType
        </p>
      </td>

      <td>
        <p>
          VisitorsType
        </p>

        <p>
          Can take three values:
        </p>

        <p>
          *

          <code>
            All
          </code>
        </p>

        <ul>
          <li>
            <code>
              Buyers
            </code>
          </li>
        </ul>

        <p>
          *

          <code>
            NonBuyers
          </code>
        </p>
      </td>

      <td>
        <p>
          Required
        </p>
      </td>

      <td>
        <p>
          The type of users being targeted.
        </p>
      </td>
    </tr>

    <tr>
      <td>
        <p>
          daysSinceLastVisitMin
        </p>
      </td>

      <td>
        <p>
          Integer
        </p>
      </td>

      <td>
        <p>
          Required
        </p>
      </td>

      <td>
        <p>
          Include users who visited your website before this number of days
        </p>
      </td>
    </tr>

    <tr>
      <td>
        <p>
          daysSinceLastVisitMax
        </p>
      </td>

      <td>
        <p>
          Integer
        </p>
      </td>

      <td>
        <p>
          Required
        </p>
      </td>

      <td>
        <p>
          Include users who visited your website after this number of days
        </p>
      </td>
    </tr>
  </tbody>
</table>

```json Example theme={null}
{
    "data": [
        {
            "id": "1002",
            "type": "AudienceSegment",
            "attributes": {
                "name": "My retargeting segment",
                "description": {
                    "value": "A segment with buyers"
                },
                "retargeting": {
                    "visitorsType": "Buyers",
                    "daysSinceLastVisitMin": 10,
                    "daysSinceLastVisitMax": 60
                }
            }
        }
    ]
}
```

## **Operations**

### Get a list of available In-market interests.

<EndpointBadge method="get">
  ```http theme={null}
   /marketing-solutions/audience-segments/in-market-interests
  ```
</EndpointBadge>

Returns a list with all available In-market interests that can be used to define an In-market audience segment. These In-market interests correspond to the Google product taxonomy. An In-market interest is considered available if there is enough volume for this particular In-market interest in the given country.

<table>
  <thead>
    <tr>
      <th>
        <p>
          Name
        </p>
      </th>

      <th>
        <p>
          Required / Optional
        </p>
      </th>

      <th>
        <p>
          Description
        </p>
      </th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>
        <p>
          advertiser-id
        </p>
      </td>

      <td>
        <p>
          required
        </p>
      </td>

      <td>
        <p>
          The Advertiser Id
        </p>
      </td>
    </tr>

    <tr>
      <td>
        <p>
          country
        </p>
      </td>

      <td>
        <p>
          required
        </p>
      </td>

      <td>
        <p>
          The ISO 3166-1 alpha-2 country code
        </p>
      </td>
    </tr>
  </tbody>
</table>

### Get a list of available In-market brands.

Returns a list with all available In-market brands that can be used to define an In-market audience segment. An In-market brand is considered available if there is enough volume for this particular In-market brand in the given country.

<EndpointBadge method="get">
  ```http theme={null}
  /marketing-solutions/audience-segments/in-market-brands
  ```
</EndpointBadge>

<table>
  <thead>
    <tr>
      <th>
        <p>
          Name
        </p>
      </th>

      <th>
        <p>
          Required / Optional
        </p>
      </th>

      <th>
        <p>
          Description
        </p>
      </th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>
        <p>
          advertiser-id
        </p>
      </td>

      <td>
        <p>
          required
        </p>
      </td>

      <td>
        <p>
          The Advertiser Id
        </p>
      </td>
    </tr>

    <tr>
      <td>
        <p>
          country
        </p>
      </td>

      <td>
        <p>
          required
        </p>
      </td>

      <td>
        <p>
          The ISO 3166-1 alpha-2 country code
        </p>
      </td>
    </tr>
  </tbody>
</table>

## **Create Audience Segments**

Create audience segments in bulk mode. Creates all audience segments with a valid configuration and returns their IDs with their advertiser IDs, names, and creation/update dates. One or multiple errors are returned for those that cannot be created.

<EndpointBadge method="post">
  ```http theme={null}
  /marketing-solutions/audience-segments/create
  ```
</EndpointBadge>

<CodeGroup>
  ```json Sample Request expandable theme={null}
  {
    "data": [
      {
        "type": "AudienceSegment",
        "attributes": {
          "name": "My contact list segment",
          "description": "An audience segment which targets my customer's database",
          "advertiserId": "4949",
          "contactList": {}
        }
      },
      {
        "type": "AudienceSegment",
        "attributes": {
          "name": "My In-market segment",
          "description": "An audience segment which targets people interested in Adidas shoes",
          "advertiserId": "4949",
          "inMarket": {
            "country": "FR",
            "interestIds": [
              "928"
            ],
            "brandIds": [
              "289"
            ]
          }
        }
      },
      {
              "type": "AudienceSegment",
              "attributes": {
                  "name": "My Prospecting segment",
                  "description": "An audience segment which targets people similar to my website visitors",
                  "advertiserId": "4949",
                  "prospecting": { }
              }
          },
      {
        "type": "AudienceSegment",
        "attributes": {
          "name": "Lookalike segment",
          "description": "Lookalike description",
          "advertiserId": "4949",
          "lookalike": {
            "seedSegmentId": "335274",
            "targetSize": 5000000
          }
        }
      },
      {
        "type": "AudienceSegment",
        "attributes": {
          "name": "My retargeting segment",
          "description": {
            "value": "A segment including buyers"
          },
          "retargeting": {
            "visitorsType": "Buyers",
            "daysSinceLastVisitMin": 10,
            "daysSinceLastVisitMax": 60
          }
        }
      }
    ]
  }
  ```

  ```json Sample Response (Success) expandable theme={null}
  {
    "data": [
      {
        "id": "1001",
        "type": "AudienceSegment",
        "attributes": {
          "name": "My contact list segment",
          "type": "ContactList",
          "description": "Contact list description",
          "createdAt": "2023-05-09T16:30:50.4633333",
          "updatedAt": null,
          "advertiserId": "4949",
          "contactList": {
            "isReadOnly": false
          }
        }
      },
      {
        "id": "1002",
        "type": "AudienceSegment",
        "attributes": {
          "name": "My In-market segment",
          "type": "InMarket",
          "description": "In-Market description",
          "createdAt": "2023-05-09T16:30:50.4633333",
          "updatedAt": null,
          "advertiserId": "4949"
        }
      },
      {
              "id": "1003",
              "type": "AudienceSegment",
              "attributes": {
                  "name": "My Prospecting segment",
                  "createdAt": "2018-07-04T00:00:00Z",
                  "updatedAt": null,
                  "advertiserId": "4949"
              }
          },
      {
        "id": "335275",
        "type": "AudienceSegment",
        "attributes": {
          "name": "Lookalike segment",
          "description": "Lookalike description",
          "type": "Lookalike",
          "createdAt": "2023-05-09T16:30:50.4633333",
          "updatedAt": "2023-05-09T16:30:50.4633333",
          "advertiserId": "4949",
          "lookalike": {
            "seedSegmentId": "335274",
            "targetSize": 5000000
          }
        }
      },
      {
        "id": "129221",
        "type": "AudienceSegment",
        "attributes": {
          "name": "My retargeting segment",
          "description": {
            "value": "A segment including buyers"
          },
          "type":"Retargeting",
          "createdAt": "2023-05-09T16:30:50.4633333",
          "updatedAt": "2023-05-09T16:30:50.4633333",
          "retargeting": {
            "visitorsType": "Buyers",
            "daysSinceLastVisitMin": 10,
            "daysSinceLastVisitMax": 60
          }
        }
      }
    ],
      "errors": [     /* omitted if no errors */
          ...
      ],
      "warnings": [   /* omitted if no warnings */
          ...
      ]
  }
  ```
</CodeGroup>

<Warning>
  To create a contact list audience segment, you need to add an empty *contactList* parameter, as you can see in the example. To define the content of this audience segment, you should refer to the section [Manage Contact Lists](/marketing-solutions/v2025.10/docs/audience-segments#manage-contact-lists).
</Warning>

## **Update Audience Segments**

Update audience segments in bulk mode. Updates the properties of all audience segments with a valid configuration and returns their IDs with their advertiser IDs, names, and creation/update dates. One or multiple errors are returned for those that cannot be updated.

<Info>
  **Partial Update Request: Modifying Segment Attributes**

  When building the update request, you don't need to include all the fields of the Segment. Provide the Id, type and the attributes you would like to modify.
</Info>

<EndpointBadge method="patch">
  ```http theme={null}
  /marketing-solutions/audience-segments
  ```
</EndpointBadge>

<CodeGroup>
  ```json Sample Request expandable theme={null}
  {
    data: [
      {
        id: "1001",
        type: "AudienceSegment",
        attributes: {
          name: "My contact list segment (v2)",
        },
      },
      {
        id: "1002",
        type: "AudienceSegment",
        attributes: {
          name: "My In-market segment (v2)",
          description: {
            value: "A segment which targets men interested in expensive Adidas shoes",
          },
          inMarket: {
            gender: "Male",
            priceRange: ["High"],
          },
        },
      },
      {
        id: "335275",
        type: "AudienceSegment",
        attributes: {
          name: "Lookalike segment (v2)",
          lookalike: {
            targetSize: 5000000,
          },
        },
      },
    ],
  }
  ```

  ```json Sample Response (Success) expandable theme={null}
  {
   ... 
     "data":[
        {
           "id":"1001",
           "type":"AudienceSegment",
           "attributes":{
              "name":"My contact list segment (v2)",
              "createdAt":"2018-07-04T00:00:00Z",
              "updatedAt":"2022-10-28T11:55:20.77",
              "advertiserId":"4949",
              "contactList":{
                 "isReadOnly":false
              }
           }
        },
        {
           "id":"1002",
           "type":"AudienceSegment",
           "attributes":{
              "name":"My In-market segment (v2)",
             "description":"A segment which targets men interested in expensive Adidas shoes",
              "createdAt":"2018-07-04T00:00:00Z",
              "updatedAt":"2022-10-28T11:55:20.77",
              "advertiserId":"4949"
           }
        },
        {  "id":"335275",
           "type":"AudienceSegment",
           "attributes":{
              "name":"Lookalike update",
              "description":"lookalike desc update",
              "type":"Lookalike",
              "createdAt":"2022-10-28T10:57:13.363",
              "updatedAt":"2022-10-28T11:55:20.77",
              "advertiserId":"4949",
              "lookalike":{
                 "seedSegmentId":"335274",
                 "targetSize":5000000
              }
           }
        }
     ],
   
      "errors": [     /* omitted if no errors */
          ...
      ],
      "warnings": [   /* omitted if no warnings */
          ...
      ]
  }
  ```
</CodeGroup>

<Warning>
  To update contact lists within an audience segment, refer to the section [Manage Contact Lists](/marketing-solutions/v2025.10/docs/audience-segments#manage-contact-lists).
</Warning>

## **Search Audience Segments**

Search audience segments by audience segment IDs, audience segment types, or advertiser IDs. It returns a list of audience segments that match the provided attributes. If present, the attributes are AND'ed together when applied (will only return the segments that satisfy ALL those conditions).

<EndpointBadge method="post">
  ```http theme={null}
  /marketing-solutions/audience-segments/search
  ```
</EndpointBadge>

<CodeGroup>
  ```json Sample Request theme={null}
  {
      "data": {
          "attributes": {
              "advertiserIds": [
                  "44981",
                  "4949"
              ],
              "audienceSegmentIds": null,
              "audienceSegmentTypes": [
                  "In-market",
                  "Location"
              ]
          }
      }
  }
  ```

  ```json Sample Response (Success) expandable theme={null}
  {
      "meta": {
          "totalItems": 400,
          "limit": 50,
          "offset": 0
      },
      "data": [
          {
              "id": "1001",
              "type": "AudienceSegment",
              "attributes": {
                  "name": "My In-market segment",
                  "description": "A segment which targets people interested in Adidas shoes",
                  "createdAt": "2018-07-04T00:00:00Z",
                  "updatedAt": "2018-07-15T00:00:00Z",
                  "advertiserId": "4949",
                  "inMarket": {
                      "country": "FR",
                      "interestIds": ["928"],
                      "brandIds": ["289"]
                  }
              },
          },
          /* more search results */
      ],
      "errors": [     /* omitted if no errors */
          ...
      ],
      "warnings": [   /* omitted if no warnings */
          ...
      ]
  }
  ```
</CodeGroup>

## **Delete Audience Segments**

Delete audience segments in bulk mode. Deletes the audience segments associated with the given audience IDs.

<EndpointBadge method="post">
  ```http theme={null}
  /marketing-solutions/audience-segments/delete
  ```
</EndpointBadge>

<CodeGroup>
  ```json Sample Request theme={null}
  {
      "data": [
          {
              "id": "1002",
              "type": "AudienceSegment"
          },
          {
              "id": "1001",
              "type": "AudienceSegment"
          }
      ]
  }
  ```

  ```json Sample Response theme={null}
  {
      ...
      "errors": [     /* omitted if no errors */
          ...
      ],
      "warnings": [   /* omitted if no warnings */
          ...
      ]
  }
  ```
</CodeGroup>

## **Compute Audience Segment sizes**

If you have already created one or more segments, and would like to know their size, you can do so by using tis endpoint. It returns the size of one or more audience segment IDs (if available and if supported). For those whose size cannot be retrieved, one or multiple errors are returned.

<EndpointBadge method="post">
  ```http theme={null}
  /marketing-solutions/audience-segments/compute-sizes
  ```
</EndpointBadge>

<CodeGroup>
  ```json Sample Request Body theme={null}
  {
      "data": [
          {
              "id": "1001", 
              "type": "AudienceSegmentSize",
              "attributes": {
                  "size": 194730
              }
          },
          {
              "id": "1002", 
              "type": "AudienceSegmentSize",
              "attributes": {
                  "size": 4285
              }
          },
          {
              "id": "1003", 
              "type": "AudienceSegmentSize",
              "attributes": {
                  "size": 978597
              }
          }
      ]
  }
  ```

  ```json Response Body - Failure theme={null}
  {
      "errors": [
          {
              "type": "validation",
              "code": "audience-segment-not-found",
              "instance": "@data/0",
              ...
          },
          {
              "type": "validation",
              "code": "audience-segment-size-not-available",
              "instance": "@data/1",
              ...
          },
          {
              "type": "validation",
              "code": "audience-segment-size-not-supported",
              "instance": "@data/2",
              ...
          }
      ],
      "warnings": [   /* omitted if no warnings */
          ...
      ]
  }
  ```
</CodeGroup>

## **Estimate Audience Segment size**

If you know the structure of your segment, but have not created it yet, and would like to estimate its size, you can use this endpoint. It returs the size estimation for an audience segment (if available and if supported). If the size cannot be estimated, an error is returned. This endpoint is resource-intensive, this is why the bulk workflow is not supported.

<EndpointBadge method="post">
  ```http theme={null}
  /marketing-solutions/audience-segments/estimate-size
  ```
</EndpointBadge>

<CodeGroup>
  ```json Sample Request Body theme={null}
  {
      "data": {
          "type": "AudienceSegment",
          "attributes": {
              "advertiserId": "4949",
              "inMarket": {
                  "country": "FR",
                  "interestIds": ["928"],
                  "brandIds": ["289"],
              }
          }
      }
  }
  ```

  ```json Response Body - Success theme={null}
  {
      "data": {
          "type": "AudienceSegmentSize",
          "attributes": {
              "size": 194730
          }
      }
  }
  ```

  ```json Response Body - Failure theme={null}
  {
      "errors": [
          {
              "type": "validation",
              "code": "audience-segment-size-too-small",
              "instance": "/audience-segments/size-estimation",
              ...
          }
      ],
      "warnings": [   /* omitted if no warnings */
          ...
      ]
  }
  ```
</CodeGroup>

## **Manage Contact Lists**

After creating an audience segment of the type *contact list*, you can use the following endpoints to update its content.

### Adding and Removing Users

<EndpointBadge method="patch">
  ```http theme={null}
  /marketing-solutions/audience-segments/{audience-segment-id}/contact-list
  ```
</EndpointBadge>

Users can be added or removed from an audience segment with a PATCH request to the audience contact list endpoint with the specific audience segment 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 in plain text, MD5, SHA256 or SHA256MD5-hashed), 'madid' (Mobile Ad Identifier), 'identityLink' (a user's LiveRamp Identity Link), 'gum' (Criteo GUM cookie identifier), 'customerid' (only for Retail Media Customer Lists) and 'phonenumber" (plain text or sha256 hashed phone numbers, only supported for advertisers in India).

<Info>
  **GUM ID**

  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>

<Info>
  **Phone number format**

  #### Clear phone number

  A clear phone number needs to have the “+” sign and the country code, it can contain spaces or “-” or both. example: +33 01 23 45 67 89, +330123456789, +330123-45-6789

  #### Sha256 hashed phone number

  The original clear phone number before sha256 should be normalized:

  1. Trimmed E.164 format including the country code
  2. without the leading "+" sign (so only 15 digits, at most): sha256 (for example,  `internationalPhoneNumber.replaceAll(/[^0-9]/g, "")`)
</Info>

#### Adding Users

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

<CodeGroup>
  ```json Example PATCH Request - Adding Users theme={null}
  {
    "data": {
      "type": "ContactlistAmendment",
      "attributes": {
          "operation": "add",
          "identifierType": "email",
          "identifiers": [
              "example1@gmail.com"
          ]
      }
    }
  }
  ```

  ```json Example PATCH Request - Adding Users (SHA256 emails) theme={null}
  {
    "data": {
      "type": "ContactlistAmendment",
      "attributes": {
          "operation": "add",
          "identifierType": "email",
          "identifiers": [
              "8614620f4b7591e9270b91928299e1de99456e9f1883eadef140b6fc12c92830",
              "97e2a275de13f3cef1f16a333baf450fcf3d58ecc7c1e509bfec91462420f3a0"
          ]
      }
    }
  }
  ```
</CodeGroup>

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

```json Example Response Body - Adding Users 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": []
}
```

#### Removing Users

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

```json Example PATCH Body - Removing Users theme={null}
{
  "data": {
    "type": "ContactlistAmendment",
    "attributes": {
        "operation": "remove",
        "identifierType": "email",
        "identifiers": [
            "example1@gmail.com"
        ]
    }
  }
}
```

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

```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": []
}
```

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

### Deleting All Users

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

<EndpointBadge method="delete">
  ```http theme={null}
  /marketing-solutions/audience-segments/{audience-segment-id}/contact-list
  ```
</EndpointBadge>

The API will return an array with the specified **audience-segment-id** from which all users were deleted.

```json Example Response Body theme={null}
{
    "data": {
        "type": "ContactListAudienceSegment",
        "id": "12"
    },
    "errors": [],
    "warnings": []
}
```

<Info>
  Note that this will only wipe all of the users from the audience segment and will not delete the audience segment 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>

### Get Segment Statistics

Get the statistics of the contact list audience segment associated with the given ID. It returns the size and other statistics available for an audience segment of the type contact list. If the given ID is not of the type contact list, an error is returned.

`audience-segment-id` is the Id of the Contact List segment.

<EndpointBadge method="get">
  ```http theme={null}
  /marketing-solutions/audience-segments/{audience-segment-id}/contact-list/statistics
  ```
</EndpointBadge>

<CodeGroup>
  ```json Sample Response (Success) theme={null}
  {
      "data": {
          "id": "1001",
          "type": "ContactListAudienceSegment"
          "attributes": {
              "numberOfIdentifiers": 1000,
              "numberOfMatches": 500,
              "matchRate": 0.50
          }
      }
  }
  ```
</CodeGroup>

<Warning>
  This statistic is not an estimation of the audience size. For it, refer to the [Estimate Audience Segment Size](/marketing-solutions/v2025.10/docs/audience-segments#estimate-audience-segment-size) section.
</Warning>

## **Validation Errors**

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

Below is a list of error codes for Audience Segment Endpoints, and a more detailed description of their meaning. For more codes don't hesitate to check also the [Audiences validation errors](/marketing-solutions/v2025.10/docs/audiences#validation-errors)

`advertiser-must-be-opt-in-for-data-sharing`

Advertiser must be opt in for data sharing

`brand-list-must-be-valid`

Brand list must be valid

`buying-power-must-be-valid`

Buying power must be valid

`cannot-create-contact-list`

Contact list creation error

`in-market-settings-must-be-defined`

In-market segment settings must be defined

`contact-list-incompatible-with-file`

Contact list is incompatible with file

`contact-list-statistics-not-supported`

Contact list statistics are not supported on this segment

`country-code-is-required`

Country code is required

`country-code-must-be-authorized`

Country code must be authorized

`country-code-must-be-valid`

Country code must be valid

`days-must-be-in-range`

Days in omnichannel segment must be in range

`event-type-must-be-valid`

Event type must be valid

`file-id-must-be-valid`

File ID must be valid

`gender-must-be-valid`

Gender must be valid

`interests-list-must-be-valid`

Interest list must be valid

`name-must-be-unique`

Name must be unique

`name-must-not-be-empty`

Name must not be empty

`name-must-not-be-too-long`

Segment name property must not be too long

`percentile-must-be-in-range`

Percentile must be in range

`poi-coordinates-must-be-unique`

Points of interest coordinates must be unique

`poi-coordinates-must-be-valid`

Points of interest coordinates must be valid

`poi-list-must-be-not-empty`

Points of interest list must be nor null nor empty

`poi-list-must-be-null-or-empty`

Points of interest list must be null or empty

`poi-radius-must-be-not-null`

Location segment of type 'Unknown' must have a radius

`poi-surface-must-be-valid`

Points of interest surface area must be valid

`price-range-must-be-valid`

Price range must be valid

`radius-must-be-in-range`

RadiusInKm must be in range

`registry-type-must-be-valid`

Registry type must be valid

`retargeting-segment-days-since-last-visit-are-not-compatible`

Retargeting segment MinDaysSinceLastVisit and MaxDaysSinceLastVisit are not compatible

`retargeting-segment-days-since-last-visit-are-not-in-acceptable-range`

Retargeting segment MinDaysSinceLastVisit and MaxDaysSinceLastVisit are not in the range of acceptable values

`segment-has-not-been-found`

Segment does not exist

`segment-must-have-valid-segment-id`

Segment must have a valid segment ID

`segment-must-not-be-used-in-audience`

Segment must not be used in an audience

`segment-not-found`

Segment not found

`segment-size-not-available`

Segment size not available

`segment-size-not-available`

Segment size cannot be calculated

`segment-size-not-supported`

Segment size not supported

`segment-size-too-small`

Segment size is too small

`type-must-be-the-same`

Type must be the same

`Target size must be within the supported rage`

In Lookalike Audience Segments, given target size must be within the supported rage. Lower and Upper bound will be included in error details.

`Seed segment does not belong to the same advertiser`

For Lookalike Audience Segments,  the seed segment (seedSegmentId input value) should have the same advertiser Id as the newly created Lookalike segment.

`retargeting-segment-from-to-days-ago-are-not-compatible`

The From days ago value should be lower than To days ago

`retargeting-segment-from-to-days-ago-are-not-in-acceptable-range`

Days must be in range: 400 >= ToDaysAgo > FromDaysAgo >= 0

`audience-with-retargeting-segment-must-be-correctly-specified`

The retargeting segment must be the unique segment in its audience