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

Authentication

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

Segment Types

The Audience API currently supports the following segment types:

composite

Composite segments apply a set intersection relationship between two or more segments

crm

Segment users based on lists of emails

custom

Segment users based on lists of partner user IDs synced

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 attributes defined by third party data

crosschannel_lal

CrossChannel Lookalike Audiences gives you the ability to run campaigns seamlessly across inventory sources.

See Creating Audiences for examples of how to create these segments.

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 partner user identifier

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
}