General Audience Management Workflow

Audience Management API V1 allows you to search, filter, and obtain descriptive metadata on segments available in Data Suite. You can also retrieve sizing estimates for segments and boolean combinations of segments, in the context of household reach and ID type across configurable geographic areas.

Using the Audience Management API V1 workflow, you can:

Retrieve lists of advertiser Industry categories
Retrieve lists of available Data Providers per relevant Industry category
Retrieve lists of Segments available from those Data Providers
Construct Audience Definitions using Segments

📘
You may wish to cache responses describing industry categories and available data providers rather than repeating them for every incremental workflow step.

Working with Audience Definitions

Once you have determined a satisfactory combination of segments, you can save the combination as an Audience Definition and export it to FreeWheel's core ad server. The Audience Definition can then be used for forecasting, ad selection, and reporting in MRM.

To work with an audience definition you need to:

Task	Notes
Create a temporary audience definition	This lets you see audience size estimates, but won't create a permanent resource in Data Suite.
Modify the temporary audience definition	Add and remove segments to change the size and composition of the audience definition until the desired state is met.
Create a permanent audience definition	In order to view sizing information and save a segment as part of an Audience Definition, the segment and its associated taxonomy metadata must have been previously ingested into Data Suite.
Retrieve an audience definition	You can paginate and filter your results.

Audience Management API V1 Glossary

Term	Definition
Segment	The most granular level of behavioral / demographic user grouping, as received by Data Suite from a data provider
Audience Definition	A boolean combination of one or more segments. A segment or segments must be saved under the heading of a parent Audience Definition in order to be exported to MRM for execution purposes. When creating boolean segment combinations within Audience Definitions: There is an AND relationship between targets. There is an OR relationship between segments within a target. Target_ids are segment IDs.
Industry	A business category descriptor associated with a given advertiser. Data usage restrictions are configurable against the Industry dimension. A truthful advertiser Industry must be declared for all Audience Definitions.
Audience Partner	The immediate upstream entity delivering a given segment to FreeWheel. For example, data vendor A is a reseller for segments owned by data vendor B. Data vendor A sends a segment owned by data vendor B to Data Suite. Data vendor A is the audience partner for that segment.
Data Provider	The root owner of a given segment. For example, data vendor A is a reseller for segments owned by data vendor B. Data vendor A sends a segment owned by data vendor B to Data Suite. Data vendor B is the data provider for that segment.

Segments Object

Name	Type	Description
id	String	FreeWheel-generated segment ID
name	String	FreeWheel-provided friendly name for the segment
audience_partner	String	FreeWheel-provided ID representing source of immediate upstream data export to FreeWheel
data_provider_id	String	FreeWheel-provided ID representing data owner upstream of audience_partner (if applicable.) This field is intended to accommodate data reseller arrangements.
data_source_id	String	FreeWheel-provided ID representing initial origin of the segment data. It is frequently the same value as data_provider_id, unless a segment was initially seeded by first-party data.
client_id	String	Numeric FreeWheel network ID of network(s) that have segment access. A value of -1 indicates the segment is available for use by any network.
level	Integer	Deprecated field, formerly used to indicate segment hierarchy where applicable. Expect value of 0.
parent_id	Integer	Deprecated field, formerly used to indicate segment hierarchy where applicable. Expect value of 0.
cpm	Integer	Cost per thousand
count	Integral	Segment membership size based on an estimate rather than the actual population. It is generated through the sketch function.
provider_segment_id	String	Segment ID provided by the audience partner

Audience Definition Object

Name	Type	Description
id	string	FreeWheel-generated audience ID
name	string	FreeWheel-provided friendly name for the audience
metadata	array	Embeds the segment and target objects.
segments	array	A subfield of metadata providing the segment metadata for all targets in the audience so that these properties can be added to your user interface (e.g. listing targets as names)
restrictions	integer(s)	Numeric FreeWheel industry IDs of industries not permitted to use a given segment
targets	array	The sub-fields within this array describe boolean relationships between segments in the Audience Definition. Target is synonymous with segment in this case. The relation between targets in the list is AND; in other words, the audience contains devices or IDs which satisfy all targets in the list. The relation between target_ids within a given target is OR; in other words, the ID may be found in any of the given segments, geo groups, etc. for the target.
kind	enum	include or exclude
type	string	The type of target: segment or geo
target_ids	string	Synonymous with FreeWheel segment ID(s)
std_dev	type	Absolute value of one standard deviation from the size estimate
estimate	integer	Size estimate
alias_type	string	The audience identifier type the estimate is for: cookies iid: individual level IDs hid: household level IDs maid: mobile device IDs ctv: ott device and smart tv IDs
lower_bound	integer	The lowest limit for your estimate
upper_bound	integer	The highest limit for your estimate
created_at	Timestamp, e.g., "2021-10-26T18:55:34.206244722Z"	The date and time at which your audience was created
updated_at	Timestamp, e.g., "2021-10-26T18:55:34.206244722Z"	The date and time at which your audience was updated
properties	string	Parameters: locked: True: indicates that an audience definition has been saved and exported to MRM, and thus is no longer eligible to be modified. False: indicates that an audience definition is still in draft. It has not been saved and exported to MRM, and thus is still eligible to be modified. user_industry_id: The FreeWheel numeric industry ID declared in the request that created the audience.

Data Provider Object

Name	Type	Description
id	string	FreeWheel-provided identifier for the data provider
label	string	FreeWheel-provided friendly name for the data provider. It generally has the same value as id (above).
restrictions	Integer	Indicates an Industry category ID that the data provider may have restricted from using its data. See Visibility and Restrictions in the Data Provider Object below.
visibility	Integer Segments from data provider X carrying hypothetical restriction 3, should only be made UI visible in the user interface to API users who have passed the industry ID associated with restriction 3.	Visibility IDs are numeric restriction IDs from the Segment Permissions API, which ensure that you see the best version of the data that you have permission to view. This field only exists to pass flags indicating restriction relationships. You can choose whether or not your user interface reflects the restrictions. See Visibility and Restrictions in the Data Provider Object below.

Visibility and Restrictions in the Data Provider Object

When you have rights to two sets of data for your application, one favored and one disfavored, the visibility ID acts as a complement to your restrictions; that is, if one data provider is restricted, then the other is visible and can be presented in your app.

The visibility ID indicates that, while the permission to use a disfavored data set exists, that data set should only be shown when the restriction to the favored data set is applied.

Scenarios

If you are restricted from seeing a particular data set, then that data is hidden and you can view the data from the provider from which you are not restricted.

If you are not restricted from seeing a particular data set, the visibility flag filters out the disfavored data set to which you have access and enables you to view the superior data sets. It is recommended that you use the favored data set.

Sample Business Use Case

Segment A and segment B have similar business purposes/definitions, but different underlying data sources. The data provider prefers to sell access to segment A over segment B, but for business reasons some clients may not be allowed to use segment A.

If an API user passes an industry ID that is restricted from using segment A, the desired user interface experience is to show segment B in its place.

If an API user passes an industry ID that is allowed to use segment A, then the desired user interface experience is to show only segment A, even though that user's industry ID is not restricted from using segment B.

Industry

See Industry Reference API.

Pagination Attributes

Name	Type	Description
page	integer	The number of pages for your list
per_page	integer	The number of results per page for your list
total_page	integer	The total number of pages in your returned list
total_count	integer	The total number of results returned in your list