Audience API Reference

Note

If you use the APIs provided here, you are subject to the API Terms of Use

Note

We’ve introduced API keys, please read Migrating to API Keys

Description

AdRoll Audience API 1.0 by apihelp@adroll.com

Manage your segments with the AdRoll Audience API

Operations

GET /audience/v1/advertisers

Retrieve list of accessible advertisers

Retrieve list of accessible advertisers

Parameters:

Query Parameters
Name Required Type Description
apikey False string Required if using HTTP Basic Authentication. The value is the Client ID you received when you registered your application on the AdRoll Developer site

Responses:

200 OK

List of Advertiser IDs

Schema as JSON:

{
  "data": [
    {
      "advertiser_id": "string"
    }
  ]
}
Schema
Type:object
data

List of Advertiser IDs

Required:True
Type:array of items
POST /audience/v1/domain_attributes

Fetch known attributes about a list of domains

Parameters:

Query Parameters
Name Required Type Description
apikey False string Required if using HTTP Basic Authentication. The value is the Client ID you received when you registered your application on the AdRoll Developer site

Schema for request body:

[
  "string"
]
Schema
Type:array

Responses:

200 OK

Attributes associated with the submitted domains

Returns DomainAttributesResponse

GET /audience/v1/segments

Retrieve list of segments

Retrieve list of segments

Parameters:

Query Parameters
Name Required Type Description
advertiser_id True integer EID of the advertiser to retrieve segment list for
type False string Filter by specified segment type One of: user_attributes, impression, custom, user_events, crm.
apikey False string Required if using HTTP Basic Authentication. The value is the Client ID you received when you registered your application on the AdRoll Developer site

Responses:

200 OK

A segment

Returns SegmentResponse

POST /audience/v1/segments

Create a new segment

Create a new segment

Parameters:

Query Parameters
Name Required Type Description
apikey False string Required if using HTTP Basic Authentication. The value is the Client ID you received when you registered your application on the AdRoll Developer site

Schema for request body: SegmentCreate

{
  "advertiser_id": "string", 
  "conversion_value": 0.0, 
  "data": [
    {
      "email": "string", 
      "id": "string"
    }
  ], 
  "is_conversion": true, 
  "name": "string", 
  "type": "string"
}

Responses:

200 OK

A segment

Returns SegmentResponse

POST /audience/v1/segments/bulk

Create or update a list of segments

Parameters:

Query Parameters
Name Required Type Description
apikey False string Required if using HTTP Basic Authentication. The value is the Client ID you received when you registered your application on the AdRoll Developer site

Schema for request body:

[
  {
    "advertiser_id": "string", 
    "conversion_value": 0.0, 
    "data": [
      {
        "email": "string", 
        "id": "string"
      }
    ], 
    "is_conversion": true, 
    "name": "string", 
    "type": "string"
  }
]
Schema
Type:array

Responses:

200 OK
List of results. Follows the request order. (See segment create and update responses)
GET /audience/v1/segments/(segment_id)

Retrieve segment information

Retrieve segment information

Parameters:

Path Parameters
Name Required Type Description
segment_id True string EID of the segment
Query Parameters
Name Required Type Description
apikey False string Required if using HTTP Basic Authentication. The value is the Client ID you received when you registered your application on the AdRoll Developer site

Responses:

200 OK

A segment

Returns SegmentResponse

POST /audience/v1/segments/(segment_id)

Update segment information and/or replace user list.

Users can be appended to a segment by including a list of the appropriate :ref:user-record objects in the payload

Parameters:

Path Parameters
Name Required Type Description
segment_id True string EID of the segment
Query Parameters
Name Required Type Description
apikey False string Required if using HTTP Basic Authentication. The value is the Client ID you received when you registered your application on the AdRoll Developer site

Schema for request body: SegmentUpdate

{
  "conversion_value": 0.0, 
  "data": [
    {
      "email": "string", 
      "id": "string"
    }
  ], 
  "duration": 0, 
  "name": "string"
}

Responses:

200 OK

A segment

Returns SegmentResponse

DELETE /audience/v1/segments/(segment_id)

Delete an existing segment

Delete an existing segment

Parameters:

Path Parameters
Name Required Type Description
segment_id True string EID of the segment
Query Parameters
Name Required Type Description
apikey False string Required if using HTTP Basic Authentication. The value is the Client ID you received when you registered your application on the AdRoll Developer site

Responses:

200 OK

A segment

Returns SegmentResponse

POST /audience/v1/segments_bulk/put

Create or update a list of segments

Parameters:

Query Parameters
Name Required Type Description
apikey False string Required if using HTTP Basic Authentication. The value is the Client ID you received when you registered your application on the AdRoll Developer site

Schema for request body:

[
  {
    "advertiser_id": "string", 
    "conversion_value": 0.0, 
    "data": [
      {
        "email": "string", 
        "id": "string"
      }
    ], 
    "is_conversion": true, 
    "name": "string", 
    "type": "string"
  }
]
Schema
Type:array

Responses:

200 OK
List of results. Follows the request order. (See segment create and update responses)
POST /audience/v1/user_attribute_counts

Retrieve user attribute counts for a pair of attribute name and value

Parameters:

Query Parameters
Name Required Type Description
apikey False string Required if using HTTP Basic Authentication. The value is the Client ID you received when you registered your application on the AdRoll Developer site

Schema for request body: UserAttributeCountsRequest

{
  "attributes": {}
}

Responses:

200 OK

A map of attribute names to values to count of users with that pair of name/value

Returns UserAttributeCountsResponse

GET /audience/v1/user_attribute_names/(advertisable_eid)

Retrieve user attributes associated with an advertisable

Parameters:

Path Parameters
Name Required Type Description
advertisable_eid True string EID of the advertisable
Query Parameters
Name Required Type Description
first_party False boolean Include first party attributes
third_party False boolean Include third party attributes
apikey False string Required if using HTTP Basic Authentication. The value is the Client ID you received when you registered your application on the AdRoll Developer site

Responses:

200 OK

List of user attributes associated with an advertisable

Returns AdvertisableAttributes

GET /audience/v1/warehouses

Fetch warehouses by advertisable EID

Parameters:

Query Parameters
Name Required Type Description
advertiser_id True string EID of advertisable attached to warehouse
apikey False string Required if using HTTP Basic Authentication. The value is the Client ID you received when you registered your application on the AdRoll Developer site

Responses:

200 OK

Database warehouse

Schema as JSON:

[
  {
    "advertiser_id": "string", 
    "comments": "string", 
    "created_date": 0, 
    "db_host": "string", 
    "db_name": "string", 
    "db_password": "string", 
    "db_port": 0, 
    "db_schema": "string", 
    "db_type": "string", 
    "db_username": "string", 
    "email_opt_in": true, 
    "id": 0, 
    "is_active": true, 
    "warehouse_eid": "string"
  }
]
Schema
Type:array
POST /audience/v1/warehouses

Create new warehouse

Parameters:

Query Parameters
Name Required Type Description
apikey False string Required if using HTTP Basic Authentication. The value is the Client ID you received when you registered your application on the AdRoll Developer site

Schema for request body:

{
  "advertiser_id": "string", 
  "db_host": "string", 
  "db_name": "string", 
  "db_password": "string", 
  "db_port": 0, 
  "db_type": "string", 
  "db_username": "string"
}
Schema
db_password

Password associated with db_username

Type:string
db_type

Type of database

Type:string
Enum:redshift, postgresql, mysql
db_port

Database port

Type:integer
advertiser_id

Advertisable EID of attached warehouse.

Type:string
db_name

Database name

Type:string
db_host

Host of database

Type:string
db_username

Username to connect to database with

Type:string

Responses:

200 OK

Database warehouse

Returns WarehouseResponse

DELETE /audience/v1/warehouses/(warehouse_eid)

Delete a warehouse specified by the warehouse EID

Parameters:

Path Parameters
Name Required Type Description
warehouse_eid True string  
Query Parameters
Name Required Type Description
apikey False string Required if using HTTP Basic Authentication. The value is the Client ID you received when you registered your application on the AdRoll Developer site

Responses:

204 No Content

Success response

Schema as JSON:

{}
Schema
Type:object

Definitions

UserAttributeCountsRequest
Type:object
attributes
Type:UserAttributeCountsRequestAttributes
AdvertisableAttributesDetail
Type:object
name
Type:string
SegmentCreate
Type:object
name

Name given to the segment upon creation

Required:True
Type:string
type
Required:True
Type:SegmentType
is_conversion

true if a segment is a conversion segment

Type:boolean
conversion_value

new conversion value to be associated with the conversion segment

Type:number
Format:float
advertiser_id

ID of the advertiser to create a new segment for

Required:True
Type:string
data

User records to add

Required:True
Type:array of UserRecord
SegmentResponse
Type:object
name

Name given to the segment upon creation

Required:True
Type:string
segment_id

Identifier used to represent this segment

Required:True
Type:string
is_conversion

true if a segment is a conversion segment else false

Type:boolean
ids

Number of users appended to a custom segment

Type:integer
Format:int64
conversion_value

conversion value associated with the conversion segment else null

Type:number
Format:float
duration
Type:Duration
type
Required:True
Type:SegmentType
emails

Number of emails appended to a crm segment

Type:integer
Format:int64
DomainAttributesResponse
Type:object
UserAttributeCountsRequestResult
Type:object
UserAttributeCountsRequestAttributes
Type:object
WarehouseResponse
Type:object
advertiser_id
Type:string
db_password
Type:string
Format:binary
db_type
Type:string
warehouse_eid
Type:string
is_active
Type:boolean
comments
Type:string
db_port
Type:integer
email_opt_in
Type:boolean
db_name
Type:string
db_host
Type:string
db_username
Type:string
created_date
Type:integer
db_schema
Type:string
id
Type:integer
AdvertisableAttributes
Type:object
attributes

List or detailed list of user attributes from an advertisable

Type:array of AdvertisableAttributesDetail
UserAttributeCountsResponse
Type:object
results
Type:UserAttributeCountsRequestResult
Duration

Number of days (1 to 540) members are valid in a segment

Type:integer
Maximum:540
Minimum:1
UserRecord
Type:object
email

Email RFC 5322 standard. Used with crm segments.

Type:string
id

Unique user identifier synced to AdRoll via Cookie Match. Used with custom segments.

Type:string
SegmentUpdate
Type:object
duration
Type:Duration
data

User records to add

Required:True
Type:array of UserRecord
name

Name shown on client’s dashboard

Required:True
Type:string
conversion_value

new conversion value to be associated with the existing conversion segment

Type:number
Format:float
SegmentType

Represents the segment type

Type:string
Enum:crm, custom, impression, user_events, user_attributes