Unified Ad Serving API

Vistar’s Unified Ad Serving offering allows media owners to schedule and deliver programmatic, flexible, and loop-based content all within one platform. To enable your content management system to use Unified Ad Serving, Vistar provides media owners with a RESTful interface over HTTP, referred to as Vistar’s Unified Ad Serving API. Using this API, you can request loops, receive loop responses, report back proof of plays (PoPs), receive direction to get programmatic content.


Definitions of common terms used throughout the API can be found below:

  • Asset – An asset is a file containing content that should be displayed on a screen
  • Slot – A slot is a space within a loop for an asset with a known duration
  • Loop – A loop is an ordered sequence of slots that should repeat until the loop’s stated end time
  • Loop Duration – A loop has a fixed duration specified at the network level. This duration should reflect the desired frequency for “one ad playing every loop”
  • Scheduled Content – Scheduled content, also referred to as loop-based content, refers to assets that should be delivered based on some frequency of loops (e.g. one play every loop)
  • Programmatic Content – Programmatic content refers to assets that should be delivered according to business rules, such as an impression or dollar goal. Programmatic content can either be direct-sold flexible orders or from PMPs or Open Exchange transactions

Get a Loop

Gets a loop of content to be played on a specific venue at a specific time. The current time is used if no display_time is specified in the request.

A Loop response includes an ordered sequence of slots. The sequence is the shortest collection of loop iterations which satisfies line item and creative targeting requirements for the requesting venue. This sequence should be displayed repeatedly, in order, until a specified end_time.

Example: If a line item is set up to run 1x per 4 loops, the loop response includes at least 4 loop iterations. 

Note: Partners should make new loop requests at least every half hour, even if the end_time is several hours away. This will ensure that the device does not miss out on any new campaigns that may have gone live and are targeting the venue in between requests.

Note: The API can be used to view schedules up to 10 days in the future. Trying to a view a display time more than 10 days in the future will display programmatic slots.

The venue should repeatedly loop over the Slot sequence in the specified order. As each slot is encountered, the venue should compare its current time with the given end_time. If the current time is equal to or after the end_time, then it should abort the current loop and make a new GetLoop request. Otherwise the Slot should be handled as follows:

  • If the type is "advertisement" or "content", then the venue should look up the associated Asset by the specified asset_url. It should play the asset and hit the specified tracking_url upon completion.
  • If the type is "programmatic", then the venue should make a programmatic GetAd request. If a programmatic ad is returned, then the venue should play the ad and hit the associated proof_of_play_url. If no programmatic ad is returned, then the venue should advance to the next slot in the loop.

Request Body Parameters

Name Description Type Required
venue_id The media owner's identifier for the requesting venue. String Required

The ID of the network you are making a request for. This is one of two fields used to authenticate using the Ad Serving API.

See API Credentials to learn how to retrieve these credentials.

String Required

The unique key for the network. This is one of two fields used to authenticate with the Ad Serving API.

See API Credentials to learn how to retrieve these credentials.

String Required
display_time The time at which the loop will begin playing, as unix epoch in UTC. Defaults to the time of the request. String <int64> Recommended


Staging Production
POST https://sandbox-api.vistarmedia.com/v1beta2/loop

Sample JSON Request

  "venue_id": "string",
  "network_id": "string",
  "api_key": "string",
  "display_time": "string"


Description Type Required

The ordered list of slot content in the loop. Note the number of slots returned is capped at 500. 

Array Required
  • "advertisement" 
  • "content" 
  • "programmatic"
String Required
  length_in_seconds The duration the slot's content should display for, in seconds Integer Required

A URL that should be hit after the slot has completed. Only present for scheduled slots. Vistar recommends appending a display time override (defined below) in instances where the time the URL is hit does not match the time the spot played.

float  Required

The URL of the creative asset to render on the client. Only present if the slot's type is "scheduled". The Asset referred to by this URL shall have an entry in the loop's assets list as well.

String Optional

The ID referring to the creative category of the asset contained within the slot. 

String Optional

The position of the slot within the loop. The first slot in the loop is labeled with loop_position = 1. If there are multiple loops returned within a single response, each instance of the first slot in the loop is labeled with loop_position = 1. 

Integer Required
assets Array of objects (v1beta1Asset)
The potentially empty list of assets that are scheduled in the current or an upcoming loop. It is recommended that all returned assets be cached by the client venue so that assets are ready to play when needed.
Array Required

The asset's URL.

Note:It is recommended to use the asset URL for mapping to cached creatives

String Required

The asset's MIME type

String Required

The asset's name

String  Required

Only present if the asset has creative companions

Array Optional

Name of the creative companion

String Required

Value of the creative companion. Note if the companion contains a file, the value will provide the URL at which the file is hosted.

String Required

The time at which this loop is scheduled to end playing as unix epoch in UTC. The venue should compare this time with its current time before handling any loop slot and abort the loop and make a new GetLoop request if the current time is not before it. Note end_time will not be more than 24 hours from the display_time passed on the request. This means the maximum time between display_time and end_time is 24 hours. 

Integer Required

Sample JSON Response

  "slots": [
      "type": "__none__",
      "length_in_seconds": 0,
      "tracking_url": "string",
      "asset_url": "string",
"creative_category": "string", "loop_position": 1 } ], "assets": [ { "url": "string", "mime_type": "string",
"name": "string",
"companions": [
"name": "string",
"value": "string"
] } ], "end_time": 0 }

Tracking URLs

You must notify Vistar after a slot is played by hitting the corresponding tracking_url located in the loop response. When the tracking_url is hit, the time is recorded in Vistar’s system as the reported display time. If you hit the tracking_url at a different time than the slot was played, you can append the display_time parameter to the query string so that reporting reflects the time the ad played rather than the time the tracking_url was hit. 

Note: Vistar strongly recommends always storing and passing a display time override to handle cases where players are offline for some period of time. The display_time can be at most 30 days in the past. Any display_time beyond 30 days will result in a 400 error. 

Offline Behavior: The tracking_url does not expire to allow devices to continue to play loop content if a device goes offline. If you do not append the display time, reporting reflects that all ads played at the time the device resumes connectivity.  


Name Description Type Required

The actual time an ad was shown in UTC epoch seconds.

Example value:1338260504

Int32 Optional
Sample proof of play URL



What determines how much programmatic content is contained in the loop?
Vistar determines how much of the fixed loop length is filled by scheduled, or loop-based, content, and then dedicates the remaining time towards programmatic. For example, if your loop length is 300 seconds and a given loop has 200 seconds of “scheduled” content, then there will be 100 seconds of “programmatic” content in your loop. 
How should I handle a programmatic slot with a long duration?
The integration should send ad requests to try to fill the whole programmatic time slot. This should be done by initially setting max duration in the ad request to the duration returned by the API. If the ad response that comes back has a duration shorter than the programmatic period, deduct the duration of the returned ad from the total duration and request that new value as the max duration. Continue this process until the full duration is used or the ad server does not return an ad.
Why am I receiving more than one loop’s worth of content in a loop response?
Rather than returning a single loop, Vistar returns the shortest repeating set of content to a loop request. In some cases, this can lead to the total duration of content being longer than the network’s loop length. This could happen if some line items are scheduled to run every X loops or if some line items have multiple associated creatives. Returning the shortest repeating set of content allows you to repeat the returned content until `end_time` is reached.
What do I do if I am unable to get the next loop or programmatic content?
If connectivity issues or some other factors prevent you from requesting and receiving the next loop or programmatic content, Vistar recommends that you continue to play the current loop without any new programmatic content until you can get a new loop. You should continue to hit the tracking URLs for the content that the device plays regardless of whether or not the loop is no longer scheduled. If poor connectivity prevents you from hitting the tracking URLs, Vistar recommends that you store the URLs and hit all URLs for the content that was played once connectivity is restored.


Was this article helpful?
2 out of 2 found this helpful