The endpoints for the Audience Management API V1 facilitate:

  • The General Audience Management Workflow
  • Working with Audience Definitions

Authentication

For details on API authentication, see Authentication for FreeWheel Demand APIs.

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:

  1. Retrieve lists of advertiser Industry categories

  2. Retrieve lists of available Data Providers per relevant Industry category

  3. Retrieve lists of Segments available from those Data Providers

  4. 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:

  1. **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.
  2. **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