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 either a publisher, who’s identifier must be specified in every request to the API, or a deal that is associated with the publisher(s). Note that if both a publisher and deal are specified in the request, the API will only look at the submitted publisher.

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

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. 

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

To submit an ad for approval to a given deal

Make a call to the API to submit a creative for approval to a given deal using its deal ID.

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

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 or deal, another POST request should be made with a different publisher ID or deal 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.

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

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 a specific ad for a given deal

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

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

The auditStart and auditEnd parameters support filtering ads based on the lastmod time of the audit. Timestamps are in unix milliseconds.

Because a single deal could possibly be associated with more than one publisher, there could be more than one status returned in the response. You can find the publisher associated with each returned status by looking at the status’s audit.ext.publisher field.

Example response when a deal is associated with two publishers, publisher “X” and publisher “Y”:

[
  {
    "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"
      }
    }
  },
  {
    "id": "123",
    “init”: 1590162907810,
    "adomain": ["cats.com"],
    "display": {
      “banner”: {
        "img": "https://cats.com/cat.jpg"
      }
    },
    "audit":{
      “init”: 1590162907815,
      “status":4,
      "feedback":["Category disallowed"],
      "lastmod":1590262017000,
      "ext":{
        "publisher": "Y"
      }
    }
  }
]

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.

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. 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" } } } ]

To get the status of multiple ads for a given deal

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

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

The auditStart and auditEnd parameters support filtering ads based on the lastmod time of the audit. Timestamps are in unix milliseconds.

Because a single deal could possibly be associated with more than one publisher, there could be more than one status returned in the response. You can find the publisher associated with each returned status by looking at the status’s audit.ext.publisher field.

Example multiple-ad response when a deal is associated with two publishers, publisher “X” and publisher “Y”:

[
  {
    "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"
      }
    }
  },
  {
    "id": "123",
    “init”: 1590162907810,
    "adomain": ["cats.com"],
    "display": {
      “banner”: {
        "img": "https://cats.com/cat.jpg"
      }
    },
    "audit":{
      “init”: 1590162907815,
      “status":4,
      "feedback":["Category disallowed"],
      "lastmod":1590262017000,
      "ext":{
        "publisher": "Y"
      }
    }
  },
  {
    "id": "456",
    “init”: 1715995260000,
    "adomain": ["cats.com"],
    "display": {
      “banner”: {
        "img": "https://cats.com/cat.jpg"
      }
    },
    "audit":{
      “init”: 1715995260020,
      “status":4,
      "feedback":["Category disallowed"],
      "lastmod":1716009660000,
      "ext":{
        "publisher": "X"
      }
    }
  },
  {
    "id": "456",
    “init”: 1715995260000,
    "adomain": ["cats.com"],
    "display": {
      “banner”: {
        "img": "https://cats.com/cat.jpg"
      }
    },
    "audit":{
      “init”: 1715995260020,
      “status":4,
      "feedback":["Category disallowed"],
      "lastmod":1716006600000,
      "ext":{
        "publisher": "Y"
      }
    }
  }
]

 

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?
2 out of 5 found this helpful