Skip to end of metadata
Go to start of metadata

Creative Service

You can use the Creative Service to add 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.

Hosted and third-party Video and Audio services can only be accessed using the Creative Vast Service. Hosted and third-party HTML creatives can only be accessed using the Creative HTML Service.

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, image, 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 creative to one of your advertisers:

Add a new creative to one of your publishers:

Modify an existing creative:

View all creatives:

View all 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.

Find out which fields you can filter and sort by:

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 (400)

The name for 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.

  

format

enum

Deprecated.

  

template

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

thirdparty_page

object

This field is no longer in use.

 

 

custom_macros

array of objects

The values for custom macros used in the creative template. For more details, see Custom Macros below.

 

POST, if template includes required custom macros

width

Int

The width of the creative; the string should contain an int.

 

POST, if template is for the "Banner" or "Expandable" media type

height

Int

The height of the creative; the string should contain an int. If the creative's template has a Pop media type, then either the creative's height must be set OR pop_window_maximize (in the pop_values field) must be true (but not both).

Notes:

  • You can only submit pop creatives of accepted sizes for AppNexus audit. If media_subtype_id within the template array is 4 (popunder) and audit_status is "pending", height must be set to 300 and width to 720. If media_subtype_id within the template array is 2 (popup) and audit_status is "pending", width and height must be one of the following: 250x250, 300x250, 550x480.
 

POST, if template is for the "Banner" or "Expandable" media type

media_url

string (1000)

The URL of the creative - can be image, flash, HTML, javascript (see format). URL must exist and should be on a CDN or equivalent.

 

POST, if not using content

media_url_secure

string (1000)

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

  

click_url

string (2000)

click_url is being deprecated in favor of click_target.

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

 

POST, if template is for the "image" format

file_name

string (1000)

The file name and extension for a hosted creative. Allowed file types: jpg, gif, png, swf, flv, mp4, wmv, f4v, avi, m4v, mov, and mpg.

 

POST, if adding a hosted creative

flash_click_variable

string (255)

The ClickTag variable in a Flash creative. AppNexus can execute and track user clicks on a Flash creative only if you provide the exact variable in the file (clickTAG, ClickTag, Clicktag, etc). You can use the ClickTags Service to identify this variable. If you need to specify more than one ClickTag variable for a single creative, please contact support.

This field may only be updated (via POST or PUT) for Flash creatives.

  

content

string

Javascript or HTML content when "format" is "raw-js" or "iframe-html". For a hosted creative, the content of the file must be base64-encoded and submitted as a string within the content field.

When using a template (ex.: template_id 6) 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.

 


There is a maximum length in the content field of 65535 characters. 

3rd party tag holder

POST, if not using media_url

content_secure

string

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

  

original_content

string

The value you pass into the "content" field through the UI will be returned in this field unchanged. The "content" field will contain the content modified by AppNexus to properly serve. This field can also be uploaded directly through the API. In this case, the value uploaded to this field will be referenced in the content section of the UI (Creative Content > Tag field).

 POST when submitting as type raw-html.

original_content_secure

string

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

  

macros

string

Read-only. The API pulls out macros and puts them in this field so that the bidder knows which macros to expect.

  

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.
  • You can only submit pop creatives of accepted sizes for AppNexus audit. If media_subtype_id within the template array is 4 (popunder), audit_status can not be set to "pending" unless width is 720 and height is 300. If media_subtype_id within the template array is 2 (popup), audit_status can not be set to pending unless width and height are one of the following: 250x250, 300x250, 550x480.

"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.
  • You can only submit pop creatives of accepted sizes for AppNexus audit. If media_subtype_id within the template array is 4 (popunder), allow_audit can not be set to 1 unless width is 720 and height is 300. If media_subtype_id within the template array is 2 (popup), allow_audit can not be set to 1 unless width and height are one of the following: 250x250, 300x250, 550x480.

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.

  

facebook_audit_status

enum

This field is no longer in use.

 

 

facebook_audit_feedback

string

This field is no longer in use.

  

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.  

pixels

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.

  

pixel_url

string (100)

Deprecated. Please use the pixels array instead. The URL of an impression pixel to serve with the media URL or content.

  

pixel_url_secure

string (100)

Deprecated. Please use the pixels array instead. The URL of a secure (HTTPS) impression pixel to serve with the media URL content on a secure ad call.

  

pixel_type

enum

Deprecated. Please use the pixels array instead. The type of impression pixel. This field must be set if pixel_url is used. Possible values: "javascript" or "image".

  

no_iframes

Boolean

Deprecated. If true, the bidder will not serve this creative when an iframe is detected in the ad call.

false

 

track_clicks

Boolean

Deprecated.

true

 

flash_backup_content

string

Write-only. For a flash creative, this is the content of the backup creative that will be served if a user's browser does not support flash. For an in-banner video creative, this is the content of the poster image that will display before users click play and after the video has finished playing. This field must be used in combination with flash_backup_file_name.

Once the backup creative has been uploaded, the content will be stored on the CDN, and the location will be set in the flash_backup_url field. Neither flash_backup_content nor flash_backup_file_name can be retrieved on GET.

 

POST/PUT, if using flash_backup_file_name

flash_backup_file_name

string

Write-only. This field must be used in combination with flash_backup_content. This is the file name and extension of the backup creative.

 

POST/PUT, if using flash_backup_content

flash_backup_url

string (100)

For a flash creative, this is the URL of a 3rd-party creative that will be served if the user's browser does not support flash. For an in-banner video creative, this is the URL of the poster image that will display before users click play and after the video has finished playing.

  

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 (Standard Line Item).

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.

  

media_subtypes

array of strings

Deprecated.

  

creative_upload_status

enum

Deprecated.

  

backup_upload_status

enum

Deprecated.

  

use_dynamic_click_url

Boolean

If true, the (optional) landing page URL for non-3rd party image and flash creatives is set at the campaign or line item level. See Dynamic Landing Pages for more information.

false

 

size_in_bytes

int

Read-only. The size of an uploaded creative (in bytes).

  

text_title

string (25)

The top line of text displayed in a text creative

 

POST, if template is for the "text" format

text_description

string (70)

The lower line of text displayed in a text creative

 

POST, if template is for the "text" format

text_display_url

string (35)

The readable URL displayed in a text creative

 

POST, if template is for the "text" format

click_action

enum

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

string (2000)

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. In the meantime, setting click_url or click_target will have the same effect.

  

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

pop_values

array

Deprecated.

  

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.

  

mobile

object

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

  
video_attributeobject

Attributes for third-party in-stream (VAST) and hosted video creatives.

To add & update vast creatives, use the /creative-vast service. See Creative Vast Service for details.

null 

stats

object

The stats object has been deprecated (as of October 17, 2016). Use the Report Service to obtain statistical information instead.

  

content_source

string

The source of this creative's content. Allowed values:

  • "standard": This creative consists of content hosted on an ad server, that will generally be retrieved with a single HTTP request.
  • "mediation": This creative is a container that is used to fetch content from another ad server for the purposes of mediation. Due to the way mediation is performed, this can involve making multiple HTTP requests in sequence. For more information, see the Creative Custom Request Template Service.

    If this field is set to "mediation", the following actions will occur:

    • A "mediation" technical attribute will be added to the creative's technical_attributes array.

    In addition, the following validations will be performed:

    • audit_status" cannot be set to "pending"; instead it will always be set to "no_audit".
    • allow_audit cannot be set to true; instead it will always be set to false.
    • The custom_request_template multi-object must be defined for the creative.
    • The custom_macros array must be populated with macros defined by the template parameters associated with the Custom Request Template.
    • The following fields will no longer be required:
      • content
      • media_url
      • template

"standard"

 

custom_request_template

multi-object

If the value of this creative's content_source field is set to "mediation", this object describes the association between this creative and a custom request template which is used to populate the creative with content. For more information, see Custom Request Template.

null

PUT, if content_source is set to "mediation"

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

 
thirdparty_pixelsarray of objectsAn array of third-party pixels associated with the creative. You can automatically attach these pixels to all creatives owned by an advertiser or member using the Third-party Pixel service or attach them individually at the creative level using the Creative Service.nullPUT
nativeobjectIf this creative is a "native ad", this object is populated with the elements required for native ads. For more information, see the description of the Native object below.nullRequired on POST and PUT for native ads. Technically, native ads are identified by our system as those creatives that have a template with a creative_format_id of 12 that identifies them as "native".
native_attribute objectThis is the new native object which contains elements required for native ads. For more information, see the description of the Native Attribute object below.nullRequired for native ad with template 39461
click_trackersarray of objectsA list of third-party click tracking URLs intended to be used with native creatives. For more information, see Click Trackers below.  
impression_trackersarray of objectsA list of third-party impression tracking URLs intended to be used with native creatives. For more information, see Impression Trackers below.  
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.  
flash_backup_url_securestringThis is the secure version of flash_backup_url, which is served on a secure ad call.  
msft_external_audit_feedbackstringDeprecated.  
msft_external_audit_statusenumDeprecated.  
member_idintThe ID of the member that owns the creative.  
media_assetsarray of objects

The asset id of the original file and a field describing what the asset must be used for. It is used to associate AppNexus hosted files to your creative. This array will auto-populate when uploading files via the API. For more information, see Media Assets below.

  
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 types)
  • "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

 

 

  

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.

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

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

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 creative template.

name

string

Read-only. The name of the creative template.

media_subtype_id

int

Read-only. The ID of the media subtype assigned to the template. You can use the Media Subtype Service to view all supported media subtypes.

format_id

string

Read-only. The name of the format assigned to the template. You can use the Creative Format Service to view all supported formats.

Frequently Used Creative Templates

For more information, see the Selecting the Correct Template for Your Creative.

Template IDCreative TypeRequirements
1Single URL that points to a piece of html codeYou will need to pass the URL in the media_url field and set an id of 1 in the template object.
2Single URL that points to a piece of Javascript codeYou will need to pass the URL in the media_url field and set an id of 2 in the template object.
5Creative that starts and ends with Javascript components, even if the Javascript code writes HTML.You will need to pass the Javascript code in the content field and set an id of 5 in the template object.
6Creative that starts and ends with HTML components, even if these HTML components are <script> tags.You will need to pass the html code in the content field and set an id of 6 in the template object.

Custom Macros

If the creative template provides default values for a macro, passing the codes and values here is optional. If the template defines a custom macro as required, however, you must pass the code and value for the macro.

Field

Type

Description

code

string

The exact name of the macro, as it is used in the code of the creative template, for example, "BORDER_COLOR".

value

string

The value for the macro. Note that this value must match the type of the macro, as defined in the template. For example, if a macro is of the type "integer", the value must be an integer. The possible macro types are "true/false", "string", "url", "integer", "decimal", and "select_from_list"

See the Adding a creative that uses a custom rendering template example below for further insight.

Custom Request Template

 

Field

Type

Description

id

int

The creative custom request template associated with this creative, if its content_source is set to "mediation". For more information, see the Creative Custom Request Template Service.

timeout_ms

int

If this is a "mediation" creative, it will make at least one HTTP request to an external ad server, which may in turn make one or more additional requests. This is the time beyond which we will not wait any longer for this creative to be populated with content. For more information, see the Creative Custom Request Template Service.

last_modified

timestamp

The date and time at which the custom request template was last modified.

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.

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

Media Assets

 

 The media_assets array of objects contain the following fields:

Field

Type

Description

media_asset_id

int

The unique ID of the creative asset.

creative_field

string

This field denotes what that particular creative asset must be used for. Possible valid values are:

  • null (if asset is VAST or HTML5)
  • media_url
  • flash_backup_url
  • native_icon_img_url
  • native_main_media
  • macro_CODE_FOR_MACRO - this is dynamically generated based on the macros for the selected template.

For each media_assets array, the following rules apply:

  • Each field value can only be used once per creative. For example, you cannot have two 'flash_backup_url' assets.
  • The value must be one of the valid values.
  • VAST / HTML5 creatives must have one, and only one, asset.
  • All other creatives can have 0 or more media assets.

Example:

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.

 

Native

 

The "native" object contains the following fields. For more information, see Add a native ad creative in the Examples.

FieldTypeDescription
titletextThe title displayed with the native ad.
descriptiontextA short description of the ad's offer to the user.
full_texttextThe full text of the native ad. Much longer than description.
contextstring

The social context where the native ad will appear in the application. This varies depending on the media subtype of the native ad. For example, it may be a string such as "newsfeed".

icon_img_urlstringThe URL of the icon image for the native ad. We don't validate this; you must ensure that the URL resolves to the proper icon image for your native ad type. Will contain a secure URL (HTTPS/SSL) if the auction is secure.
main_mediaarray of objectsThe main content that will appear in the body of the native ad. For now, we only support images and only one image can be associated with a native creative. For more information, see Main Media below.
sponsoredstringThe brand name that the user should associate with this creative.
ctastringThe "call to action" text of the ad, e.g., "Download now".
ratingobjectIf the advertisement is for an app, this will display the app's rating in the relevant app store. Note that the rating is provided by the advertiser. We do not directly pull ratings from app stores.
click_urlstringThe destination URL that will open if the user clicks the ad. Note that this URL could launch an app on a device.
click_fallback_urlstringA fallback web URL to be used if the deep link provided in the click_url is not supported on the device. For mobile inventory only.
custom_key_valuesarray of objectsSome sellers allow the buyer to pass a list of custom key/value pairs. For more information, see Custom Key Values below.
Main Media
NameTypeDescription
widthintThe width of the main native ad media.
heightintThe height of the main native ad media.
media_urlstringThe URL from which the media can be downloaded.
media_url_securestringLike media_url, but with SSL.

There can only be one main_media object associated with a native creative.

Custom Key Values
NameTypeDescription
custom_keystringA seller-defined key string.
custom_valuestringA seller-defined value string.
Click Trackers
NameTypeDescription
click_tracker_urlstringA third-party click tracking URL.
Impression Trackers
NameTypeDescription
impression_tracker_urlstringA third-party impression tracking URL.
impression_tracker_url_securestringA third-party impression tracking URL (that uses SSL)

Native Attribute

The native_attribute object contains the following fields. For more information, see Adding a native creative - new in  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 objectsA list of third-party impression tracking URLs. For more information, see Javascript Trackers below.
data_assetsarray 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.
privacy_urlstringIf 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.

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

url_secure

string

(optional) A secure third-party tracking URL.


Image Trackers
Name
Type
Description
url stringA third-party impression tracking URL.
url_secure stringA third-party impression tracking URL (that uses SSL)
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
image_typestring

The format of the image. Possible values include:

  • icon_image
  • main_image
media_asset_idint

The id of the media asset. Required for hosted native creatives.

if media_asset_id can be retrieved, the creative_asset_image object will be populated automatically.

creative_asset_imageobject

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

Creative Asset Image
FieldTypeDescription
urlstringThe landing page url of the image.
url_securestringThe secure landing page url of the image.
widthintThe width of the image. Value must be > 0
heightintThe height of the image. Value must be > 0

Pixels

You use this array to add AppNexus-approved and custom pixels to a creative. You can add up to five pixels for 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.

When you make a PUT call to update the pixels array, the array is completely overwritten with the information in the JSON-formatted file. Therefore, if the array already includes pixels, be sure to include those pixels in the JSON-formatted file as well.

Field

Type

Description

id

int

Read-only. The AppNexus-assigned ID of the pixel array. You will associate pixels via the pixel_template_id, content, or URL fields listed below.

  

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.

secure_content

string (255)

If the pixel format is "raw-js", the HTML or JavaScript content to serve with the creative on a secure (HTTPS) ad call.

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.

secure_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 on a secure (HTTPS) call.

Pop Values

The pop_values fields are deprecated, and ignored/not used by our systems.

These fields should be included in a "pop_values" array within the creative JSON. Please see below for an example.

Field

Type (Length)

Description

Default

Required On

pop_window_maximize

Boolean

If true, the publisher's tag should maximize the window. Only relevant for creatives with format "url-html" and "url-js". If pop_window_maximize is set to true, then neither "height" nor "width" should be set on the creative.

false

 

pop_is_tag_initiated

Boolean

If true, the creative's tag will initiate the pop. If false, then the AppNexus Impression Bus will initiate the pop.

false

 

pop_window_title

string (255)

The title of the popped window. Only applies to pops with pop_is_tag_initiated set to false. Not guaranteed to be supported in all browsers

Network name

 

pop_statusbar

Boolean

If true, a status bar is shown in the popped window. Only applies to pops with pop_is_tag_initiated set to false. Not guaranteed to be supported in all browsers.

true

 

pop_menubar

Boolean

If true, a menu bar is shown in the popped window. Only applies to pops with pop_is_tag_initiated set to false. Not guaranteed to be supported in all browsers.

true

 

pop_resizable

Boolean

If true, the popped window is resizable. Only applies to pops with pop_is_tag_initiated set to false. Not guaranteed to be supported in all browsers.

true

 

pop_scrollbars

Boolean

If true, scroll bars are shown in the popped window. Only applies to pops with pop_is_tag_initiated set to false. Not guaranteed to be supported in all browsers.

true

 

pop_toolbar

Boolean

If true, a toolbar is shown in the popped window. Only applies to pops with pop_is_tag_initiated set to false. Not guaranteed to be supported in all browsers

true

 

pop_addressbar

Boolean

If true, an address bar is shown in the popped window. Only applies to pops with pop_is_tag_initiated set to false. Not guaranteed to be supported in all browsers

true

 

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. 

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.

Third-party Pixels

The thirdparty_pixels array contains the fields in the table below. These fields, except for id, are read-only. Use this service to update the id of a third-party pixel or attach third-party pixels to individual creatives.

Field
Type
Description
Required on
idintThe pixel's ID.PUT
namestringRead-only. The full name of the pixel. 
activeBooleanRead-only. The current status of the pixel (true = active). 
audit_statusstringRead-only. Audit status of the pixel. 
To update or create a third-party pixel and/or attach third-party pixels to all creatives owned by the advertiser or network member, use the Third-party Pixel service.

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

Stats

The  stats  object has been deprecated (as of October 17, 2016). Use the  Report Service  to obtain statistical information instead.

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.

Creative Macros

AppNexus has predefined some macros that can be used within the creative's media_url, content, click_url, and pixel_url fields. For a complete list, see Creative Macros.

Click Tracking Example:

Examples

Adding a banner image creative (hosted)
Add a mobile banner image creative (hosted)
Adding a banner flash creative (hosted)
Adding a banner flash creative (third-party URL)
Adding a MediaMind expandable creative (third-party URL)
Adding a Pointroll expandable creative (third-party HTML tag)
Adding a popup image creative (third-party URL)
Adding a popunder image creative (third-party URL)
Adding an in-banner video (third-party video file)
Adding an in-banner video (third-party XML file)
Adding a creative that uses a custom rendering template
Adding a secure creative
Submitting a creative for priority audit
Canceling a creative audit
Viewing audit stats for all creatives
Adding an AppNexus-approved pixel to a creative
Adding a custom pixel to a creative
Adding a third-party pixel to a creative
Adding a creative (third-party HTML tag)
Adding a native ad creative

Adding a native creative - new

Related Topics