Skip to end of metadata
Go to start of metadata

Creative Service

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/GIF file).
  • We will check media_urls on a regular basis. If a file disappears, the creative will be treated as unaudited.
  • An audit notify request will be sent to the audit_notify_uri handler for each creative whose audit status has changed.
  • Uploading malware or deceptive creatives or purposely mislabeling creatives is absolutely prohibited.
  • It is highly recommended to configure your member (see the Member Service) to receive emails when:
    • The creative is audited (by configuring the audit_notify_email field in the Member Service.)
    • The creative has been scanned by Sherlock (by configuring the sherlock_notify_email in the Member Service.)

For our full audit policy, please see Creatives - Standards and Auditing.

Expired Creative Policy

When a creative (1) has not run and (2) has not been modified for 15 consecutive days, then it will be automatically marked expired ("is_expired": true) and will not serve on any inventory. As of March 2018 expired creatives will be automatically reactivating if your bidder resumes bidding with the creative.


Permissions:

  • Only admin can change audit_status field.
  • Creatives that are modified after they've been audited will return to an pending audit status.
On This Page

REST API

Add a new creative:

Modify an existing creative:

View all of a member's creatives:

Note: If you have more than 100 creatives for a member, please use the num_elements and start_element parameters discussed below

To see a specific number and range of creatives for a member. X is the number of elements to be returned. This should be 100 or lower. Y is the first element of the X elements to be returned. The first element is 0. If you use num_elements, you must also specify the start_element. To retrieve unique paginated results use the parameter &sort=id.asc as shown below.

You may also specify min_last_activity=Z as a filter. Z must be in the form YYYY-MM-DD.

View a specific creative:

Delete a creative:

JSON Structure

Field

Set By

Required

Type

Description

Default

id

internal

yes (on update)

int

The ID of the creative; used for internal matching purposes only.

 

active

internal

no

Boolean

Read-only. The current state of the creative.

 

member_id

client

no

int

The ID of the member this creative belongs to. This is specified in the URI of the API call and does not need to also be in the JSON.

 

mobile

client

no

object

Information needed for mobile creatives to pass the creative audit. See Mobile below.

 
video_attributeclientnoobjectAttributes for third-party in-stream (VAST) video creatives. See  Video Attribute  below for more details. 

description

 

no

string (400)

Optional description associated with the creative.

 

code

client

no

string (100)

The member code of the creative; used for external ID mapping purposes only (see Incoming Bid Response from Bidders).

 

brand_id

client

no

int

The id of the brand of the company advertising the creative.

 

brand

client

no

object

Contains the id of the brand of the company advertising the creative, the name, and the category_id. Will be audited.

To return category_name as well, pass show_category_name=true in the query string of your call.

 

stateinternalnoenumThe state of the creative. Possible values are "active" or "inactive" 
statusclientnoobjectThe status of the creative describing if the creative is ready to serve. See Status below for details. 

media_url

client

no (if content exists)

string(1000)

The URL of the creative - can be image, flash, html, javascript. URL must exist and should be on a CDN or equivalent.

 

media_url_secure

client

no (if content_secure exists)

string(1000)

The URL of the secure (https) creative - can be image, flash, HTML, javascript to be served on a secure ad call. URL must exist and should be on a CDN or equivalent.

 

content

client

no (if media_url exists)

text

The raw javascript or html content of the creative used instead of a media_url.

 

content_secure

client

no (if media_url_secure exists)

text

Javascript or HTML content when "format" is "raw-js" or "iframe-html" served on a secure ad call.

 

audit_status

audit team and client

no

enum ('no_audit','pending','rejected','unauditable', 'audited')

The status of the audit. This field is set by the AppNexus creative auditing team. A creative that does not have audit_status "audited" may be resubmitted for audit by setting the audit_status of the creative to "pending."

 

ssl_status

audit team

no

enum('disabled','pending','approved','failed')

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

'disabled'

audit_feedback

internal

no

string

If the creative has failed the creative audit for AppNexus, this includes the audit team's reasoning.

 

allow_audit

client

no

Boolean

Set to true if you would like to opt the creative into the audit process. 

 

allow_ssl_audit

client

no

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

size_in_bytes

internal

no

int

The size of the media file in bytes.

 

last_checked

internal

no

timestamp

The timestamp that the URL was last checked for existence.

 

not_found

internal

no

boolean

How many times the URL has failed to load. After a certain number of checks, the creative will deactivate.

 

added_by_bidder

internal

no

int

The ID of the bidder that added this creative.

 

campaign

client

no

string(50)

The (optional) name of the campaign for this creative - used for reporting/management purposes.

 

placement

client

no

string(50)

The (optional) name of the placement for this creative - used for reporting/management purposes.

 

flash_click_variable

client

no

string

For flash creatives only. Attempting to POST or PUT to this field for non-flash creatives is not enabled. This is the name of the Flash clickTAG variable into which AppNexus will insert a click tracking URL (if click tracking is enabled) that will be followed when the user clicks on the creative. See Adobe's designer's guide on how to set up a Flash file to use the clickTAG variable.

 

template

client

yes

object

The creative template (ex.:  template_id 6 ) for the creative's format and media type (i.e., flash and expandable). The template includes code to control how the creative renders on web pages. For more details, see Creative Template below.

When using a template for the "raw-html" format (HTML that will not be served in an iFrame), everything in the content field must be escaped (quotes, slashes, etc.,) and wrapped in a document.write(); statement. This is necessary to deliver the content to the page


POST
native_attribute clientyes (required for native ads with template 39461)objectThis is the native object that contains elements required for native ads. For more information, see the description of the Native Attribute object below. 
adx_auditinternalnoobjectRead only. This object contains information about the status and feedback related to the Google Ad Exchange audit of the creative. Information about whether or not a creative has been approved is returned in the audit_status field. 
width 

client

yes

int

The width of the creative in pixels.

 

height

client

yes

int

The height of the creative in pixels.

 

click_url

client

yes (When creative.format is image)

string(1000)

Does not work for Bidder clients.

 

pixels

client

no

array of objects

The pixels to serve with the creative. They can be for external impression tracking, external click tracking, or other purposes, such as adding the AdChoices icon to a creative. See Pixels below for more details.

 

flash_backup_url

 

no

string

Backup for flash format creatives, which will be served if the user's browser doesn't support flash.

 

created_on

internal

no

timestamp

The timestamp when the creative was originally uploaded to AppNexus

 

last_activity

internal

no

timestamp

The timestamp of last modification to this creative.

 

original_content

internal

no

string

This field is for reference only. When a tag with third party content is uploaded to AppNexus, the original content uploaded with the creative will be stored in this field.

Required on POST when submitting as type  raw-html.

original_content_secure

internal

no

string

See original_content. This is the secure version of this content.

 

segments

client

no

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:

 

is_prohibited

internal

no

boolean

True if the AppNexus internal auditing system has detected malicious behavior while analyzing the creative. If True, this creative will not be eligible to serve.

 

is_suspicious

internal

no

boolean

True if the AppNexus internal auditing system has detected suspect behavior while analyzing the creative. If True, this creative will not be eligible to serve.

 

language_id

audit team

no

int

ID of the creative's language - see Language service

 

categories

audit team

no

List of ints

IDs of categories associated with the creative - see Category Service. For GET, these are only returned if you use the flag attributes=true in the request URL.

 

adservers

internal

no

array of objects

Read-only. The ad servers that deliver the creative or are called for data collection purposes during the delivery of the creative.

 

technical_attributes

audit team

no

List of ints

IDs of technical attributes associated with the creative - see Technical Attribute Service. For GET, these are only returned if you use the flag attributes=true in the request URL.

 

passed_sherlock_audit

internal

no

boolean

Indicates whether the creative has been recently checked by the AppNexus automated creative auditing system ("Sherlock").

 

is_expired

internal

no

boolean

Indicates whether the creative has been served or modified in the past 15 days.

 

sla

client

no

integer

The target timeframe when requesting a platform audit.  A value of 0 is standard, 2 is priority/rush.  Default is 0.

Please note when requesting a standard audit, the api will populate this field with a value of null.

 

text_title

client

yes, only if format is text

string up to 25 characters

The top line of text displayed in a text creative

 

text_description

client

yes, only if format is text

string up to 70 characters

The lower line of text displayed in a text creative

 

text_display_url

client

yes, only if format is text

string up to 35 characters

The readable URL displayed in a text creative

 

click_action

no

no

string

The action that the device should take when the creative is clicked. Currently, this field will be set to the only supported click action, "click-to-web"

click-to-web

click_target

no

no

string

The target of the click_action. For click-to-web, this is the click_url of the creative.

click_url will eventually be deprecated in favor of this field.

 

format

 

 

 

Deprecated.

 

native   

Deprecated.

 
click_trackers   Deprecated. 
impression_trackers   Deprecated. 

pixel_url

 

 

 

Deprecated. Please use the pixels field instead.

 

pixel_url_secure

 

 

 

Deprecated. Please use the pixels field instead.

 

pixel_type

 

 

 

Deprecated. Please use the pixels field instead.

 

no_iframes

 

 

 

Deprecated.

 

track_clicks

 

 

 

Deprecated.

 

no_iframes

 

 

 

Deprecated.

 

track_clicks

 

 

 

Deprecated.

 

filter

 

 

 

Deprecated.

 

creative_upload_status

 

 

 

Deprecated. 

 

backup_upload_status

 

 

 

Deprecated.

 

media_subtypes

 

 

 

Deprecated.

 
pop_values   Deprecated. 

Mobile

Field

Type

Description

alternative_landing_page_url

string

An alternative landing page URL that can be viewed in a desktop browser for creatives that have a landing page targeted to a specific device, operating system, or carrier.

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

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.

Video Attribute

The template id for video_attribute is 6439 - Video: Standard VAST (also accepts VPAID), and the object includes the following fields:

Audio

The video attribute object is also used to create audio creatives. The template id for audio is 38745 - AppNexus Audio Template (VAST). Both XML-urls and audio file urls are accepted.

VAST Check

When adding a third party VAST or VPAID video creative, a series of checks are performed on the XML. There are different outputs you may see and corrective action that can be taken. See VAST Check for details.

Field

Type

Description

is_skippable

boolean

If true, the in-stream (VAST) video creative is skippable.

Only third-party skippable VAST video creatives are supported; therefore, when is_skippable is true, is_hosted must be false.

duration_ms

double

The duration, in milliseconds, of the in-stream (VAST) video creative. This must be greater than 0.

wrapper

object

The VAST document wrapper that contains the elements array and the trackers array.

 

Video Attribute Wrapper

The wrapper object contains the following fields:

Field

Type

Description

url

string

URL of the VAST document.

secure_url

string

Secure URL of the VAST document.

elements

array

Elements of the VAST wrapper.


Video Attribute Wrapper Element 

The elements array contains the following fields:

At least one element must be specified.

Field

Type

Description

vast_element_type_id

int

VAST element ID. Possible value:

  • 1: linear

type

string

Read only. Type of element. Possible value: "linear"

trackers

array

VAST event trackers.


Video Attribute Event Trackers

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: 

Field

Type

Description

name

string

The name of the event tracker.

vast_event_type_id

int

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

url

string

The URL of the event tracker.

secure_url

string

The secure URL of the event tracker.

event_type

string

Read only. The type of event corresponding to vast_event_type_id.

Creative Template

You can use the Creative Template Service to view all rendering templates that can be assigned to creatives.

Field

Type

Description

id

int

The ID of the creative template.

Here are standard template ids for the most common creative formats.

IDFormatName

1

url-htmlStandard Banner
2url-jsStandard Banner
3flashStandard Banner
4imageStandard Banner
5raw-jsStandard Banner
6raw-htmlStandard Banner
7iframe-htmlStandard Banner
8url-xmlIn-Banner Video
9url-htmlPopup
10url-jsPopup
11flashPopup
12imagePopup
13raw-jsPopup
14raw-htmlPopup
15iframe-htmlPopup
6439VAST, VPAIDStandard VAST

For Expandable creatives, please see the Expandables and Rich Media wiki page for more details.

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.

  

Native Attribute

The native_attribute object contains the following fields. For more information, see Adding a native creative in the  Examples .

FieldTypeDescription
linkobjectURLs associated with the native creative. See Link below for details.
image_trackersarray of objectsA list of third-party impression tracking URLs intended to be used with native creatives. For more information, see Image Trackers below.
javascript_trackersarray of objects

A list of third-party impression tracking URLs. For more information, see Javascript Trackers below.

All OpenRTB and AppNexus macros are supported for this field except for ${AUCTION_PRICE} and ${PRICE_PAID}.

data_assets
array of objects Attributes of the native creative. See  Data Assets  below for more details.
image_assets array of objects Attributes of each individual image. See  Image Assets  for more details.
video_assets
array of objectsAttributes of the video assets. See Video Assets for more details.
privacy_url
string

If support was indicated in the request, URL of a page informing the user about the buyer’s targeting activity. AppNexus does not provide a default privacy link.

Please use image_trackers for impression trackers and link.trackers for click trackers.


Link

The link object contains the landing page URL, fallback URL and Trackers associated with the native creative. The link object is required for native attribute.

The link object includes the following fields:

Field

Type

Description

Required On

url

string

The landing page of the native creative.

POST,PUT

fallback_url

string

A backup url if the main deeplink url is not supported.

 

trackersarray of objectsA list of third-party tracking URLs intended to be used with native creatives. This should be an array of click trackers. See Trackers below for more details. 

All native creatives are submitted for secure auditing by default.

  • If the secure url has not been specified for any tracker (image trackers, javascript trackers, and creative image asset trackers), secure audit is disabled for that creative.
  • If the secure URL has not been specified, but URL is prefixed with `https`, the creative will be submitted for secure audit.

Trackers

Field

Type

Description

url

string

A third-party tracking URL. This should contain your click tracker.

url_secure

string

(optional) A secure third-party tracking URL. This should contain your click tracker.


Image Trackers
Name
Type
Description
url stringA third-party impression tracking URL. This should contain your impression tracker.
url_secure stringA third-party impression tracking URL (that uses SSL). This should contain your impression tracker.
Javascript Trackers
Name
Type
Description
url stringA third-party javascript tracking URL.
url_secure stringA third-party javascript tracking URL (that uses SSL)
Data Assets

The data_assets object includes the following fields:

FieldTypeDescription
data_typestring

The asset type for the native creative. Possible values:

    • sponsored_by
    • title
    • description
    • rating
    • call_to_action
    • display_url
    • likes

    • downloads

    • price

    • sale_price

    • phone

    • address

    • additional_description

valuestring

The description of the data_type asset that you have specified.

    • "sponsored_by" - brand name of the sponsor
    • "title" - title of the creative
    • "description" - description of the product or service being advertised
    • "rating" - rating of the product being offered
    • "call_to_action" - suggested action for next step
    • "display_url" - the URL you would like displayed
    • "likes" - social media likes

    • "downloads" - number downloads/installs of this product

    • "price" - Price for product / app / in-app purchase

    • "sale_price" - sale price that can be used together with price to indicate a discounted price

    • "phone" - phone number

    • "address" - address

    • "additional_description" - the longer version of your ad's description

Image Assets

The image_assets object includes the following fields:

FieldTypeDescription
creative_asset_imageobject

The object containing details of the creative asset. Required for third-party native creatives. See details in Creative Asset Image below.

image_typestring

The format of the image. Possible values include:

  • icon_image
  • main_image

Creative Asset Image

FieldTypeDescription
urlstringThe url of the image.
url_securestringThe secure url of the image.
widthintThe width of the image. Value must be > 0
heightintThe height of the image. Value must be > 0

Video Assets

The video_assets object includes the following fields:

FieldTypeDescription
video_creative_idint

The AppNexus creative id of the video asset associated with the native creative.

Note: A separate video creative must be registered first before registering a native video creative.


Pixels

You use this array to add up to five AppNexus-approved and custom pixels to a creative.

AppNexus-approved pixels are from trusted, commonly-used providers. Most of them do not cause the creative to be resubmitted for audit. To add an AppNexus-approved pixel to a creative, you need to pass only the pixel_template_id and the number of params that the pixel requires. See the Adding an AppNexus-approved pixel to a creative example below for further guidance. Note that you can use the Pixel Template Service to get information about these pixels, including whether or not they trigger re-audit.

Custom pixels are defined by you and do cause the creative to be resubmitted for audit. To add a custom pixel, you need to pass only the format and, depending on the format, the content or url. See the Adding a custom pixel to a creative example below for further guidance.

Field

Type

Description

id

int

Read-only. The ID of the pixel.

pixel_template_id

int

The ID of the AppNexus-approved pixel. You can use the Pixel Template Service to get this ID.

param_1

string

For AppNexus-approved pixel: The value for the first parameter in the pixel content or URL. To find out how many parameters are required for an AppNexus-approved pixel, use the Pixel Template Service.

param_2

string

For AppNexus-approved pixel: The value for the second parameter in the pixel content or URL.

param_3

string

For AppNexus-approved pixel: The value for the third parameter in the pixel content or URL.

param_4

string

For AppNexus-approved pixel: The value for the fourth parameter in the pixel content or URL.

param_5

string

For AppNexus-approved pixel: The value for the fifth parameter in the pixel content or URL.

format

enum

The format of the pixel. Possible values: "raw-js", "url-html", "url-js", or "url-image".

content

string (255)

If the pixel format is "raw-js", the HTML or JavaScript content to serve with the creative.

url

string (255)

If the pixel format is "url-html", "url-js", "url-image", or "raw-url", the URL of the HTML, JavaScript, or Image pixel to serve with the creative.

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
name stringThe segment's name. 

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"):

  • width
  • height
  • content
  • media_url
  • click_url
  • template
  • custom_macros
  • media_subtypes
  • language
  • categories
  • technical_attributes
  • brand_id
  • pixel_url
  • pixels (if adding or removing a custom pixel or an AppNexus-approved pixel)
  • text_title (if text creative)
  • text_description (if text creative)
  • text_display_url (if text creative)
  • pop_window_maximize (if pop creative)
  • pop_is_tag_initiated (if pop creative and changing from false to true)
  • 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

Adding a creative
View the creative that was added
Modifying a creative
Submit a creative for audit
Unexpire a creative and resubmit for audit
Submit a mobile creative for audit
Submit a creative for priority audit
View the estimated audit time for your creative ('sla_eta')
Adding a creative (third-party HTML tag)
Adding an iframe-html creative
Adding an AppNexus-approved pixel to a creative
Adding a custom pixel to a creative
 Add a video creative with video attribute object and wrapper
Adding a native creative
Determining the Technical Atttributes assigned to your creative

Creative Macros

The Impression Bus supports two types of creative macros replaced in real time: pre-defined AppNexus creative macros and custom macros that can be defined by the bidder. The main difference between the two is the perspective. For example, the impression bus has no knowledge of a Campaign or an Insertion Order when a real time bid is placed, so any objects supported with a bidder's internal object model and required in a macro should be supported using custom macros.

Macro Restrictions

  • Only pre-defined AppNexus macros and custom macros are supported when registering creatives.
  • DO NOT use OpenRTB macros when registering creatives.
    OpenRTB macros are for use only in the bid response.
  • Do not give a custom macro a name that matches the name of an OpenRTB macro.

AppNexus Creative Macros

See AppNexus Macros for a complete list of the available creative macros.

Click Tracking Example:

 

Custom Macros

Using custom_macro functionality in the Bid Response, you can dynamically pass into the pre-registered creatives. For instance, if you wanted to always return a particular campaign and reporting code, you could set up your creative as follows:

Then, when your bidder responds to an auction, the bid response can specify the name and value of the macros to replace, by including, for example:

Even if the value is an integer, it must be placed within quotation marks (for example,  "42" ).