Creative Submission API

Creatives can enter our Supply Side Platform (SSP) via bids from third-party (non-Vistar) Demand Side Platforms (DSPs). 

Vistar’s SSP saves and transcodes creative files for each creative ID (CRID) using its default creative ingestion process. This takes place on first bid. The creative then enters each publisher’s queue for manual approval. Approval times vary by publisher but can be up to several business days. Bids with that CRID against that publisher’s inventory will fail until manually approved.

The use of the Creative API by third-party DSPs has two key advantages. First, you can submit creatives for approval before campaign flight dates. This means that spending can start immediately on first bid. Second, DSPs receive more detailed feedback about the approval status of their creatives, and they can get feedback without the need to place a bid.

Integration with the Creative API is voluntary. Even if integrated, you’re not required to submit every new creative through the API. The default creative ingestion process will continue to function.

All creative submission is scoped to a publisher, whose identifier must be specified in every request to the API. 

The publisher must have at least one network currently eligible to send requests to your bidder. This applies to both staging and production. If there is a block between you and the publisher's networks, your call will result in a 403 error. This includes cases where all traffic to your bidder is paused. Please email the team at rtb-integrations@vistarmedia.com if you have questions about enabled networks.

Our API is based on the IAB’s Ad Management API v1.0, and all messages are encoded with JSON.

Authentication

DSPs will be provided offline with an API key and unique bidder ID. Please email support@vistarmedia.com if you would like an API key and bidder ID. The API key must be specified on all requests in the x-vistar-bidder-api-key header. The bidder ID must be specified in the endpoint URLs, seen below.

To get a list of publishers and their IDs

A complete list of Vistar's publishers and their publisher IDs are available on Vistar's sellers.json

• Staging sellers.json
• Production sellers.json

You will need the publisher IDs from the response in order to submit creatives to specific publishers, as outlined in the steps below.

To submit an ad for approval

To submit an ad for approval to a given publisher

Make a call to the API to submit a creative for approval to a given publisher using the publisher ID from the previous call. 

Other submission criteria

When submitting a creative through the API, the Id field of the ad must correspond to the crid field that will be sent in bid responses.

Creative submissions must pass a content category using IAB Content Category Taxonomy 1.0, signified by setting cattax = 1. No other content taxonomies are currently supported. 

Example POST body for an image creative:

{
   "id": "123",
   "adomain": ["cats.com"],
   "cat": ["IAB16-3"],
   "cattax": 1,
   "display": {
     “banner”: {
       "img": "https://cats.com/cat.jpg"
     }
   }
}

For a video creative, the video object will instead contain VAST located in the adm field.

To reformat the above example to a video post, update "banner" to "video" and update "img" to "adm" and insert the VAST tag. 

A successful POST returns a status of 202 Accepted or 204 No Content Success. It may take up to 10 minutes for this Ad to begin appearing in subsequent GET requests.

To submit an existing ad to a new publisher, another POST request should be made with a different publisher ID and the same Ad Id. In subsequent requests, all fields in the Ad object other than Id are still required, but will be ignored.

To get the status of a specific ad

To get the status of a specific ad for a given publisher

Make a call to the API to retrieve the status of a specific ad and its approval status for the specified publisher.

The publisher for which the status is for will be returned in the audit.ext.publisher field.

Example response:

{
   "id": "123",
   "init": 1590162907810,
   "adomain": ["cats.com"],
   "display": {
     “banner”: {
       "img": "https://cats.com/cat.jpg"
       }
     },
   "audit":{
     “init”: 1590162907815,
     “status":4,
     "feedback":["Category disallowed"],
     "lastmod":1590162907815,
     "ext":{
       "publisher": "X"
     }
   }
}

To get the status of multiple ads

To get the status of multiple ads for a given publisher

Make a call to the API to retrieve the statuses of multiple ads for the specified publisher.

The auditStart and auditEnd parameters support filtering ads based on the lastmod time of the audit. Timestamps are in unix milliseconds. The publisher for which the status is for will be returned in the audit.ext.publisher field.

[
   {
     "id": "123",
     “init”: 1590162907810,
     "adomain": ["cats.com"],
     "display": {
       “banner”: {
          "img": "https://cats.com/cat.jpg"
       }
     },
     "audit":{
       “init”: 1590162907815,
       “status":4,
       "feedback":["Category disallowed"],
       "lastmod":1590162907815,
       "ext":{
         "publisher": "X"
       }
     }
  }
]

Audit Status Code

The following table lists the codes used in Audit objects to reflect status or workflow state.