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 either a publisher, whose 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.

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

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

Code not currently supported by our Creative Submission API.

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.
4 Denied: The audit is complete, but the ad has been found unacceptable in some material aspect and is disapproved for use.
5

Code not currently supported by our Creative Submission API.

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.

 

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