Creative Submission API

Vistar Media’s creative submission API provides a way for DSPs to submit creatives to our platform, instead of relying on creative ingestion at bid response time. When a creative is submitted through this API, it will be transcoded and sent to the specified publisher for approval. The status of approvals can be retrieved periodically.

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

Our API is based off of 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.  

While Vistar recommends using our sellers.json to fetch publisher IDs, alternatively you can make a call to the API to get the same list of all available publishers and their corresponding publisher IDs.

Example Response:

[
   {
     "id": "1076472806277c2c055332640466243e3617241e7526",
     "displayName": "Sample Publisher 1"
   },
   {   
     “id”: "18056b3633004c5c006800366a05290f0c1e2e265210",
     "displayName": "Sample Publisher 2"
   }
]

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 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. 

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

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

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
     }
  }

To get the status of multiple ads

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.

[
   {
     "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
     }
  }
]

Audit Status Code

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