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

Make a call to the API to get a list of all available publishers and their corresponding publisher IDs

Staging Production
GET https://staging-creatives.vistarmedia.com/ssp/rtb/v1/admgmt/{bidderId}/publishers

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. Note these publisher IDs match the seller_id provided in Vistar's Sellers.json.

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. 

Staging Production
POST https://staging-creatives.vistarmedia.com/ssp/rtb/v1/admgmt/{bidderId}/ads?publisherId={publisherId}

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.

Staging Production
GET https://staging-creatives.vistarmedia.com/ssp/rtb/v1/admgmt/{bidderId}/ads/{adId}?publisherId={publisherId}

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.

Staging Production
GET https://staging-creatives.vistarmedia.com/ssp/rtb/v1/admgmt/{bidderId}/ads?auditStart={startTime}&publisherId={publisherId}

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.

Value Definition
4 Denied: The audit is complete, but the ad has been found unacceptable in some material aspect and is disapproved for use.
5 Changed; Resubmission Requested: A version of the ad has been detected in use that is materially different from the version that was previously audited, which may result in rejection during use until the ad is resubmitted for audit and approved. Vendors need to communicate offline as to the criteria that constitutes a material change.
6 Expired: The ad has been marked as expired by the vendor. Vendors need to communicate offline as to the expected bidding behavior for ads with this status.
500+ Vendor-specific codes
1 Pending Audit: An audit has not yet been completed on this ad. A recommendation cannot be made to use this ad, but vendors' policies may override.
2 Pre-Approved: An audit has not yet been completed on this ad. Subject to vendors' policies, it can be recommended for use. However, once the audit has been completed, its status will change and it may or may not be approved for continued use.
3 Approved: The audit is complete and the ad is approved for use. Note, however, that some attributes (e.g., adomain, cat, attr, etc.) may have been changed in the process by the auditor.
Was this article helpful?
1 out of 2 found this helpful