Partager via

Creative HTML service

  • Article

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

Note

media_asset_id is required in order to upload a hosted HTML5 creative. For more details, see the Examples section below.

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 below.
  • For more details on auditing, see Creative Standards and Auditing.

REST API

HTTP Method Endpoint Description
POST https://api.appnexus.com/creative-html?advertiser_id=ADVERTISER_ID
(creative JSON)		 Add a new hosted HTML5 creative to one of your advertisers.
POST https://api.appnexus.com/creative-html?publisher_id=PUBLISHER_ID
(creative JSON)		 Add a new HTML5 creative to one of your publishers.
PUT - https://api.appnexus.com/creative-html?id=CREATIVE_ID&advertiser_id=ADVERTISER_ID
- https://api.appnexus.com/creative-html?id=CREATIVE_ID&publisher_id=PUBLISHER_ID		 Modify an existing hosted HTML5 creative.
GET https://api.appnexus.com/creative-html View all hosted HTML5 creatives.
GET - https://api.appnexus.com/creative-html?advertiser_id=ADVERTISER_ID
- https://api.appnexus.com/creative-html?advertiser_code=ADVERTISER_CODE
- https://api.appnexus.com/creative-html?publisher_id=PUBLISHER_ID
- https://api.appnexus.com/creative-html?publisher_code=PUBLISHER_CODE		 View all hosted HTML5 creatives for an advertiser or publisher.

Note:
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 below.
GET - https://api.appnexus.com/creative-html?id=CREATIVE_ID
- https://api.appnexus.com/creative-html?code=CREATIVE_CODE		 View a specific creative.
GET https://api.appnexus.com/creative-html?id=1,2,3 View multiple creatives by ID using a comma-separated list.
GET https://api.appnexus.com/creative-html?audit_stats=true View creative audit stats.

Note:
The response tells you the number of creatives with each AppNexus, Microsoft, and Google audit status. For the response format, see Examples below.
DELETE - https://api.appnexus.com/creative-html?id=CREATIVE_ID&advertiser_id=ADVERTISER_ID
- https://api.appnexus.com/creative-html?id=CREATIVE_ID&publisher_id=PUBLISHER_ID		 Delete a creative.

Note:
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 Description
id int The internal ID associated with the creative.
Default: Auto-generated number.
Required On: PUT, in query string.
code string (100) The custom code for the creative.
code2 string (100) The additional custom code for the creative. Each object in the line_items.
name string (100) The name of the creative.
type enum The type of creative. Possible values:
"html"

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

Read Only.
height int Size of the creative in height.
width int Size of the creative in width.
advertiser_id int The ID of the advertiser to which the creative is attached.
Required On: 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.
Required On: 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 The state of the creative. Possible values: "active" or "inactive".
Read Only.
status object The status of the creative describing if the creative is ready to serve. For more details, see Status below.
click_track_result enum The result of the click track test, a feature only available in the Console user interface. Possible values: "not_tested", "passed", or "failed".
Default: "not_tested"
campaigns array of objects The list of campaigns to which the creative is associated. For more details, see Campaigns below.

Note:
This field will only be returned if an advertiser_id is specified in the querystring.
template object The creative template (example: 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:
- HTML Multi Asset - Standard: 8606
- HTML Multi Asset - Interstitial: 8607
- HTML Multi Asset - Expandable: 8608
Required On: POST
For more details, see Examples below.
media_url string (1000) The URL of the creative - can be flash, HTML, javascript (see format).
Required On: POST, if not using content.
This field only applies to third party creatives. Leave blank for HTML5 creatives.
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.
This field only applies to third party creatives. Leave blank for HTML5 creatives.
click_url string (2000) The (optional) landing page URL for non-3rd party image and flash creatives.

Note:
This value must begin with "http://" or "https://"
Required On: 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".

Note:
- 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 below.
Default: "pending"
audit_feedback string The creative auditing team can pass messages about a creative in this field.
Read Only.
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.

Note:
- 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.
Default: 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"

Default: "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.
Default: false
google_audit_status enum Deprecated. See adx_audit instead.
google_audit_feedback string Deprecated. 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.
Default: false
is_expired Boolean 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".
Default: false
Read Only.
is_prohibited Boolean If Sherlock flags the creative for having malware or loading blocked domains, this is set true to prevent the creative from serving.
Default: false
Read Only.
is_hosted Boolean If true, the creative is hosted by AppNexus.
Read Only.
lifetime_budget double The lifetime budget in dollars.

Note:
To include this field in a GET response, pass attributes=1 in the query string.
Default: 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.
Default: 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.
Default: 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.
Default: 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.
Default: true
allow_safety_pacing Boolean If true, spend per minute is limited to a maximum of 1% of the lifetime budget and 5% of the daily budget.
Admin Only.
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_items array of objects The line items that are associated with the creative. For more details, see Line Items below.
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.
Default: 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 and the example below.
created_on timestamp The date and time when this creative was created. If it was created before January 2010, this will be zero.
Read Only.
last_modified timestamp The date and time when the creative was last modified.
Read Only.
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 and the example below.
adservers array of objects 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 and the example below.
Read Only.
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 and the example below.
language object The language of the creative. To retrieve a full list of languages, see the Language Service and the example below.
brand object The brand of the company advertising the creative and the category associated with the brand. For more details, see Brand below.
Read Only.
sla int Creatives set to "0" will be submitted for audit with a standard SLA.

Caution: 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 The estimate time of completion for a priority audit.
Read Only.
currency string The code that defines the advertiser's primary currency (for example, USD). For more details about the currency types available, see Currency Service.
Default: Member's default currency.
Read Only.
first_run timestamp 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.
Read Only.
last_run timestamp 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.
Read Only.
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.
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.
adx_audit object 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.
Read Only.
member_id int The ID of the member that owns the creative.
custom_macros array of objects HTML5 creatives will have the HTML5_INDEX_FILE custom macro which is set by the API.
media_assets array 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.
See example.

Note:
creative_field should always be null for an HTML5 creative.

segments example

"segments":[
{"id":11111,
"action":"add_on_view"
},
{"id":22222,
"action":"add_on_click"
}
]

categories example

"categories":[{"id":"13","name":"Online Games"}]

adservers example

"adservers":[{"id":"1","use_type":"adserver","name":"24/7 Real Media"}]

technical_attributes example

"technical_attributes":[{"id":"1","name":"Image"}]

language example

"language":{"id":"1","name":"English"}

media_assets example

"media_assets":[
{
"media_asset_id":22,
"creative_field":null
}
]

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
name string The name of the line item.
Read Only.
state enum The state of the creative. Possible values: "active" or "inactive".
Read Only.
id int The ID of the line item. Either "id" or "code" is required when updating line item association.
Required On: PUT
code string The custom code for the line item. Either "id" or "code" is required when updating line item association.
Required On: 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
id int The ID of the campaign. Either "id" or "code" is required when updating campaign association.
Required On: PUT
campaign_id int The ID of the campaign.
creative_id int The ID of the creative.
name string The name of the campaign.
Read Only.
state enum The state of the campaign. Possible values: "active", "inactive", or "parent_inactive".
Read Only.
code string The custom code for the campaign. Either "id" or "code" is required when updating line item association.
Required On: PUT

Status

Name Type Description
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"
Default: true
hosted_assets_association_complete boolean/null Status of the creative uploaded by AppNexus' internal systems. Possible values: "true" or "false" for hosted creatives and "null" for third-party creatives.
Read Only.

Competitive brands

Note

For more information about brands, see the Brand Service.

Name Type Description
id int The ID of the brand.
Default: N/A
Required On: N/A
name string The name of the brand.
Default: N/A
Required On: N/A

Competitive categories

Note

For more information about categories, see the Category Service.

Name Type Description
id int The ID of the category.
Default: N/A
Required On: N/A
name string The name of the category.
Default: N/A
Required On: N/A

Segments

These fields will be included in the Segments array:

Field Type Description
id int The ID of the segment.
Required On: 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".
Required On: POST, PUT
name string The segment's name.

Brand

The brand object contains the following fields.

Note

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 The ID of the brand of the company advertising the creative.
Read Only.
name string The name of the brand of the company advertising the creative.
Read Only.
category_id int The ID of the category associated with the brand.
Read Only.
category_name string The name of the category associated with the brand.

Note: The category_name field is returned only when you passshow_category_name=true in the query string of your call.
Read Only.

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

Pass never_run=true in the query string.

curl -b cookies -c cookies 'https://api.appnexus.com/creative-html?advertiser_id=100&flight_info=true&never_run=true'

Note

You can use never_run=true in combination with other filters, but note that it will always be an OR relationship. For example, if you pass both never_run=true and min_first_run=2012-01-01 00:00:00 in the query string, you will be looking for creatives that have never served OR line items that first served on or after 2012-01-01.

Retrieve only creatives that first served on or after a specific date

Pass min_first_run=YYYY-MM-DD HH:MM:SS in the query string.

curl -b cookies -c cookies 'https://api.appnexus.com/creative-html?advertiser_id=100&flight_info=true&min_first_run=2012-01-01 00:00:00'

Retrieve only creatives that first served on or before a specific date

Pass max_first_run=YYYY-MM-DD HH:MM:SS in the query string.

curl -b cookies -c cookies 'https://api.appnexus.com/creative-html?advertiser_id=100&flight_info=true&max_first_run=2012-08-01 00:00:00'

Retrieve only creatives first served within a specific date range

Pass min_first_run=YYYY-MM-DD HH:MM:SS&max_first_run=YYYY-MM-DD HH:MM:SS in the query string.

curl -b cookies -c cookies 'https://api.appnexus.com/creative-html?advertiser_id=100&flight_info=true&min_first_run=2012-01-01 00:00:00&max_first_run=2012-08-01 00:00:00'

Retrieve only creatives that last served on or after a specific date

Pass min_last_run=YYYY-MM-DD HH:MM:SS in the query string.

curl -b cookies -c cookies 'https://api.appnexus.com/creative-html?advertiser_id=100&flight_info=true&min_last_run=2012-01-01 00:00:00'

Retrieve only creatives that last served on or before a specific date

Pass max_last_run=YYYY-MM-DD HH:MM:SS in the query string.

curl -b cookies -c cookies 'https://api.appnexus.com/creative-html?advertiser_id=100&flight_info=true&max_last_run=2012-08-01 00:00:00'

Retrieve only creatives that last served within a specific date range

Pass min_last_run=YYYY-MM-DD HH:MM:SS&max_last_run=YYYY-MM-DD HH:MM:SS in the query string.

curl -b cookies -c cookies 'https://api.appnexus.com/creative-html?advertiser_id=100&flight_info=true&min_last_run=2012-01-01 00:00:00&max_last_run=2012-08-01 00:00:00'

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_asset

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 an HTML5 creative

When uploading a creative for hosting with AppNexus:

Step 1: Upload the asset to the creative upload service.

curl -X POST -H "Authorization: hbapi:139072:5761726637ada:nym2" --form "type=html" --form "file=@./AppNexus_30_1280_720_2500k.zip" "https://api.appnexus.com/creative-upload?member_id=123"

The media_asset_id is returned.

{
    "response": 
        "status": "OK",
        "count": 0,
        "start_element": 0,
        "num_elements": 0,
        "media-asset": [
            {
                "id": 54621,
                "parent_media_asset_id": null,
                "member_id": 123,
                "advertiser_id": null,
                "publisher_id": null,
                "file_name": "AppNexus_30_1280_720_2500k.zip",
                "size_in_bytes": 8358845,
                "cdn_uploaded_on": null,
                "cdn_url": null,
                "cdn_secure_url": null,
                "created_on": "2016-06-15 15:33:17",
                "last_modified": "2016-06-15 15:33:17",
                "deleted": false,
                "media_asset_status": [
                    {
                        "id": 54621,
                        "media_asset_id": 54621,
                        "error_message": null,
                        "local_path": "03/36/2e/66/03362e66-674a-41b3-9477-fcd979cdbf0b/03362e66-674a-41b3-9477-fcd979cdbf0b.zip",
                        "cdn_upload_attempt_count": 0,
                        "created_on": "2016-06-15 15:33:17",
                        "last_modified": "2016-06-15 15:33:17",
                        "deleted": false,
                        "status": "on_shared_storage"
                    }
                ],
                "media_asset_video": null,
                "media_asset_html5": null,
                "asset_type": "html",
                "mime_type": "zip" 
            }
        ]
    }

Step 2: Use the media_asset_id to upload the creative.

$ cat creative_html

{
    "creative-html": {
        "name": "upload_hosted_html5.zip",
        "template":{
            "id":8606
            },
        "media_assets": 
           [{
               "media_asset_id": 54621
            }
        ],
        "width":120
        "height":600
        "click_url": "https://appnexus.com",
        "advertiser_id": 164979,
        "segments": null,
        "allow_audit": true,
        "is_self_audited": false,
        "sla": 0
    }
}

{
    "response": {
        "status": "OK",
        "count": 1,
        "id": 12345678,
        "start_element": 0,
        "num_elements": 100,
        "creative-html": {
            "name": "upload_hosted_html5.zip",
            "brand_id": 1,
            "media_url": "http://appnexus.com",
            "id": 12345678,
            ...
            "track_clicks": true,
            "audit_status": "pending",
            ...
            "media_url_secure": "https://appnexus.com",
            ...
            "is_hosted": true,
            ...
            "language": {
                "id": 1,
                "name": "English"
            },
            ...
            },
            "template": {
                "id": 8606,
                "name": "HTML Multi Asset - Standard",
            },
            ...
            "media_assets": [
                {
                    "media_asset_id": 54621
                }
            ],
            ...
            "currency": "USD",
            "type": "html"
        },
        ...
    }
    }