The endpoints for the Audience Management API V1 facilitate:

  • The General Audience Management Workflow
  • Working with Audience Definitions


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:

Create a temporary audience definitionThis lets you see audience size estimates, but won't create a permanent resource in Data Suite.
Modify the temporary audience definitionAdd and remove segments to change the size and composition of the audience definition until the desired state is met.
Create a permanent audience definitionIn 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 definitionYou can paginate and filter your results.

Audience Management API V1 Glossary

SegmentThe most granular level of behavioral / demographic user grouping, as received by Data Suite from a data provider
Audience DefinitionA 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.
IndustryA 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 PartnerThe 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 ProviderThe 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

idStringFreeWheel-generated segment ID
nameStringFreeWheel-provided friendly name for the segment
audience_partnerStringFreeWheel-provided ID representing source of immediate upstream data export to FreeWheel
data_provider_idStringFreeWheel-provided ID representing data owner upstream of audience_partner (if applicable.) This field is intended to accommodate data reseller arrangements.
data_source_idStringFreeWheel-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_idStringNumeric FreeWheel network ID of network(s) that have segment access.  A value of -1 indicates the segment is available for use by any network.
levelIntegerDeprecated field, formerly used to indicate segment hierarchy where applicable. Expect value of 0.
parent_idIntegerDeprecated field, formerly used to indicate segment hierarchy where applicable. Expect value of 0.
cpmIntegerCost per thousand
countIntegralSegment membership size based on an estimate rather than the actual population. It is generated through the sketch function.
provider_segment_idStringSegment ID provided by the audience partner

Audience Definition Object

idstringFreeWheel-generated audience ID
namestringFreeWheel-provided friendly name for the audience
metadataarrayEmbeds the segment and target objects.
segmentsarrayA 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)
restrictionsinteger(s)Numeric FreeWheel industry IDs of industries not permitted to use a given segment
targetsarrayThe 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.
kindenuminclude or exclude
typestringThe type of target: segment or geo
target_idsstringSynonymous with FreeWheel segment ID(s)
std_devtypeAbsolute value of one standard deviation from the size estimate
estimateintegerSize estimate

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_boundintegerThe lowest limit for your estimate
upper_boundintegerThe highest limit for your estimate
created_atTimestamp, e.g., "2021-10-26T18:55:34.206244722Z"The date and time at which your audience was created
updated_atTimestamp, e.g., "2021-10-26T18:55:34.206244722Z"The date and time at which your audience was updated

  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

    idstringFreeWheel-provided identifier for the data provider
    labelstringFreeWheel-provided friendly name for the data provider. It generally has the same value as id (above).
    restrictionsIntegerIndicates 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.

    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.


    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.


    See Industry Reference API.

    Pagination Attributes

    pageintegerThe number of pages for your list
    per_pageintegerThe number of results per page for your list
    total_pageintegerThe total number of pages in your returned list
    total_countintegerThe total number of results returned in your list