Examples: Ad Requests

This page gives a few examples of using the Ad API endpoints for ads.

Note: Only successful responses are shown in the examples. Details about unsuccessful responses are found in the swagger documentation: https://api.videoplaza.com/v1/swagger.

Request Body Format

To create or update ads, you need to supply a body to the request with the following format:
Note: All parameters are optional unless explicitly stated.
{
  "id": "<string>", (id of the ad, required only for the update request)
  "name": "<string>", (Required)
  "goalId": "<string>", (Required, valid goal UUID)
  "customId": "<string>",
  "description": "<string>",
  "enabled": "<boolean>", (Defaults to false)
  "weight": "<number from 0.01 to 100>", (Defaults to proportional split between ads in a goal)
  "creative": { (Required, fields under the creative field depend on the type of creative)
    "type": "standard", (Required)
    "insertionPoint": "<preroll|midroll|postroll>", (Required)
    "assetId": "<fileId from /v1/assets>", (Required)
    "clickDestinationUri": "http://click-destination-uri.com"
  },
  "start": "<ISO-8601 formatted date-time string>", (Inherits from goal if not supplied)
  "end": "<ISO-8601 formatted date-time string>", (Inherits from goal if not supplied)
  "externalTrackers": [ (You can provide multiple external trackers for an ad)
    {
      "url": "<string>", 
      "event" : "<string>"
    },
    {
      "url": "<string>", 
      "event" : "<string>"
    }
  ],
  "deviceContainers": [ (Valid device container UUID, defaults to all available device containers. You can target multiple device containers.)
    "string",
    "string"
  ]
}

Creative types

We currently support the following creative types:
  • Standard spot ads (pre-, mid-, and post-rolls): pass in the type of insertion point and the asset id:
    "creative": {
      "type": "standard",
      "insertionPoint": "<preroll|midroll|postroll>",
      "assetId": "<assetId>",
      "clickDestionationUri": "http://click-destination-uri.com" (Optional, to set the clickthrough URI)
    }
  • Pause ads: pass in the type of ad and the asset id:
    "creative": {
      "type": "pause",
      "assetId": "<assetId>",
      "clickDestionationUri": "http://click-destination-uri.com" (Optional, to set the clickthrough URI)
    }
  • Third party ads: the asset is not stored in Ooyala Pulse, so you need to provide a URI for the location of the VAST ticket:
    "creative": {
      "type": "thirdparty",
      "vastUri": "http://vast-uri-example.com",
      "vpaidStrict": true, (Optional)
      "vpaidCountdown": false (Optional)
    }
  • Generic placeholder ads, where you do not specify the type of ad yet:
    "creative": {
      "type": "placeholder"
    }
  • Standard spot placeholder ads (pre-, mid-, and post-rolls): pass in the type of insertion point, but you pass in the asset later:
    "creative": {
      "type": "spotPlaceholder",
      "insertionPoint": "<preroll|midroll|postroll>"
    }
  • Pause placeholder ads, where you specify the type of placeholder ad, but you pass in the asset later:
    "creative": {
      "type": "pausePlaceholder"
    }

External tracking

Ads can have multiple external trackers. The following tracking events are available:

IMPRESSION, CLICK_THROUGH, AD_START, AD_FIRST_QUARTILE, AD_MIDPOINT, AD_THIRD_QUARTILE, AD_COMPLETE, CLOSE, MUTE, UNMUTE, PAUSE, RESUME, REWIND, FULLSCREEN, EXPAND

Creating Ads

Example: create a pre-roll ad

Request header:

POST /v1/ads HTTP/1.1
Host: api.videoplaza.com
Content-type: application/json
x-o-api-key="<your key>"

Request body:

{
  "name": "Test preroll ad with asset",
  "goalId": "9d876692-44c1-4b7a-ae46-b8c4dbb2dae6",	
  "creative": {
    "type": "standard",
    "insertionPoint": "preroll",
    "assetId": "df3d2ad9-2c83-4ee1-b2ca-388c3d302f40",
    "clickDestinationUri": "http://example.com"
  },
  "start": "2017-03-02T23:00:00Z",
  "end": "2017-04-02T23:00:00Z",
  "weight": 50,
  "externalTrackers": [
    {
      "url": "http://externaltracker.com",
      "event": "IMPRESSION"
    }
  ],
  "deviceContainers": [
    "86d28d24-d025-4633-a081-bea93de04dc3",
    "145299c6-ba02-45de-9995-c2dfaba44c8c"
  ]
}

Success response:

HTTP status:
  201 (Created)

Header:
  Location: <URI to the location of the ad>

Body:
{
  "id": "6afcb416-7f6c-425b-852c-1a8ce7fb8987",
  "name": "Test preroll ad with asset",
  "goalId": "9d876692-44c1-4b7a-ae46-b8c4dbb2dae6",
  "enabled": false,
  "creative": {
    "type": "standard",
    "insertionPoint": "preroll",
    "assetId": "df3d2ad9-2c83-4ee1-b2ca-388c3d302f40",
    "clickDestinationUri": "http://example.com"
  },
  "start": "2017-03-02T23:00:00Z",
  "end": "2017-04-02T23:00:00Z",
  "weight": 50,
  "externalTrackers": [
    {
      "url": "http://externaltracker.com",
      "event": "IMPRESSION"
    }
  ],
  "deviceContainers": [
    "86d28d24-d025-4633-a081-bea93de04dc3",
    "145299c6-ba02-45de-9995-c2dfaba44c8c"
  ]
}

Example: create a pause placeholder ad

Request header:

POST /v1/ads HTTP/1.1
Host: api.videoplaza.com
Content-type: application/json
x-o-api-key="<your key>"

Request body:

{
  "name": "Pause placeholder ad",
  "goalId": "fbda8a5d-5f32-4bc5-8b21-aff9f08c66ff",	
  "creative": {
  "type": "pausePlaceholder"
  }
}

Success response:

HTTP status:
  201 (Created)

Header:
  Location: <URI to the location of the ad>

Body:
{
  "id": "1dec40ea-3933-496b-862f-156e30ca7717",
  "name": "Pause placeholder ad",
  "goalId": "fbda8a5d-5f32-4bc5-8b21-aff9f08c66ff",
  "enabled": false,
  "creative": {
    "type": "pausePlaceholder"
  },
  "externalTrackers": [],
  "deviceContainers": [
    "24c2dd16-eda0-48f3-8e74-f8e0c608d3cd",
    "27375d12-e3ad-46ce-ad78-eece92928c90",
    "5aa5bfe0-985c-4144-9ab1-9f723ba81abf",
    "145299c6-ba02-45de-9995-c2dfaba44c8c",
    "a6b5b571-c517-4597-861b-24d2d190d642",
    "6b79564c-8a8c-102f-9f01-001e4f3cd645",
    "86d28d24-d025-4633-a081-bea93de04dc3"
  ]
}

Update Ads

Note: When updating ads, you must provide all fields set during creation, which you do not want to alter, again in the request body, otherwise these fields are unset and may inherit the settings from the goal the ad belongs to. For example, this applies to the start and end date of the ad.

Example: update a pre-roll ad

In this example, the PUT method is used to update the pre-roll ad from the first example. The ad's name is changed, the ad is enabled, and more device containers are added.

Request header:

PUT /v1/ads HTTP/1.1
Host: api.videoplaza.com
Content-type: application/json
x-o-api-key="<your key>"
Note: The ad id is not provided as a parameter in the URL, but it is a part of the body of the request.

Request body:

{
  "id": "b1672a4f-cc59-45d3-9c3c-b0bfaf1f5bfb",
  "name": "Delicious perfume ad",
  "goalId": "9d876692-44c1-4b7a-ae46-b8c4dbb2dae6",
  "enabled": true,
  "creative": {
    "type": "standard",
    "insertionPoint": "preroll",
    "assetId": "df3d2ad9-2c83-4ee1-b2ca-388c3d302f40",
    "clickDestinationUri": "http://example.com"
  },
  "start": "2017-03-02T23:00:00Z",
  "end": "2017-04-02T23:00:00Z",
  "weight": 50,
  "externalTrackers": [
    {
      "url": "http://externaltracker.com",
      "event": "IMPRESSION"
    }
  ],
  "deviceContainers": [
    "86d28d24-d025-4633-a081-bea93de04dc3",
    "a6b5b571-c517-4597-861b-24d2d190d642",
    "6b79564c-8a8c-102f-9f01-001e4f3cd645",
    "5aa5bfe0-985c-4144-9ab1-9f723ba81abf",
    "27375d12-e3ad-46ce-ad78-eece92928c90",
    "24c2dd16-eda0-48f3-8e74-f8e0c608d3cd",
    "145299c6-ba02-45de-9995-c2dfaba44c8c"
  ]
}

Success response:

HTTP status:
  200 (OK)

Body:
{
  "id": "6afcb416-7f6c-425b-852c-1a8ce7fb8987",
  "name": "Delicious perfume ad",
  "goalId": "9d876692-44c1-4b7a-ae46-b8c4dbb2dae6",
  "enabled": true,
  "creative": {
    "type": "standard",
    "insertionPoint": "preroll",
    "assetId": "df3d2ad9-2c83-4ee1-b2ca-388c3d302f40",
    "clickDestinationUri": "http://example.com"
  },
  "start": "2017-03-02T23:00:00Z",
  "end": "2017-04-02T23:00:00Z",
  "weight": 50,
  "externalTrackers": [
    {
      "url": "http://externaltracker.com",
      "event": "IMPRESSION"
    }
  ],
  "deviceContainers": [
    "145299c6-ba02-45de-9995-c2dfaba44c8c",
    "86d28d24-d025-4633-a081-bea93de04dc3",
    "24c2dd16-eda0-48f3-8e74-f8e0c608d3cd",
    "a6b5b571-c517-4597-861b-24d2d190d642",
    "27375d12-e3ad-46ce-ad78-eece92928c90",
    "6b79564c-8a8c-102f-9f01-001e4f3cd645",
    "5aa5bfe0-985c-4144-9ab1-9f723ba81abf"
  ]
}

Modify Ads

Note: id is the only required field. If you do not provide any other fields in the request body, nothing changes and the original values are retained. You can use the PATCH method to modify one or multiple fields at once.

Limitation

You cannot use the PATCH method to modify the creative, externalTrackers, and deviceContainers fields. Doing so is ignored and the original values are retained. You can only modify the following fields:
  • name
  • customId
  • description
  • enabled
  • start
  • end
  • weight

Example: modify a pre-roll ad

In this example, the PATCH method is used to disable the pre-roll ad from the previous example.

Request header:

PATCH /v1/ads HTTP/1.1
Host: api.videoplaza.com
Content-type: application/json
x-o-api-key="<your key>"
Note: The ad id is not provided as a parameter in the URL, but it is a part of the body of the request.

Request body:

{
  "id": "b1672a4f-cc59-45d3-9c3c-b0bfaf1f5bfb",
  "enabled": false
}

Success response:

HTTP status:
  200 (OK)

List Ads by Ad Id

Example:

Request header:

GET /v1/ads/3db7f7d7-5a7d-4714-931f-b976d9f4986e HTTP/1.1
Host: api.videoplaza.com
Content-type: application/json
x-o-api-key="<your key>"

Request body: NA

Success response:

HTTP status:
  200 (OK)

Body:{
  "id": "3db7f7d7-5a7d-4714-931f-b976d9f4986e",
  "name": "Royco_sauce_2017",
  "goalId": "9d876692-44c1-4b7a-ae46-b8c4dbb2dae6",
  "customId": "royco_sauce_jan_feb_2017",
  "description": "Royco sauce standard preroll.",
  "enabled": true,
  "creative": {
    "type": "standard",
    "insertionPoint": "preroll",
    "assetId": "2172ef35-c13c-49f1-b8fe-ebe6dd4812de",
    "clickDestinationUri": "http://example.com"
  },
  "start": "2017-01-25T23:00:00Z",
  "end": "2017-02-16T23:00:00Z",
  "weight": 50,
  "externalTrackers": [
    {
      "url": "http://externaltracker.com",
      "event": "IMPRESSION"
    },
    {
      "url": "http://externaltracker.com",
      "event": "AD_COMPLETE"
    }
  ],
  "deviceContainers": [
    "6b79564c-8a8c-102f-9f01-001e4f3cd645",
    "24c2dd16-eda0-48f3-8e74-f8e0c608d3cd",
    "a6b5b571-c517-4597-861b-24d2d190d642",
    "145299c6-ba02-45de-9995-c2dfaba44c8c",
    "86d28d24-d025-4633-a081-bea93de04dc3",
    "5aa5bfe0-985c-4144-9ab1-9f723ba81abf",
    "27375d12-e3ad-46ce-ad78-eece92928c90"
  ]
}

Was this article helpful?