Use the /sapi/adunit endpoint to manage ad units. An ad unit defines a placement for video advertising and controls how ads are served and displayed. The positionType field determines the ad format: instream formats (preroll, midroll, postroll, VMAP) are served through the Blue Billywig video player, while the outstream format (inarticle) is embedded independently in page content.
Ad units are embedded on a web page via a JavaScript snippet:
<script type="text/javascript" src="https://{publication}.bbvms.com/a/{code}.js"></script>Each ad unit can have one or more line items attached to it. A line item holds the VAST URL or auction reference for the actual ad creative, along with campaign settings such as timeout and commercial behaviour.
1.0 | AdUnit Object
1.1 | Example AdUnit Object
{
"type": "AdUnit",
"id": "123",
"code": "homepage_preroll",
"title": "Homepage Preroll",
"description": "Preroll ad unit for the homepage player",
"publicationid": "754",
"status": "published",
"createddate": "2024-01-15T10:30:00Z",
"updateddate": "2024-06-01T09:15:22Z",
"positionType": "preroll",
"playoutCode": "default",
"assignedLineitems": ["456"],
"lineitems": [
{
"id": "456",
"code": "campaign_a_lineitem",
"title": "Campaign A",
"status": "published",
"vast_url": "https://example.com/vast.xml",
"timeout": 10
}
]
}1.2 | AdUnit Attributes
| Parameter | Description |
|---|---|
id | (string) Unique identifier of the ad unit. Read-only. |
type | (string) Type of object: "AdUnit". Read-only. |
code | (string) Unique textual code used in the embed script. Auto-generated from title on creation; must be unique within the publication. Cannot be changed after creation. |
title | (string) Display name of the ad unit. |
description | (string) Optional description. |
publicationid | (string) Unique identifier of the publication. Read-only. |
status | (string) "draft" or "published". Only published ad units are active. |
createddate | (string) ISO 8601 date/time the ad unit was created. Read-only. |
updateddate | (string) ISO 8601 date/time the ad unit was last updated. Read-only. |
positionType | (string) Ad format. See Position Types. |
playoutCode | (string) Code of the playout this ad unit is assigned to. For instream types, a playout can have at most one ad unit per position type. |
assignedLineitems | (array of strings) IDs of the line items attached to this ad unit. |
lineitems | (array) Line item objects attached to this ad unit. See Line Item Attributes. |
playout | (object) Embedded player configuration controlling ad display behaviour (skip offset, CTA settings, outstream sizing, passback settings, and more). |
1.3 | Position Types
| Value | Description |
|---|---|
"preroll" | Instream ad played before the video content. |
"midroll" | Instream ad played during the video content. |
"postroll" | Instream ad played after the video content. |
"vmap" | Instream ad scheduling via a single VMAP URL. The VMAP response defines preroll, midroll, and postroll placement internally. |
"inarticle" | Outstream ad embedded in article content, independent of a video player. |
"overlay" | Ad displayed as an overlay on top of the video player. |
"shorts" | Ad unit for the Shorts video format. |
1.4 | Line Item Attributes
| Parameter | Description |
|---|---|
id | (string) Unique identifier of the line item. Read-only. |
code | (string) Unique textual code for the line item. |
title | (string) Display name of the line item. |
status | (string) "draft" or "published". |
vast_url | (string) VAST tag URL for this line item. Mutually exclusive with auctionId. |
auctionId | (string) ID of a Blue Billywig Auction (/sapi/auction). Mutually exclusive with vast_url. |
timeout | (integer) Maximum time in seconds to wait for an ad response before moving on. Defaults to 10. |
2.0 | Retrieve List
Retrieves a list of ad units.
3.0 | Retrieve
Retrieves a single ad unit object.
4.0 | Create/Update
Creates a new ad unit. Omit id in the request body to create; include id to update an existing ad unit.
Example request payload:
{
"title": "Homepage Preroll",
"description": "Preroll ad unit for the homepage player",
"status": "published",
"positionType": "preroll",
"playoutCode": "default",
"lineitems": [
{
"code": "campaign_a_lineitem",
"title": "Campaign A",
"status": "published",
"vast_url": "https://example.com/vast.xml",
"timeout": 10
}
]
}5.0 | Delete
Deletes an ad unit and removes it from its assigned playout.