Audience API Overview

The Audience API allows you to create and update CRM segments. It also allows you to manage data warehouses used with AdRoll SQL.

Note

The Audience API does not currently support all Segment Types. The Audience API currently supports these segment types. For unsupported segment types, you can use the AdRoll CRUD API.

Authentication

For details on how to authenticate, refer to Get Started with the AdRoll API.

Segment Types

The Audience API currently supports the following segment types:

crm
Segment users based on lists of emails
custom
Segment users based on lists of user IDs synced to AdRoll via Cookie Match
impression
Segment users based on number of impressions shown
user_events
Segment users based on user defined events
user_attributes
Segment users based on user defined attributes

Segment Response

A JSON dictionary representing a segment. Some info may only be present depending on the request method and segment type.

Key Data Type Description Segment Types
segment_id string Identifier used to represent this segment all
type string See Segment Types all
name string Name given to the segment upon creation all
duration long Number of days (1 to 540) members are valid in this segment custom
emails long Number of emails in the crm segment crm
ids long Number of users in the custom segment custom

Example Response:

{
    "result": "success",
    "segment": {
        "emails": 101,
        "name": "TestCRMSegment",
        "segment_id": "TESTSEGMENT1234567890X",
        "type": "crm"
    }
}

User Record

A user record is a JSON dictionary containing an identifier for an individual user.

Key Data Type Segment Type Description Required
email string crm Email RFC 5322 standard Y
id string custom Unique user identifier synced to AdRoll via Cookie Match Y

User Record examples

email (crm segment type):

{
  "email": "first.last@host.com"
}

id (custom segment type):

{
  "id": "user_identifier_1234"
}

Optionally, a timestamp can be added to indicate when a user entered a segment (the default timestamp is “now”). Valid timestamps can be up to 540 days old or up to 7 days in the future:

{
    "id": "user_identifier_1234",
    "ts": 1455342342
}