Pulse REST API

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

Overview

The Pulse REST API is organised around the main resources available in the 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 and so on), for Pulse available in the Pulse User Guide.

You need to have a Pulse account that you can test the API against and an API key so that you can make API calls. For more information, see Authentication.

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 and communication formats. 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 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 successfully 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.

The Campaign Management APIs also include a series of query endpoints, which are meant to quickly retrieve detailed information and performance metrics for your campaigns, goals and ads. These endpoints allow you to build your own interfaces to view the information in your account.

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.

Custom Reporting API -

The Custom Reporting API offers a powerful tool to pull complex reports from Pulse, within limits. You can generate reports as you need them, without having pre-existing report definitions.

Related user documentation: Custom Reporting

Audience Management API -

The Audience Management API allows you to retrieve audience data provider information, and manage your audience segmentations and audience segments.

Related user documentation: Pulse Audience Management

Swagger Specification for Pulse REST API

Swagger specification for Pulse APIs is available at https://api.videoplaza.com/v1/swagger.

In the top right corner you can select the API specification you are interested in. A Swagger specification is available for the following Pulse APIs:Links to the corresponding API specification are included in our API documentation where applicable.

All the different API models (the structures used in the API requests and responses) for a specific API are listed below the API requests. The API models specific to one request are also available and visible within each request.

Errors

The 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 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 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.