Audience Management API

If you are using, or want to use, the Pulse Audience Management functionality, the Audience Management API allows you to manage the audience segmentations and audience segments for your audience providers, and upload your audience data batch files to assign viewers to the desired segmentations and segments so INVIDI Pulse can target them accordingly.

Prerequisites

Before you start using this API, see Pulse Audience Management to get an overview of the functionality and understand its requirements and limitations.

Getting started

  • Base URL: https://api.videoplaza.com/v1/audience
    Note:

    When using the Batch upload requests, you must prefix the base URL with your region, either eu for European customers or asia for Asian customers.

    • Europe: https://eu.api.videoplaza.com/v1/audience
    • Asia: https://asia.api.videoplaza.com/v1/audience
  • Requests: GET, POST, and PUT requests are used. You pass parameters by using common REST parameters like PATH, as well as HTTP HEADERS. The body of the requests should be encoded using UTF-8 and provided in JSON format, except for the Batch upload requests, which are provided in pipe-delimited text file format.
  • Responses: All responses contain an HTTP status code in the header and the body is in JSON format.
  • Swagger documentation: Audience Management API
  • Related integration documentation: Pulse Audience Management
  • Related API tutorial: Audience Management API tutorial

Key terms

  • Audience data provider: a provider of demographic data - Data Management Platform (DMP). When a DMP integration is created, it can be enabled or disabled.
  • Audience segmentation: a grouping of related segments, for example Age, Gender, or Interests.
  • Audience segment: a specific segment in the audience segmentation, for example 10-14 years or 55-64 years can be segments of the Age segmentation.
  • Audience data batch file: refers to a collection of audience data rows. Each audience data row represents a viewer, who is tied to a unique persistent identifier (PID), and specifies the audience segmentations and audience segments the viewer belongs to so Pulse can target them accordingly. The audience data batch files are uploaded to and stored in your region's session store (either eu or asia).
  • PID: persistent identifier, a unique ID (preferably GUID or UUID format) that identifies the end user (your viewer) and persists across sessions. This parameter should be generated the very first time a viewer uses the video player. The parameter should be stored and reused for every future session. It is the basis for frequency capping, uniqueness tracking, goal sequencing, session clash protection, and audience targeting across platforms and devices. For more information, see Persistent identifier (PID).
  • Session store: a database where Pulse stores viewer sessions linked with their unique persistent identifier (PID). Session-related data is stored in key-value pairs, where the key is a PID and the value is an object of, for example, audience data or frequency capping data.

Data integration structure

This is a high-level overview of a DMP integration required to start using audience targeting in Pulse.

High-level integration overview

The table below describes the parameters that identify each unique targeting segment, allowing Pulse to match the information coming from the audience provider with the targeting segments displayed to a Pulse user. segmentationId and segmentId are Pulse assigned IDs and cannot be modified.

Parameter Type Description Note
segmentationId Integer Value between 0-199, Pulse assigned ID for a single segmentation (a grouping of segments). Previously Index in (Deprecated) Segment identification CSV file.
segmentationKey String

Your own segmentation key (ID) sent in the async pixel request, used to parse incoming requests. For example, xyz.

You can use up to 255 characters. The following characters are allowed:
  • Letters: A through Z, and a through z
  • Numbers: 0 through 9
  • Other characters: - (hyphen) _ (underscore)
Previously Parameter Name in (Deprecated) Segment identification CSV file.
segmentationName String Segmentation name displayed in the Pulse UI, for example, Age or Gender. You can use up to 255 characters. Previously Key Label in (Deprecated) Segment identification CSV file.
segmentId Integer Value between 1-15, Pulse assigned ID for a single segment. Previously Value in (Deprecated) Segment identification CSV file.
segmentKey String

Your own segment key (ID) sent in the async pixel request, used to parse incoming requests. For example, 123.

You can use up to 255 characters. The following characters are allowed:
  • Letters: A through Z, and a through z
  • Numbers: 0 through 9
  • Other characters: - (hyphen) _ (underscore)
Previously Parameter Value in (Deprecated) Segment identification CSV file.
segmentName String Segment name displayed in the Pulse UI. For example, Male or Female. You can use up to 255 characters. Previously Value Label in (Deprecated) Segment identification CSV file.