Vistar Media

Updated April 24, 2026 21:31

Creative Submission API

Reading Time: ±8 minutes

Introduction

Third-party DSPs (demand side platforms) can submit creatives to Vistar’s Supply Side Platform (SSP) either through the default ingestion process or by using the Creative Submission API (application program interface).

The API offers 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.

These benefits reduce delays at launch and minimize troubleshooting.

Without the API, Vistar’s SSP saves and transcodes each creative by CRID (creative ID) on the first bid. The creative is then placed into each publisher’s manual approval queue. 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 Creative Submission API is based on the IAB’s (Interactive Advertising Bureau) Ad Management API v1.0, and all messages are encoded with JSON.

What You’ll Learn

In this topic, you'll learn how to:

Authenticate.
Submit an ad for approval by publisher or deal ID.
Get the approval status of a specific ad by publisher or deal ID.
Get the approval statuses of multiple ads by publisher or deal ID.

Authentication

DSPs are provided an API key and a unique bidder ID offline. To request these credentials, please email support@vistarmedia.com.

Include the API key in every request using the x-vistar-bidder-api-key header, and include the bidder ID in the endpoint URLs shown below.

Submit an Ad For Approval

Use one of the following options to submit an ad to a publisher for approval. Expand each section to learn more.

Submit an Ad For Approval by Publisher ID

Caution: All creative submissions must specify the publisher ID. The publisher must also have at least one network eligible to send requests to your bidder in staging or production. If no eligible pathway exists, the request returns a 403 error.

Tip: To get a complete list of Vistar’s publishers, and their publisher IDs, see Staging sellers.json and Production sellers.json.You'll need these publisher IDs to submit creatives to specific publishers, as outlined below.

Use this endpoint to submit a creative ad to a publisher for approval using the publisher ID. See Find Publisher Names and IDs above to learn more.

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

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

Request Parameters

Name	Description	Type	Required	Notes
bidderId	The unique identifier for your bidder. In the endpoint URL, replace the {bidderId} placeholder with your bidder ID. This field isn't part of the request body.	String	Yes	Path parameter.
publisherId	The unique identifier for your publisher listed in the sellers.json linked above. In the endpoint URL, replace the {publisherId} placeholder with your publisher ID. This field isn't part of the request body.	String	Yes	Path parameter.

Request Body

Name	Description	Type	Required	Notes
id	Unique identifier for the creative.	String	Yes
adomain	Advertiser domain(s) associated with the creative.	Array	Yes
cat	IAB content category/categories for the creative.	Array	Yes	Required only if passing contextual categories.
cattax	Taxonomy identifier for cat values.	Integer	Yes	Required when cat is provided.
display	Container object for image/banner creative attributes.	Object	Conditional	Required for image creatives.
banner	Banner-specific properties for a display creative.	Object	Conditional	Required for image creatives.
img	URL of the hosted image asset.	String	Conditional	Required for image creatives.
video	Container object for video creative attributes.	Object	Conditional	Required for video creatives.
adm	VAST tag or markup used to render the video creative.	String	Conditional	Required for video creatives.

Sample JSON Request for an Image Creative

Copy

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

Sample JSON Request for a Video Creative

Copy

{
   "id": "123",
   "adomain": ["cats.com"],
   "cat": ["IAB16-3"],
   "cattax": 1,
   "video": {
     "adm": "https://samplevasttag.com"
   }
}

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

To send an existing ad to another publisher, issue a new POST request with a new publisher ID and the same ad ID. All other ad fields must still be present in the request, but they're ignored.

Submit an Ad For Approval by Deal ID

Use this endpoint to submit a creative to a specific publisher for approval using the deal ID.

Note: You can’t use programmatic guaranteed Deal IDs with the Creative Approval API.

Note: Users of third-party DSPs don’t have direct access to Deal ID information. If you need a Deal ID, your media owner is responsible for providing it.

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

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

Request Parameters

Name	Description	Type	Required	Notes
bidderId	The unique identifier for your bidder. In the endpoint URL, replace the {bidderId} placeholder with your bidder ID. This field isn't part of the request body.	String	Yes	Path parameter.
dealId	The unique identifier for your deal. In the endpoint URL, replace the {dealId} placeholder with your deal ID. This field isn't part of the request body.	String	Yes	Path parameter.

Request Body

Name	Description	Type	Required	Notes
id	Unique identifier for the creative.	String	Yes
adomain	Advertiser domain(s) associated with the creative.	Array	Yes
cat	IAB content category/categories for the creative.	Array	Yes	Required only if passing contextual categories.
cattax	Taxonomy identifier for cat values.	Integer	Yes	Required when cat is provided.
display	Container object for image/banner creative attributes.	Object	Conditional	Required for image creatives.
banner	Banner-specific properties for a display creative.	Object	Conditional	Required for image creatives.
img	URL of the hosted image asset.	String	Conditional	Required for image creatives.
video	Container object for video creative attributes.	Object	Conditional	Required for video creatives.
adm	VAST tag or markup used to render the video creative.	String	Conditional	Required for video creatives.

Sample JSON Request for an Image Creative

Copy

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

Sample JSON Request for a Video Creative

Copy

{
   "id": "123",
   "adomain": ["cats.com"],
   "cat": ["IAB16-3"],
   "cattax": 1,
   "video": {
     "adm": "https://samplevasttag.com"
   }
}

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

To send an existing ad to another deal, issue a new POST request with a new deal ID and the same ad ID. All other ad fields must still be present in the request, but they're ignored.

Get the Approval Status of a Specific Ad

Use one of the following options to get the approval status for a specific ad using either the publisher ID or deal ID. Expand each section to learn more.

Get Approval Status by Publisher ID

Use this endpoint to get the approval status of a specific ad by publisher ID.

Note: After submitting an ad, wait up to 10 minutes in production or 30 minutes in staging before checking its status. Until then, the API returns “Ad not found.”

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

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

Request Parameters

Name	Description	Type	Required	Notes
bidderId	The unique identifier for your bidder. In the endpoint URL, replace the {bidderId} placeholder with your bidder ID. This field isn't part of the request body.	String	Yes	Path parameter.
adId	The unique identifier for your ad. In the endpoint URL, replace the {adId} placeholder with your ad ID. This field isn't part of the request body.	String	Yes	Path parameter.
publisherId	The unique identifier for your publisher listed in the sellers.json linked above. In the endpoint URL, replace the {publisherId} placeholder with your publisher ID. This field isn't part of the request body.	String	Yes	Path parameter.

Sample JSON Response

Copy

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

Response Parameters

Name	Description	Type	Returned	Notes
id	Unique identifier for the ad.	String	Always
init	Timestamp indicating when the ad was first received. Represents the initial upload time.	Integer	Always
adomain	Advertiser domain(s) associated with the ad.	Array	Always
display	Container object for image/banner creative attributes.	Object	Conditional	Returned for image creatives only. A video object would show instead for video creatives.
banner	Banner-specific properties for a display creative.	Object	Conditional
img	URL of the hosted image asset.	String	Conditional
audit	Object containing review, status, and feedback information. The following list shows the value codes and status definitions that could apply: Pending Audit: An audit hasn't been completed on this ad. A recommendation can't be made to use this ad, but vendors' policies may override. Pre-approved: Code not currently supported by our Creative Submission API. An audit hasn't been completed on this ad. Subject to vendors' policies, it can be recommended for use. However, once the audit is completed, its status will change and it may or may not be approved for continued use. Approved: The audit is complete and the ad is approved for use. Note, some attributes (for example, adomain, cat, attr, and so on) may have been changed in the process by the auditor. Denied: The audit is complete, and the ad is rejected due to material issues that prevent its use. Changed/Resubmission Requested: Code not currently supported by our Creative Submission API. The ad currently in use differs significantly from the audited version, which may cause it to be rejected until it’s resubmitted and approved. Vendors must communicate offline as to the criteria that constitutes a material change. Expired: The ad has been marked as expired by the vendor. Vendors must communicate offline as to the expected bidding behavior for ads with this status. Tip: Codes showing 500+ are vendor-specific codes.	Object	Always
init	Timestamp indicating when the ad was first reviewed. May match lastmod if only one review has occurred.	Integer	Always
status	Numeric status value representing approval state.	Integer	Always
feedback	List of rejection or review messages associated with the ad.	Array	Conditional	Returned when the ad is rejected or requires changes.
lastmod	Timestamp indicating when the audit was last updated. Reflects the most recent review action	Integer	Always
ext	Container for additional metadata used in audit processing.	Object	Conditional	Extended audit fields.
publisher	The publisher associated with the returned status.	String	Conditional

Get the Approval Statuses of Multiple Ads

Use one of the following options to get the approval statuses for multiple ads using either the publisher ID or deal ID. Expand each section to learn more.

Get Approval Statuses by Publisher ID

Use this endpoint to get the approval statuses of multiple ads by publisher ID.

Note: After submitting an ad, wait up to 10 minutes in production or 30 minutes in staging before checking its status. Until then, the API returns “Ad not found.”

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

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

Request Parameters

Name	Description	Type	Required	Notes
bidderId	The unique identifier for your bidder. In the endpoint URL, replace the {bidderId} placeholder with your bidder ID. This field isn't part of the request body.	String	Yes	Path parameter.
auditStart	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, is returned in the audit.ext.publisher field.	Integer	Yes	Path parameter.
adId	The unique identifier for your ad. In the endpoint URL, replace the {adId} placeholder with your ad ID. This field isn't part of the request body.	String	Yes	Path parameter.
publisherId	The unique identifier for your publisher listed in the sellers.json linked above. In the endpoint URL, replace the {publisherId} placeholder with your publisher ID. This field isn't part of the request body.	String	Yes	Path parameter.

Sample JSON Response

Copy

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

Response Parameters

Name	Description	Type	Returned	Notes
id	Unique identifier for the ad.	String	Always
init	Timestamp indicating when the ad was first received. Represents the initial upload time.	Integer	Always
adomain	Advertiser domain(s) associated with the ad.	Array	Always
display	Container object for image/banner creative attributes.	Object	Conditional	Returned for image creatives only. A video object would show instead for video creatives.
banner	Banner-specific properties for a display creative.	Object	Conditional
img	URL of the hosted image asset.	String	Conditional
audit	Object containing review, status, and feedback information. The following list shows the value codes and status definitions that could apply: Pending Audit: An audit hasn't been completed on this ad. A recommendation can't be made to use this ad, but vendors' policies may override. Pre-approved: Code not currently supported by our Creative Submission API. An audit hasn't been completed on this ad. Subject to vendors' policies, it can be recommended for use. However, once the audit is completed, its status will change and it may or may not be approved for continued use. Approved: The audit is complete and the ad is approved for use. Note, some attributes (for example, adomain, cat, attr, and so on) may have been changed in the process by the auditor. Denied: The audit is complete, and the ad is rejected due to material issues that prevent its use. Changed/Resubmission Requested: Code not currently supported by our Creative Submission API. The ad currently in use differs significantly from the audited version, which may cause it to be rejected until it’s resubmitted and approved. Vendors must communicate offline as to the criteria that constitutes a material change. Expired: The ad has been marked as expired by the vendor. Vendors must communicate offline as to the expected bidding behavior for ads with this status. Tip: Codes showing 500+ are vendor-specific codes.	Object	Always
init	Timestamp indicating when the ad was first reviewed. May match lastmod if only one review has occurred.	Integer	Always
status	Numeric status value representing approval state.	Integer	Always
feedback	List of rejection or review messages associated with the ad.	Array	Conditional	Returned when the ad is rejected or requires changes.
lastmod	Timestamp indicating when the audit was last updated. Reflects the most recent review action	Integer	Always
ext	Container for additional metadata used in audit processing.	Object	Conditional	Extended audit fields.
publisher	The publisher associated with the returned status.	String	Conditional

Get the Approval Statuses by Deal ID

Use this endpoint to get the statuses of multiple ads by deal ID.

Note: You can’t use programmatic guaranteed Deal IDs with the Creative Approval API.

Note: After submitting an ad, wait up to 10 minutes in production or 30 minutes in staging before checking its status. Until then, the API returns “Ad not found.”

Note: Users of third-party DSPs don’t have direct access to Deal ID information. If you need a Deal ID, your media owner is responsible for providing it.

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

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

Request Parameters

Name	Description	Type	Required	Notes
bidderId	The unique identifier for your bidder. In the endpoint URL, replace the {bidderId} placeholder with your bidder ID. This field isn't part of the request body.	String	Yes	Path parameter.
auditStart	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, is returned in the audit.ext.publisher field.	Integer	Yes	Path parameter.
adId	The unique identifier for your ad. In the endpoint URL, replace the {adId} placeholder with your ad ID. This field isn't part of the request body.	String	Yes	Path parameter.
dealId	The unique identifier for your deal. In the endpoint URL, replace the {dealId} placeholder with your deal ID. This field isn't part of the request body.	String	Yes	Path parameter.

Sample JSON Response

Copy

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

Response Parameters

Name	Description	Type	Returned	Notes
id	Unique identifier for the ad.	String	Always
init	Timestamp indicating when the ad was first received. Represents the initial upload time.	Integer	Always
adomain	Advertiser domain(s) associated with the ad.	Array	Always
display	Container object for image/banner creative attributes.	Object	Conditional	Returned for image creatives only. A video object would show instead for video creatives.
banner	Banner-specific properties for a display creative.	Object	Conditional
img	URL of the hosted image asset.	String	Conditional
audit	Object containing review, status, and feedback information. The following list shows the value codes and status definitions that could apply: Pending Audit: An audit hasn't been completed on this ad. A recommendation can't be made to use this ad, but vendors' policies may override. Pre-approved: Code not currently supported by our Creative Submission API. An audit hasn't been completed on this ad. Subject to vendors' policies, it can be recommended for use. However, once the audit is completed, its status will change and it may or may not be approved for continued use. Approved: The audit is complete and the ad is approved for use. Note, some attributes (for example, adomain, cat, attr, and so on) may have been changed in the process by the auditor. Denied: The audit is complete, and the ad is rejected due to material issues that prevent its use. Changed/Resubmission Requested: Code not currently supported by our Creative Submission API. The ad currently in use differs significantly from the audited version, which may cause it to be rejected until it’s resubmitted and approved. Vendors must communicate offline as to the criteria that constitutes a material change. Expired: The ad has been marked as expired by the vendor. Vendors must communicate offline as to the expected bidding behavior for ads with this status. Tip: Codes showing 500+ are vendor-specific codes.	Object	Always
init	Timestamp indicating when the ad was first reviewed. May match lastmod if only one review has occurred.	Integer	Always
status	Numeric status value representing approval state.	Integer	Always
feedback	List of rejection or review messages associated with the ad.	Array	Conditional	Returned when the ad is rejected or requires changes.
lastmod	Timestamp indicating when the audit was last updated. Reflects the most recent review action	Integer	Always
ext	Container for additional metadata used in audit processing.	Object	Conditional	Extended audit fields.
publisher	The publisher associated with the returned status.	String	Conditional

Zendesk Target.4.log-582747842.zip
(3 KB)
Zendesk Target.4.log-582747842.zip
(3 KB)

Creative Submission API

Introduction

What You’ll Learn

Authentication

Submit an Ad For Approval

Request Parameters

Request Body

Sample JSON Request for an Image Creative

Sample JSON Request for a Video Creative

Request Parameters

Request Body

Sample JSON Request for an Image Creative

Sample JSON Request for a Video Creative

Get the Approval Status of a Specific Ad

Request Parameters

Response Parameters

Get the Approval Statuses of Multiple Ads

Request Parameters

Sample JSON Response

Response Parameters

Request Parameters

Sample JSON Response

Response Parameters

Articles in this section