Ad Requests

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"
  ]
}
Note: Ads have two kinds of weights: explicit weights and proportional split (no weight set). All ads with proportional split share the remaining weight (100% - explicit weights). This means that explicitly setting the weight of an ad affects the weight of other ads that have proportional split. For example: You have 2 ads with no weight set. You add a third ad with weight 50%. The two previously added ads will now have 25% each (they split the remaining 50%).

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, indicates the allowed behaviour of VPAID ads. Set to true to allow only linear ads, or  set to false to allow non-linear ads as well)
      "vpaidCountdown": false (Optional, indicates if you want the standard Ooyala countdown text visible on the third party VPAID ad)
    }
  • 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

Create an Ad

Method POST
URL https://api.videoplaza.com/v1/ads
Header Authentication header (x-o-api-key)
Content type application/json
URL params -
Query params -
Body Request Body Format
Success response

HTTP status: 201 Created

Header: Location: URI to the location of the ad

Body: ad object including the ad ID

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, 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.
Method PUT
URL https://api.videoplaza.com/v1/ads
Header Authentication header (x-o-api-key)
Content type application/json
URL params -
Query params -
Body Request Body Format
Note: The ad ID is not provided as a parameter in the URL, but it is a part of the body of the request.
Success response

HTTP status: 200 OK

Header: -

Body: ad object including the ad ID

Example: Update the pre-roll ad

Request header:

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

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

You can use the PATCH method to modify one or multiple fields at once.

Limitation

You cannot use the PATCH method to modify the goalId, 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
Method PATCH
URL https://api.videoplaza.com/v1/ads
Header Authentication header (x-o-api-key)
Content type application/json
URL params -
Query params -
Body
Note: The ad ID is not provided as a parameter in the URL, but it is a part of the body of the request.
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.
Success response

HTTP status: 200 OK

Header: -

Body: -

Example: Modify the pre-roll ad

Request header:

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

Request body:

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

Success response:

HTTP status:
  200 (OK)

List All Ads

This returns a list of all ads ever created for your account. You can filter ads based on creation date.

Method GET
URL https://api.videoplaza.com/v1/ads
Header Authentication header (x-o-api-key)
Content type application/json
URL params -
Query params
  • created.after: provide an ISO-8601 formatted date-time string to only list ads created after a certain date
  • created.before: provide an ISO-8601 formatted date-time string to only list ads created before a certain date
Body -
Success response

HTTP status: 200 OK

Header: -

Body: list of ads

Example:

Request header:

GET /v1/ads?created.after=2017-08-01T00:00:00Z 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": "7b6ad319-ff66-4425-b522-000f1d71e7ed",
        "name": "argos_postroll",
        "goalId": "07147834-14de-4cf1-bb2a-6c6a13f15b9e",
        "description": "",
        "enabled": true,
        "created": "2017-08-08T11:17:59Z",
        "creative": {
            "type": "standard",
            "insertionPoint": "postroll",
            "assetId": "03f2bbd4-a906-4f1b-bce0-6ad75d86e053",
            "creationDate": "2017-08-08T11:17:59Z",
            "modificationDate": "2017-08-08T11:17:59Z"
        },
        "externalTrackers": []
    },
    {
        "id": "7d6da03f-5c04-4e19-92e3-58424958ccf8",
        "name": "ooyala_ad_preroll",
        "goalId": "8caf3aa3-e41a-4b7d-b956-58ac1b09b0b2",
        "description": "",
        "enabled": true,
        "created": "2017-08-08T11:07:45Z",
        "creative": {
            "type": "standard",
            "insertionPoint": "preroll",
            "assetId": "1a55837f-ed05-4abe-bbfd-3ac098e9bf7d",
            "creationDate": "2017-08-08T11:07:45Z",
            "modificationDate": "2017-08-08T11:07:45Z"
        },
        "externalTrackers": []
    },
    {
        "id": "50d554a5-9569-4599-a9c9-860e03b35729",
        "name": "argos_midroll",
        "goalId": "9a62331d-6654-4139-9406-2c6729285b3e",
        "description": "",
        "enabled": true,
        "created": "2017-08-08T11:16:42Z",
        "creative": {
            "type": "standard",
            "insertionPoint": "midroll",
            "assetId": "43982540-cfb3-4f9a-a59f-aacfa4c2aff3",
            "creationDate": "2017-08-08T11:16:42Z",
            "modificationDate": "2017-08-08T11:16:42Z"
        },
        "externalTrackers": []
    },
    {
        "id": "3637f512-882c-4abd-a998-5b658ed22529",
        "name": "sony_ad_midroll",
        "goalId": "d3a34b6f-1de9-40e9-84bc-03dc7914c437",
        "description": "",
        "enabled": true,
        "created": "2017-08-08T11:10:14Z",
        "creative": {
            "type": "standard",
            "insertionPoint": "midroll",
            "assetId": "a4f5a293-de74-4fa1-8008-9e6f01069800",
            "creationDate": "2017-08-08T11:10:14Z",
            "modificationDate": "2017-08-08T11:10:14Z"
        },
        "externalTrackers": []
    },
    {
        "id": "11ee8d36-fedf-4564-83c2-ef015a538a13",
        "name": "argos_preroll",
        "goalId": "dfeaaea7-5cd0-4531-904b-c96afe7a3239",
        "description": "",
        "enabled": true,
        "created": "2017-08-08T11:15:26Z",
        "creative": {
            "type": "standard",
            "insertionPoint": "preroll",
            "assetId": "87b7bed7-eb6b-44c5-a66e-42d478a1f357",
            "creationDate": "2017-08-08T11:15:26Z",
            "modificationDate": "2017-08-08T11:15:26Z"
        },
        "externalTrackers": []
    }
]

List Ads by Ad Id

Method GET
URL https://api.videoplaza.com/v1/ads/{id}
Header Authentication header (x-o-api-key)
Content type application/json
URL params ID of the ad
Query params -
Body -
Success response

HTTP status: 200 OK

Header: -

Body: list of ads

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?