Audience Segments - Criteo Docs

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

Static Values on Audience SegmentsSome 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.

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.

Field name and type	Possible value	Optional / Required / Computed	Description
id (String)		Required	Unique ID of the segment
name (String)		Required	Name of the segment. It must be unique per advertiser.
description (String)		Optional	Description of the segment
type (AudienceSegmentType)	`AudienceSegment`	Computed	Type of audience segment (read-only). Once created, the type cannot be changed.
createdAt (String)		Computed	ISO-8601 timestamp in UTC of segment creation (read-only)
updatedAt (String)		Computed	ISO-8601 timestamp in UTC of segment update (read-only)
advertiser Id (String)		Required	Advertiser associated to the segment

In-market

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

Field name	Type	Optional / Required / Computed	Description
In-market	In-market	Optional	Indicates that this should be an Audience Segment of typeIn-market

A In-market object has the following parameters:

Field name	Type	Optional / Required / Computed	Description
country	String The ISO 3166-1 alpha-2 country code	Required (if In-market is set)	Reach people of a specific country.
buyingPower	BuyingPower array BuyingPower can be: `Low` `Medium` `High` `VeryHigh`	Optional	Reach people who frequently purchase high price range items to lower price range items. If empty, don’t filter people based on buying power.
gender	Gender Gender can be: `Male` `Female`	Optional	Reach people who’ve shown interest in products made for a specific gender. If empty, don’t filter people based on gender.
interestIds	String array	Required (if In-market is set)	Reach new people based on their commercial interests
brandIds	String array	Required (if In-market is set)	Choose the commercial brands your segment might be interested in
priceRange	PriceRange array PriceRange can be: `Low` `Medium` `High`	Optional	Reach people who’ve shown interest in products within a specific price range. If empty, don’t filter people based on price range.

Example

{
    "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.

Field name	Type	Optional / Required / Computed	Description
contactList	ContactList	Optional	Indicates that this should be an Audience Segment of typeContact List

The contactList parameter should be empty on the creation of this type of audience segment. More details on Manage Contact Lists.

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

Field name	Type	Optional / Required / Computed	Description
isReadOnly	Boolean	Computed	True if the contact list-specific information cannot be edited through the public API, false otherwise. 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. Segments created in Commerce Growth will show up as`“isReadOnly”: true`on the Public API.

Field name

Type

Optional / Required / Computed

Description

isReadOnly

Boolean

Computed

True if the contact list-specific information cannot be edited through the public API, false otherwise.

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.

Segments created in Commerce Growth will show up as“isReadOnly”: trueon the Public API.

Example

{
            "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.

Field name	Type	Optional / Required / Computed	Description
location	Location	Optional	Indicates that this should be an Audience Segment of typeLocation

A Location object has the following parameters:

Field name	Type	Optional / Required / Computed	Description
registryType	RegistryType RegistryType can take only one value (for now): `PointsOfInterest`	Required (if location set)	The type of location audience segment
pointsOfInterest	PointsOfInterest array. Each point has a name, latitude and longitude	Required (if location set)	Reach users which have been historically located in the given coordinates
→ name	String	Required	Name of the point of interest
→ latitude	Decimal	Required	ISO-6709 latitude
→ longitude	Decimal	Required	ISO-6709 longitude
radiusInKm	Integer	Required (if location set)	The expected maximum distance in kilometers between a user and a point of interest

Example

{
    "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.).

Field name	Type	Optional / Required / Computed	Description
behavioral	Behavioral	Computed	Indicates that this should be an Audience Segment of typeBehavioral

A Behavioral object has the following parameters:

Field name	Type	Optional / Required / Computed	Default Value	Description
country	String	Computed		The user’s country
category	BehavioralCategory. Can take any of these values: `Lifestyles` `LifeEvents` `Seasonal` `BuyingPatterns`	Computed		The behavioral’s category
startDate	DateTime	Computed (can be empty)	Empty	The date when this audience segment will start to be filled with audience data
endDate	DateTime	Computed (can be empty)	Empty	The date when this audience segment will be cleaned of audience data

List of Behavioral SegmentsTo get the list of the available Behavioral segments you can use the Search endpoint filtering by Behavioral type.

Prospecting

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

Field name	Type	Optional / Required / Computed	Description
Prospecting	Prospecting	Optional	Indicates that this should be an Audience Segment of typeProspecting

A Prospecting object does not have any attributes, so you need to declare it empty. "prospecting":{}

Example

{
    "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.

Field name	Type	Optional / Required / Computed	Description
Lookalike	Lookalike	Optional	Indicates that this should be an Audience Segment of typeLookalike

A Lookalike Segment object has the following parameters:

Field	Type	Mandatory	Description
seedSegmentId	string	Yes	Id of existing Contact List or Event segment that will be treated as a seed.
targetSize	int64	No	The target size of the resulting segment after computation.

Example

{
  "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
    }
  },
},

Updating Lookalike segmentsIt’s not possible to update the seed of a lookalike segment, if you need to use another seed, create a new segment instead.

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.

Field name	Type	Optional / Required / Computed	Description
Retargeting	Retargeting	Optional	Indicates that this should be an Audience Segment of typeRetargeting

Name	Type	Optional/Required	Description
visitorsType	VisitorsType Can take three values: `All` `Buyers` `NonBuyers`	Required	The type of users being targeted.
daysSinceLastVisitMin	Integer	Required	Include users who visited your website before this number of days
daysSinceLastVisitMax	Integer	Required	Include users who visited your website after this number of days

Name

Type

Optional/Required

Description

visitorsType

VisitorsType

Can take three values:

All

Buyers

NonBuyers

Required

The type of users being targeted.

daysSinceLastVisitMin

Integer

Required

Include users who visited your website before this number of days

daysSinceLastVisitMax

Integer

Required

Include users who visited your website after this number of days

Example

{
    "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.

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.

Name	Required / Optional	Description
advertiser-id	required	The Advertiser Id
country	required	The ISO 3166-1 alpha-2 country code

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.

Name	Required / Optional	Description
advertiser-id	required	The Advertiser Id
country	required	The ISO 3166-1 alpha-2 country code

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.

{
  "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
        }
      }
    }
  ]
}

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.

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.

Partial Update Request: Modifying Segment AttributesWhen 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.

{
  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,
        },
      },
    },
  ],
}

To update contact lists within an audience segment, refer to the section Manage Contact Lists.

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

{
    "data": {
        "attributes": {
            "advertiserIds": [
                "44981",
                "4949"
            ],
            "audienceSegmentIds": null,
            "audienceSegmentTypes": [
                "In-market",
                "Location"
            ]
        }
    }
}

Delete Audience Segments

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

{
    "data": [
        {
            "id": "1002",
            "type": "AudienceSegment"
        },
        {
            "id": "1001",
            "type": "AudienceSegment"
        }
    ]
}

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.

{
    "data": [
        {
            "id": "1001", 
            "type": "AudienceSegmentSize",
            "attributes": {
                "size": 194730
            }
        },
        {
            "id": "1002", 
            "type": "AudienceSegmentSize",
            "attributes": {
                "size": 4285
            }
        },
        {
            "id": "1003", 
            "type": "AudienceSegmentSize",
            "attributes": {
                "size": 978597
            }
        }
    ]
}

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.

{
    "data": {
        "type": "AudienceSegment",
        "attributes": {
            "advertiserId": "4949",
            "inMarket": {
                "country": "FR",
                "interestIds": ["928"],
                "brandIds": ["289"],
            }
        }
    }
}

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

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

GUM IDGUM 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.

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:

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

Adding Users

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

{
  "data": {
    "type": "ContactlistAmendment",
    "attributes": {
        "operation": "add",
        "identifierType": "email",
        "identifiers": [
            "example1@gmail.com"
        ]
    }
  }
}

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.

Example Response Body - Adding Users

{
   "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:

Example PATCH Body - Removing Users

{
  "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.

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

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.

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. The API will return an array with the specified audience-segment-id from which all users were deleted.

Example Response Body

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

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.

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.

{
    "data": {
        "id": "1001",
        "type": "ContactListAudienceSegment"
        "attributes": {
            "numberOfIdentifiers": 1000,
            "numberOfMatches": 500,
            "matchRate": 0.50
        }
    }
}

This statistic is not an estimation of the audience size. For it, refer to the Estimate Audience Segment Size section.

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

​Audience Segment types

​In-market

​Contact List

​Location

​Behavioral

​Prospecting

​Lookalike

​Retargeting

​Operations

​Get a list of available In-market interests.

​Get a list of available In-market brands.

​Create Audience Segments

​Update Audience Segments

​Search Audience Segments

​Delete Audience Segments

​Compute Audience Segment sizes

​Estimate Audience Segment size

​Manage Contact Lists

​Adding and Removing Users

​Clear phone number

​Sha256 hashed phone number

​Adding Users

​Removing Users

​Deleting All Users

​Get Segment Statistics

​Validation Errors

Audience Segment types

In-market

Contact List

Location

Behavioral

Prospecting

Lookalike

Retargeting

Operations

Get a list of available In-market interests.

Get a list of available In-market brands.

Create Audience Segments

Update Audience Segments

Search Audience Segments

Delete Audience Segments

Compute Audience Segment sizes

Estimate Audience Segment size

Manage Contact Lists

Adding and Removing Users

Clear phone number

Sha256 hashed phone number

Adding Users

Removing Users

Deleting All Users

Get Segment Statistics

Validation Errors