Audience Definition API V4

Overview

The Audience Definition API V4 is a group of endpoints that provides key management of audience definitions, geo groups, and audience segments. By creating an audience definition, publishers can exert granular control over the location and traits of their target audience. Once defined, audience definitions can be used in placement and campaign targeting.

Audience definitions are reusable objects for all sites and site sections within a network. Audience definitions may draw from multiple data sources across providers, as well as combine data sources into one definition. They are defined by the third-party audience tracking provider you have chosen to integrate with MRM, not by FreeWheel.

Feature	GET	POST	PUT	DELETE
Audience Definitions	X	X	X	X
Geo Groups	X	X
Segments	X

Leverage the Audience Definition API to accomplish the following tasks:

Retrieve metadata for all audience definitions in a network
Create and update an audience definition with geo group and segment targeting
Create geo groups by zip code
Search segments by data provider, name, ID, or number of segments per provider

Uniform Resource Identifiers (URI)

Feature	Production URI	Staging URI
Audience Definition	`https://api.freewheel.tv/services/v4/audience_definition`	`https://api.stg.freewheel.tv/services/v4/audience_definition`
Geo Group	`https://api.freewheel.tv/services/v4/audience_definition/geo_group`	`https://api.stg.freewheel.tv/services/v4/audience_definition/geo_group`
Segments	`https://api.freewheel.tv/services/v4/segment/{parameter}`	`https://api.stg.freewheel.tv/services/v4/segment/{parameter}`

Workflows

Update an Audience Definition with a Geo Group

Publisher

Requests all geo groups in the network with GET, or creates a new geo group with POST.

FreeWheel

Returns a geo group ID.

Publisher

Adds the geo group ID to the audience definition's location_targets array.

FreeWheel

Updates the audience definition with the new geo targeting.

Update an Audience Definition with a Segment

Publisher

Requests segments by data provider or name.

FreeWheel

Returns a list of segment IDs, as well as other segment information.

Publisher

Adds the segment ID to the audience definition's targets array.

FreeWheel

Updates the audience definition with the new segment targeting.

Attributes

Audience Definition Attributes

The following attributes are used when creating an audience definition with the POST method. This table also provides information on whether the attribute can be updated via PUT. For an interactive example, see Create Audience Definition.

Name	Type	Description	Mandatory?	Updatable?
id	integer	Audience definition ID used when updating	Yes	Yes
name	string	Name of the audience definition	Yes	Yes
description	string	Description of the audience definition	No	Yes
targets	array	Segment targeting of the audience definition	Yes	Yes
location_targets	array	Geo targeting of the audience definition	No	Yes
active	boolean	True if the audience definition should be activated, default value is false	No	Yes
graph_optimization	string	If the graph optimization is enabled. This is only applicable if the network graph optimization is set as "custom". Default empty string equals "off".	No	Yes

Targets Child Attributes

Name	Type	Description	Mandatory?	Updatable?
kind	string	INCLUDE or EXCLUDE from targeting	Yes	Yes
target_ids	array of strings	Array of FreeWheel segment IDs for targeting	Yes	Yes

Location Targets Child Attributes

Name	Type	Description	Mandatory?	Updatable?
kind	string	INCLUDE or EXCLUDE from targeting	No	Yes
target_ids	array of strings	Array of geo group IDs for targeting	No	Yes

Geo Group Attributes

The following attributes are used when creating a geo group with the POST method. This table also provides information on whether the attribute can be updated via PUT. For an interactive example, see Create Geo Group

Name	Type	Description	Mandatory?	Updatable?
name	string	Name of the geo group	Yes	No
description	string	Description of the geo group	No	No
postal_codes	array of strings	Postal codes to include in the geo group	Yes	No