Ooyala Pulse REST API

Find out how to integrate Ooyala Pulse, leverage its power and export data to external systems. For example, use Ooyala Pulse REST API to integrate with a standalone booking system that handles both display and video campaigns.

Overview

The Ooyala Pulse REST API is organised around the main resources available in the Ooyala Pulse user interface, which enables you to use this API to retrieve and alter items in the UI, with limitations. In order to use it, you need to be familiar with the key concepts, representing the endpoints (campaign, goal, client, targeting rules, campaign/inventory forecast ...), for the Ooyala Pulse platform available in the Ooyala Pulse User Guide.

You need to have an Ooyala Pulse account that you can test the API against and an API key so that you can make API calls. For more information, refer to Authentication.
Attention: We have made major changes in our authentication infrastructure to support the OAuth 2.0 protocol and we strongly recommend clients with existing integrations to upgrade as soon as possible. If you have an existing integration and want to upgrade, please contact your Account Manager for further assistance. For more information on the old way of authenticating, refer to Deprecated: Authenticating Using the X-VP-AUTH-API Key and X-VP-AUTH Token.
In order to follow the Pulse workflow more accurately, the various Pulse REST API components are organised into meaningful groups which cover the different workflow topics. For this reason, the different API components in each group have different:
  • base URLs,
  • communication formats,
  • Swagger documentation locations (where applicable).
The table below provides a general overview of the different Pulse REST API groups and their corresponding API components.
Pulse REST API group API components Description
Account Management APIs The Account Management APIs include endpoints for configuring and manipulating your Ooyala Pulse account settings, ad serving settings, the clients you work with, and your targeting templates, before you actually start booking campaigns.
Campaign Management APIs The Campaign Management APIs include endpoints for sucessfully booking a campaign, as well as managing any campaign and goal targeting rules. Each campaign consists of goals, and each goal consists of ads, to which you upload assets.
Forecast API - The Forecast API includes endpoints for managing your campaign and inventory forecasts, as well as the projected delivery of all active goals. A forecast is a prediction of future conditions based on past and present data. In this context, Pulse forecasts future ad inventory based on historical user traffic, and current campaign and account settings.
Analytics APIs Ooyala Pulse Analytics consists of two reporting tools, Insight and Custom Reporting.
  • The Custom Reporting API offers a powerful tool to pull complex reports from Ooyala Pulse, within limits. You can generate reports as you need them, without having pre-existing report definitions, unlike the Insight Reporting API.
  • The Insight Reporting API offers a tool for fast, reliable access to standard, every day reporting needs. Pulse pre-aggregates typical combinations of filters, dimensions, and metrics and makes them available to report against directly within the Insight UI or through the Insight API. In the Insight UI, you can also configure custom templates with some additional combinations of filters, dimensions, and metrics.

Related user documentation: Analytics

Errors

The Ooyala Pulse REST API communicates errors through standard HTTP status codes to indicate the success or failure of an API request. Generally, the following pattern applies:
  • 2xx: Pulse received, understood, and accepted a request.
  • 3xx: The user agent must take further action in order to complete the request.
  • 4xx: An error occurred in handling the request. The most common cause of this error is an invalid parameter.
  • 5xx: Pulse received and accepted the request, but an error occurred in the Pulse service while handling it.

Example Errors

HTTP status:
  403 (Forbidden)

Body:
{
  "type": "ForbiddenError",
  "message": "You have used 5 (100%) of your 5 templates. Please remove obsolete templates in order to create new ones."
}

Things Every Developer Should Know

  1. One request at a time: Only one request at a time towards Ooyala Pulse REST endpoints is allowed for a client.
  2. Updates overwrite data: Update requests replace data with the one sent in this request. If a field is not included, it is cleared in the Ooyala Pulse backend. Best practice is to first retrieve data for an entity, change values in that entity and then send it back in an update.

HTTP Verbs

Verb Description
GET Used for retrieving resources or collections.
POST Used for creating resources.
PUT Used for updating (replacing) complete resources or collections.
PATCH Used for partially updating (modifying) resources using instructions given in the request body.
DELETE Used for deleting resources.

Was this article helpful?