Audience Definition API V4

Overview

The Audience Definition API V4 is a group of endpoints that provides key management of audience definitions 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
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 segment targeting
Return segments by data provider, name, segment ID, ingestion status, and 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`
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 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
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