GuidesAPI ReferenceChangelog
GuidesAPI ReferenceChangelogLog In

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 Commerce Brand Id can take, use the /audience-segments/commerce-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

Commerce

Commerce segments can be used to target users based on high shopping intents and demographics.

Field name

Type

Optional / Required / Computed

Description

commerce

Commerce

Optional

Indicates that this should be an Audience Segment of type Commerce

A Commerce object has the following parameters:

Field name

Type

Optional / Required / Computed

Description

country

String

The ISO 3166-1 alpha-2 country code

Required (if commerce 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 commerce set)

Reach new people based on their commercial interests

brandIds

String array

Required (if commerce 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.

{
    "type": "AudienceSegment",
    "attributes": {
        "name": "My commerce segment",
        "description": "This is a segment for men in France who look for high priced products",
        "commerce": {
            "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 type Contact 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.

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

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

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

    }
}

Prebuilt

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

prebuilt

Prebuilt

Computed

Indicates that this should be an Audience Segment of type Prebuilt

A Prebuilt object has the following parameters:

Field name

Type

Optional / Required / Computed

Description

country

String

Computed

Country of the prebuilt audience segment (read-only).

📘

List of Prebuilt Segments

To get the list of the available Prebuilt segments you can use the Search endpoint filtering by Prebuilt type.

Similar

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

Field name

Type

Optional / Required / Computed

Description

similar

Similar

Optional

Indicates that this should be an Audience Segment of type Similar

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

"similar":{}

{
    "type": "AudienceSegment",
    "attributes": {
        "name": "My Similar Segment",
        "description": "Customers that are similar to my current website visitors"
        "advertiserId": "12345"
        "similar": {}
    }
}

Operations

Get a list of available commerce interests.

 https://api.criteo.com/preview/audience-segments/commerce-interests?advertiser-id={advertiser-id}&country={country}

Returns a list with all available commerce interests that can be used to define a commerce audience segment. These commerce interests correspond to the Google product taxonomy. A commerce interest is considered available if there is enough volume for this particular commerce 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 commerce brands.

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

https://api.criteo.com/preview/audience-segments/commerce-brands?advertiser-id={advertiser-id}&country={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.

https://api.criteo.com/preview/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 commerce segment",
                "description": "An audience segment which targets people interested in Adidas shoes",
                "advertiserId": "4949",
                "commerce": {
                    "country": "FR",
                    "interestIds": ["928"],
                    "brandIds": ["289"],
                }
            }
        },
        {
            "type": "AudienceSegment",
            "attributes": {
                "name": "My similar segment",
                "description": "An audience segment which targets people similar to my website visitors",
                "advertiserId": "4949",
                "similar": { }
            }
        },
    ]
}
{
    ...
    "data": [
        {
            "id": "1001",
            "type": "AudienceSegment",
            "attributes": {
                "name": "My contact list segment",
                "createdAt": "2018-07-04T00:00:00Z",
                "updatedAt": null,
                "advertiserId": "4949",
                "contactList": {
                    "isReadOnly": false
                }
            }
        },
        {
            "id": "1002",
            "type": "AudienceSegment",
            "attributes": {
                "name": "My commerce segment",
                "createdAt": "2018-07-04T00:00:00Z",
                "updatedAt": null,
                "advertiserId": "4949"
            }
        },
        {
            "id": "1003",
            "type": "AudienceSegment",
            "attributes": {
                "name": "My similar segment",
                "createdAt": "2018-07-04T00:00:00Z",
                "updatedAt": null,
                "advertiserId": "4949"
            }
        },
    ],
    "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.

https://api.criteo.com/preview/audience-segments
{
    "data": [
        {
            "id": "1002",
            "type": "AudienceSegment",
            "attributes": {
                "name": "My commerce segment (v2)",
                "description": {
                    value: "A segment which targets men interested in expensive Adidas shoes"
                },
                "commerce": {
                    "gender": "Male",
                    "priceRange": ["High"]
                }
            }
        },
        {
            "id": "1001",
            "type": "AudienceSegment",
            "attributes": {
                "name": "My contact list segment (v2)"
            }
        },
    ]
}
{
    ...
    "data": [
        {
            "id": "1001",
            "type": "AudienceSegment",
            "attributes": {
                "name": "My contact list segment (v2)",
                "createdAt": "2018-07-04T00:00:00Z",
                "updatedAt": "2018-07-15T00:00:00Z",
                "advertiserId": "4949",
                "contactList": {
                    "isReadOnly": false
                }
            }
        },
        {
            "id": "1002",
            "type": "AudienceSegment",
            "attributes": {
                "name": "My commerce segment (v2)",
                "createdAt": "2018-07-04T00:00:00Z",
                "updatedAt": "2018-07-15T00:00:00Z",
                "advertiserId": "4949"
            }
        },
    ],
    "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).

https://api.criteo.com/preview/audience-segments/search
{
    "filters":
    {
        "advertiserIds": ["44981", "4949"],
        "audienceSegmentIds": null,
        "audienceSegmentTypes": ["Commerce", "Location"]
    }
}
{
    "meta": {
        "totalItems": 400,
        "limit": 50,
        "offset": 0
    },
    "data": [
        {
            "id": "1001",
            "type": "AudienceSegment",
            "attributes": {
                "name": "My commerce 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",
                "commerce": {
                    "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.

https://api.criteo.com/preview/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.

\
https://api.criteo.com/preview/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.

https://api.criteo.com/preview/audience-segments/estimate-size
{
    "data": {
        "type": "AudienceSegment",
        "attributes": {
            "advertiserId": "4949",
            "commerce": {
                "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

https://api.criteo.com/preview/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) and 'gum' (Criteo GUM cookie identifier).

📘

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.

 

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.

https://api.criteo.com/preview/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.

https://api.criteo.com/preview/audience-segments/{audience-segment-id}/contact-list
{
    "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

undefined-advertiser-id

Cannot have an undefined advertiser ID

undefined-segment-type

Cannot have a segment object without any type defined

multiple-segment-types

Cannot have a segment object with multiple types defined

duplicate-name

Cannot have duplicated segment names

payload-too-big

Cannot create more than 50 segments at a time

payload-too-big

Cannot update more than 50 segments at a time

non-parsable-id

Segment ID cannot be parsed

duplicate-id

Segment ID cannot be duplicated

name-must-not-be-empty

Name must not be empty

name-must-not-be-too-long

Segment name property must not be too long

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

Segment must not be used in an audience

commerce-settings-must-be-defined

Commerce segment settings must be defined

event-type-must-be-valid

Event type must be valid

days-must-be-in-range

Days in omnichannel segment must be in range

cannot-create-contact-list

Contact list creation error

name-must-be-unique

Name must be unique

type-must-be-the-same

Type must be the same


Did this page help you?