Skip to end of metadata
Go to start of metadata

Creative VAST Service

You can use the Creative Vast Service to add video or audio creatives to AppNexus. All creatives must be attached to an advertiser or publisher.

  • You can view your advertiser ID by calling the Advertiser Service.
  • You can view your publisher ID by calling the Publisher Service.
  • You can attach a creative to a publisher for use as a default creative for a placement. You would then attach the creative to a placement via its ID using the Placement Service.

video_attribute is always required on the creative-vast endpoint.

On This Page

Auditing

AppNexus works with members who care deeply about brand and reputation. For this reason, we are careful to ensure that the advertisements (creatives) that pass through our system are acceptable to all parties. For quality assurance, all creatives that serve on third-party inventory must be pre-registered using the Creative Service.

  • Creatives are identified by their media_url (either a third-party adserver URL or a Content Delivery Network URL for a Flash or video file).
  • AppNexus checks media_urls on a regular basis. If a file disappears, the creative will be treated as unaudited.
  • Once a creative has passed AppNexus audit, certain changes to the creative cause it to be resubmitted for audit. For more details, see Changes That Cause Re-Audit.
  • For more details on auditing, see Creative Standards and Auditing.

REST API

Add a new hosted video or audio creative to one of your advertisers:

Add a new hosted video or audio creative to one of your publishers:

Modify an existing hosted video or audio creative:

View all hosted video or audio creatives:

View all hosted video or audio creatives for an advertiser or publisher:

You can filter for creatives based on when they first and last served. This is particularly useful when you are approaching your object limit and need to identify creatives that can be deleted from the system. For more details, see First Run / Last Run.

View a specific creative:

View multiple creatives by ID using a comma-separated list:

View creative audit stats:

The response tells you the number of creatives with each AppNexus, Microsoft, and Google audit status. For the response format, see the example below.

Delete a creative:

You cannot delete a creative that is used as the default creative for a member or placement. Default creatives can be deleted once they are disassociated from a placement.


JSON Fields

Field

Type (Length)

Description

Default

Required On

id

int

The internal ID associated with the creative.

Auto-generated number

PUT, in query string

code

string (100)

The custom code for the creative.

  

code2

string (100)

The additional custom code for the creative.

  

name

string (100)

The name of the creative.

  
typeenum

Read-only. The type of creative. Possible values:

  • "standard"
  • "html"
  • "video"

Alpha-Beta Notice

This field or feature is part of functionality currently in either Alpha or Beta phase. It is therefore subject to change.

  

advertiser_id

int

The ID of the advertiser to which the creative is attached.

 

POST/PUT, in query string, if the creative is attached to an advertiser

publisher_id

int

The ID of the publisher/media buy to which the creative is attached.

 

POST/PUT, in query string, if the creative is attached to a publisher

brand_id

int

The ID of the brand of the company advertising the creative. If included, it will be verified by the AppNexus auditing team. If not included, it will be assigned by the auditing team. To retrieve a full list of brands, see the Brand Service.

  

state

enum

Read only. The state of the creative. Possible values: "active" or "inactive".

 

 
status objectThe status of the creative describing if the creative is ready to serve. For more details, see Status below.  
click_track_resultenumThe result of the click track test, a feature only available in the Console user interface. Possible values: "not_tested", "passed", or "failed"."not_tested" 

campaigns

array of objects

The list of campaigns to which the creative is associated. For more details, see Campaigns below.

This field will only be returned if an advertiser_id is specified in the querystring.

  

template

object

The creative template (ex.: template_id 6439) for the creative's format and media type. The template includes code to control how the creative renders on web pages.

Possible values:

  • Video creatives: 6439
  • Audio creatives: 38745
 

POST

media_url

string (1000)

The URL of the creative - can be flash, HTML, javascript (see format). URL must exist and should point to a CDN hosted VAST XML file.

This field only applies to third party creatives.

 

POST, if not using content

media_url_secure

string (1000)

The URL of the secure (HTTPS) creative - can be flash, HTML, javascript (see format) to be served on a secure ad call. URL must exist and should point to a CDN hosted VAST XML file.

This field only applies to third party creatives.

  

click_url

string (2000)

The (optional) landing page URL for non-3rd party image and flash creatives.

This value must begin with "http://" or "https://"

 

POST, if template is for the "image" format

file_name

string (1000)

This field does not apply to hosted video creatives.

 

 

audit_status

enum

The audit status of the creative. Possible values: "no_audit", "pending", "rejected", or "audited".

Notes:

  • If allow_audit is false, this field must be "no_audit".
  • If a creative is expired, you can reanimate it by changing this field. Setting it to "pending" will resubmit it for auditing. For changes that automatically resubmit the creative for auditing, see Changes That Cause Re-Audit.

"pending"

 

audit_feedback

string

Read-only. The creative auditing team can pass messages about a creative in this field.

  

allow_audit

Boolean

If true, the creative will be submitted for auditing. If false, the creative will not be submitted. Unaudited creatives can only run on a network's managed inventory.

Notes:

  • If audit_status is "no_audit", this field must be "false".
  • If your member is not yet active, you can add creatives, but they will not be submitted for audit (allow_audit will be false). Once your member has been activated, if you want these creatives to be audited, you must update the creatives and set allow_audit to true.

true

 

ssl_status

enum

The ssl (HTTPS) status of the creative. Only creatives with ssl_status = approved will be eligible to serve on secure inventory. Note: If a creative fails the ssl Sherlock audit, you can submit it for a retest (once you've fixed the downstream non-secure content) by changing this field to "pending". Allowed values:

  • "disabled"
  • "pending"
  • "approved"
  • "failed"

"disabled"

 

allow_ssl_audit

Boolean

If true, the creative will be submitted for secure (HTTPS) auditing. If false, the creative will not be submitted. If true, either media_url_secure or content_secure is required as well.

false

 

google_audit_status

enum

Deprecated. Please see adx_audit instead.

 

 

google_audit_feedback

string

Deprecated. Please see adx_audit instead.

  

msft_audit_status

enum

Deprecated.

 

 

msft_audit_feedback

string

Deprecated.

  

is_self_audited

Boolean

If true, the creative is self-audited and thus will not go through platform (AppNexus) audit. The creative can only serve on inventory that accepts your self-classified creative or on inventory that accepts unaudited creatives.

false

 

is_expired

Boolean

Read-only. If your creative (1) has not run and (2) has not been modified in 45 days, then it will be automatically marked expired and will not serve on any inventory.

  • Expired creatives must be reaudited to run on third-party inventory. To unexpire a creative for third-party inventory, set audit_status to "pending".
  • Expired creatives do not need to be reaudited to run on direct inventory. To unexpire a creative for direct inventory, set audit_status to "no_audit".

false

 

is_prohibited

Boolean

Read-only. If Sherlock flags the creative for having malware or loading blacklisted domains, this is set to true to prevent the creative from serving.

false

 

is_hosted

Boolean

Read-only. If true, the creative is hosted by AppNexus.

  

lifetime_budget

double

The lifetime budget in dollars. Note: To include this field in a GET response, pass attributes=1 in the query string.

unlimited

 

lifetime_budget_imps

int

The lifetime limit for number of impressions. Note: To include this field in a GET response, pass attributes=1 in the query string.

unlimited

 

daily_budget

double

The daily budget in dollars. Note: To include this field in a GET response, pass attributes=1 in the query string.

unlimited

 

daily_budget_imps

int

The daily limit for number of impressions. Note: To include this field in a GET response, pass attributes=1 in the query string.

unlimited

 

enable_pacing

Boolean

If true, daily budgeted spend is spread evenly throughout a day. Note: To include this field in a GET response, pass attributes=1 in the query string.

true

 

allow_safety_pacing

Boolean

Admin-only. If true, spend per minute is limited to a maximum of 1% of the lifetime budget and 5% of the daily budget.

  

profile_id

int

You can attach targeting such as gender and geography to a creative by creating a profile and associating it here.

  

folder

object

To arrange your creatives in folders for convenience (usually in the UI) you will create a folder using the Creative Folder Service and then associate it here via folder ID or in the Creative Folder service via creative ID. Output is {"id": "41", "name": "MyFolder"}

  
line_itemsarray of objectsThe line items that are associated with the creative. See Line Items below for more details.  

is_control

Boolean

This is a flag used to mark this creative as part of a control/test group in A/B testing. For more information, see Test and Control Targeting .

false

 

segments

array

A list of segments that a user will be added to upon viewing or clicking on this creative. For more information, see Segments below.

Example:

  

created_on

timestamp

Read-only. The date and time when this creative was created. If it was created before January 2010, this will be zero.

  

last_modified

timestamp

Read-only. The date and time when the creative was last modified.

  

creative_upload_status

enum

Deprecated.

  

categories

array of objects

The categories that describe the creative and offer type. Note: To include categories in a GET response, pass attributes=1 in the query string. To retrieve a full list of categories, see the Category Service.
Example:

  

adservers

array of objects

Read-only. The ad servers that deliver the creative or are called for data collection purposes during the delivery the creative. Note: To include adservers in a GET response, pass attributes=1 in the query string. To retrieve a full list of ad servers, see the Ad Server Service .
Example:

  

technical_attributes

array of objects

The attributes that describe technical characteristics of the creative, such as "Expandable" or "Video". Note: To include technical attributes in a GET response, pass attributes=1 in the query string. To retrieve a full list of technical attributes, see the Technical Attribute Service.
Example:

  

language

object

The language of the creative. To retrieve a full list of languages, see the Language Service.
Example:

  
brandobjectRead-only. The brand of the company advertising the creative and the category associated with the brand. For more details, see Brand below.  

sla

int

Creatives set to "0" will be submitted for audit with a standard SLA.

Creatives submitted with any number other than 0 will result in a priority audit (when enabled) and resulting fees.

If you have a supplemental services agreement with AppNexus for priority audits, you can submit a creative for priority audit (auditing within 2 hours during business hours) by setting this field to 2. For more details about priority auditing, see Creative Standards and Auditing.

  

sla_eta

timestamp

Read-only. The estimate time of completion for a priority audit.

  
currencystringRead-only. The code that defines the advertiser's primary currency (for example, USD). For more details about the currency types available, see Currency Service.Member's default currency 

first_run

timestamp

Read-only. The date and time when the creative first served, refreshed on an hourly basis. This value reflects the UTC time zone. To include this information in a GET response, pass flight_info=true in the query string. For details about how to filter creatives based on when they first served, see First Run / Last Run below.

  

last_run

timestamp

Read-only. The date and time when the creative last served, refreshed on an hourly basis. This value reflects the UTC time zone. To include this information in a GET response, pass flight_info=true in the query string. For details about how to creatives based on when they last served, see First Run / Last Run below.

  
video_attributeobjectAttributes for third-party in-stream (VAST) and hosted video and audio creatives. See Video Attribute below for more details.nullPOST , if template is for "Standard VAST" media subtype

competitive_brands

array of objects

Creatives associated with the brands in this array will not serve together in /mtj auctions. The classic example of competing brands is Coke vs. Pepsi. See Competitive Brands below. For more information about the brands in our system, see the Brand Service. For an overview of /mtj auctions, see MultiTags.

n/a

 

competitive_categories

array of objects

Creatives associated with the categories in this array will not serve together in /mtj auctions, e.g., "Dating" and "Education". See Competitive Categories below. For more information about the categories we apply to creatives (and brands), see the Category Service. For an overview of /mtj auctions, see MultiTags.

n/a

 
adx_auditobjectRead-only. This object contains information about the status and feedback related to the Google AdExchange audit of the creative. Information about whether or not a creative has been approved is returned in the audit_status field.  
member_id intThe ID of the member that owns the creative.  
media_assetsarray of objects

It is  used to associate AppNexus hosted files to your creative. This field will be auto-populate when uploading files via the API.

Example:

creative_field should always be null for a VAST creative.

  
ad_typestring

This field only applies when you are associating creatives to augmented line items.

The type of creative used.  Possible values: 

  • "banner"
  • "video" (includes audio creatives)
  • "native"

This value determines how auction items are tracked for the line item's buying strategy, paying strategy, optimization options, creative association, and targeting options. 

All creatives associated to a line item must have the same ad type, which should match the ad_type selected in the Line Item Service - ALI

  

Audio

Field

Type

Description

click_target

string

The target of the click_action, which is the action that the device should take when the creative is clicked. Enter a URL that our audit team can use to verify the brand and attributes of your audio creative. Ensure that the site the URL points to is in the same language as the audio. This URL is used only  for auditing purposes. 

You must provide an auditable URL in order for your creative to pass auditing.

Line Items

Each object in the line_items array includes the following fields. To obtain information for "id" or "code" fields, you can use the Line Item Service - ALI .

Field

Type (Length)

Description

Required On

name

string

Read-only. The name of the line item.

 

state

enum

Read-only. The state of the creative. Possible values: "active" or "inactive".

 

id

int

The ID of the line item. Either "id" or "code" is required when updating line item association.

PUT

code

string

The custom code for the line item. Either "id" or "code" is required when updating line item association.

PUT

Campaigns

Each object in the campaigns array includes the following fields. To obtain information for "id" or "code" fields, you can use the Campaign Service.

Field

Type (Length)

Description

Required On

id

int

The ID of the campaign. Either "id" or "code" is required when updating campaign association.

PUT
campaign_idintThe ID of the campaign. 
creative_idintThe ID of the creative. 

name

string

Read-only. The name of the campaign.

 

state

enum

Read-only. The state of the campaign. Possible values: "active", "inactive", or "parent_inactive".

 

code

string

The custom code for the campaign. Either "id" or "code" is required when updating line item association.

PUT

Status

Name

Type

Description

Default

Required on

user_ready

boolean

The status of the creative set by the user describing if the creative is ready to serve or not. Possible values: "true" or "false"

true

 

hosted_assets_association_complete

boolean / null

Read-only. Status of the creative uploaded by AppNexus' internal systems. Possible values: "true" or "false" for hosted creatives and "null" for third-party creatives.

 

 

Competitive Brands

For more information about brands, see the Brand Service.

Name

Type

Description

Default

Required on

id

int

The ID of the brand.

n/a

n/a

name

string

The name of the brand.

n/a

n/a

Competitive Categories

For more information about categories, see the Category Service.

Name

Type

Description

Default

Required on

id

int

The ID of the category.

n/a

n/a

name

string

The name of the category.

n/a

n/a

Video Attribute

video_attribute is required for both audio and video creatives on the creative-vast endpoint. Template ids are:

  • 6439 - Video: Standard VAST
  • 38745 - Audio: Standard VAST

 The video_attribute object includes the following fields:

FieldTypeDescriptionRequired On
is_skippableboolean

Deprecated. AppNexus automatically adds a skip tracker to all trafficked VAST creatives.

 
duration_msdoubleThe duration, in milliseconds, of the in-stream (VAST) video or audio creative. This must be greater than 0.POST,PUT  
wrapperobject

The VAST document wrapper that contains the elements array and the trackers array. See Video Attribute Wrapper for details.

Either the wrapper or inline object is required on POST,PUT
inlineobjectThe inline VAST document. See Video Attribute Inline for details.Either the wrapper or inline object is required on POST,PUT

Either the wrapper or inline object can be specified in the creative call. They are mutually exclusive.

Video Attribute Wrapper

The wrapper object contains the following fields:

FieldTypeDescriptionRequired On
urlstringURL of the VAST document.POST, PUT

secure_url

stringSecure URL of the VAST document. 
elementsarrayElements of the VAST wrapper.POST, PUT
Video Attribute Wrapper Element

The elements array contains the following fields:

At least one element must be specified.

FieldTypeDescription
vast_element_type_idint

VAST element ID. Possible value:

  • 1: linear
typestringRead only. Type of element. Possible value: "linear"
trackersarrayVAST event trackers.
media_filesarrayMedia files in the VAST wrapper.
Video Wrapper Event Tracker

You can drop pixels on every event that we track in reporting (see vast_event_type_id below). Add the pixel(s) as trackers on the creative. The trackers array contains the following fields:

FieldTypeDescription

name

stringThe name of the event tracker.
vast_event_type_idint

The ID of the VAST event. Possible values:

  • 1: service
  • 2: start
  • 3: skip
  • 4: error
  • 5: first_quartile
  • 6: midpoint
  • 7: third_quartile
  • 8: completion
  • 9: impression
  • 10: click
urlstringThe URL of the event tracker.
secure_urlstringThe secure URL of the event tracker.
event_typestringRead only. The type of event corresponding to vast_event_type_id.
Video Wrapper Media Files

Field

Type

Description

maintain_aspect_ratio

string

Read only. The ratio between a media file's sizes in dif­fer­ent dimen­sions.

scalable

string

Read only. Is the media file scalable.

media_assetstringRead only. The values are derived from the video or audio upload app.

Video Attribute Inline

FieldTypeDescriptionRequired on
ad_titlestringThe title of the ad.POST, PUT

ad_description

stringOptional. The description of the ad. 
linearobject Ad that appears before, after or during a break in content.  
companion_adsarray of objects

Companion banner ads that appear in banner placements in the same page as the accompanying video or audio.

 
Inline Linear Object  

Field

Type

Description

trackers

array

Inline linear trackers.

media_files

array

The inline linear media files.

skipoffset_secondsint

The number of seconds that is allowed for the video to play, before it can be skipped. The default value is null.

This field can only be used if you are serving ads into a placement by the same member.

Inline Linear Trackers

Field

Type

Description

Required on

vast_event_type

string

The type of tracking event. Possible Values:

  • service
  • start
  • skip
  • error
  • first_quartile
  • completion
  • impression
  • click
POST, PUT

name

string

The name of the tracker.

 
urlstringThe URL of the inline linear event tracker.POST, PUT
secure_urlstringThe secure URL of the inline linear event tracker. 
Inline Linear Media Files

Field

Type

Description

maintain_aspect_ratio

string

Read only. The ratio between a media file's sizes in dif­fer­ent dimen­sions.

scalable

string

Read only. Is the media file scalable.

media_assetsstringRead only. The values are derived from the video upload app.

Inline Companion Ads Object

Field

Type

Description

trackers

array of objects

Inline companion ad trackers

companion_creative_id

int

The ID of the the companion ad.

Segments

These fields will be included in the Segments array:

Field

Type

Description

Required on

id

int

The ID of the segment.POST, PUT

segment_id

int

The ID of the segment. This field contains the same information as the id field.

 

action

enum

The action taken by users that will add them to the segment. Possible values: "add on view" or "add on click".

POST, PUT
namestringThe segment's name. 

Brand

The brand object contains the following fields.

This object is read-only. To set the brand for a creative, use the brand_id field outside of this object.

Field

Type

Description

id

int

Read-only. The ID of the brand of the company advertising the creative.

name

string

Read-only. The name of the brand of the company advertising the creative.

category_idintRead-only. The ID of the category associated with the brand
category_namestring

Read-only. The name of the category associated with the brand.

The category_name field is returned only when you pass show_category_name=true in the query string of your call.

First Run / Last Run

To include the first_run and last_run fields in a GET response, pass flight_info=true in the query string. You can also filter for creatives based on when they first and last served, as follows:

Retrieve only creatives that have never served
Retrieve only creatives that first served on or after a specific date
Retrieve only creatives that first served on or before a specific date
Retrieve only creatives first served within a specific date range
Retrieve only creatives that last served on or after a specific date
Retrieve only creatives that last served on or before a specific date
Retrieve only creatives that last served within a specific date range

Changes That Cause Re-Audit

Once a creative has passed AppNexus audit (audit_status is "audited"), changing any of the following fields causes the creative to be resubmitted for audit (allow_audit is set to "pending"

  • media_url
  • click_url
  • language
  • categories
  • technical_attributes
  • brand_id
  • pixel_url
  • video_attribute
  • media_assets

Also, if the audit_status is "no_audit", changing allow_audit from "false" to "true" causes the creative to be resubmitted for AppNexus audit.

Examples

Upload a video or audio creative

A video_attribute object with wrapper example

video_attribute object with inline VAST example

Related Topics