Audience Segments

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

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.

In-market

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

A In-market object has the following parameters:

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

🚧

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:

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

A Location object has the following parameters:

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

A Behavioral object has the following parameters:

📘

List of Behavioral Segments

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

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

"prospecting":{}

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

A Lookalike Segment object has the following parameters:

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

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.

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

 /marketing-solutions/audience-segments/in-market-interests?advertiser-id={advertiser-id}&country={country}

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.

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.

/marketing-solutions/audience-segments/in-market-brands?advertiser-id={advertiser-id}&country={country}

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.

/marketing-solutions/audience-segments/create

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

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

🚧

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

/marketing-solutions/audience-segments

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

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

🚧

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 filters. If present, the filters are AND'ed together when applied (will only return the segments that satisfy ALL those conditions).

/marketing-solutions/audience-segments/search

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

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

Delete Audience Segments

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

/marketing-solutions/audience-segments/delete

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

{
    ...
    "errors": [     /* omitted if no errors */
        ...
    ],
    "warnings": [   /* omitted if no warnings */
        ...
    ]
}

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.

\

/marketing-solutions/audience-segments/compute-sizes

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

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

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.

/marketing-solutions/audience-segments/estimate-size

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

{
    "data": {
        "type": "AudienceSegmentSize",
        "attributes": {
            "size": 194730
        }
    }
}

{
    "errors": [
        {
            "type": "validation",
            "code": "audience-segment-size-too-small",
            "instance": "/audience-segments/size-estimation",
            ...
        }
    ],
    "warnings": [   /* omitted if no warnings */
        ...
    ]
}

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

/marketing-solutions/audience-segments/{audience-segment-id}/contact-list

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

📘

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, ""))

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

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.

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

{
  "data": {
    "type": "ContactlistAmendment",
    "attributes": {
        "operation": "remove",
        "identifierType": "email",
        "identifiers": [
            "[email protected]"
        ]
    }
  }
}

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

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.

/marketing-solutions/audience-segments/{audience-segment-id}/contact-list

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

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

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.

/marketing-solutions/audience-segments/{audience-segment-id}/contact-list/statistics

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