Bidders - Creative service

Artigo
02/26/2024

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

Note

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. Creatives will be automatically reactivated 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.

REST API

HTTP method	End point	Description
DELETE	https://api.adnxs.com/creative/MEMBER_ID?id=CREATIVE_ID	Delete a creative.
GET	https://api.adnxs.com/creative/MEMBER_ID https://api.adnxs.com/creative/MEMBER_ID?num_elements=X&start_element=Y&min_last_activity=Z&sort=id.asc	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`.
GET	https://api.adnxs.com/creative/MEMBER_ID/CREATIVE_ID https://api.adnxs.com/creative?member_id=MEMBER_ID&id=CREATIVE_ID1,CREATIVE_ID2,CREATIVE_ID3 https://api.adnxs.com/creative?member_id=MEMBER_ID&code=CODE	View a specific creative.
POST	https://api.adnxs.com/creative/MEMBER_ID (creative JSON)	Add a new creative.
PUT	https://api.adnxs.com/creative-macro-check?include_tests=1 (replace_pattern_in_content_url JSON)	Modify an existing creative.
PUT	https://api.adnxs.com/creative/MEMBER_ID/CREATIVE_ID (creative JSON) https://api.adnxs.com/creative/MEMBER_ID?code=CODE

JSON structure

Field	Set By	Required	Type	Description
`active`	internal	no	Boolean	Read-only. The current state of the creative.
`added_by_bidder`	internal	no	int	The ID of the bidder that added this creative.
`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.
`adx_audit`	internal	no	object	Read 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.
`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. Default: false
`audit_feedback`	internal	no	string	If the creative has failed the creative audit for Xandr, this includes the audit team's reasoning.
`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 Xandr 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."
`backup_upload_status`				Deprecated.
`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. Tip: To return `category_name` as well, pass `show_category_name=true` in the query string of your call.
`brand_id`	client	no	int	The id of the brand of the company advertising the creative.
`campaign`	client	no	string(50)	The (optional) name of the campaign for this creative - used for reporting/management purposes.
`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.
`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" Default: 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.
`click_trackers`				Deprecated.
`click_url`	client	yes (When creative.format is image)	string(1000)	Does not work for Bidder clients.
`code`	client	no	string (100)	The member code of the creative; used for external ID mapping purposes only (see Incoming Bid Response from Bidders).
`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.
`created_on`	internal	no	timestamp	The timestamp when the creative was originally uploaded to Xandr
`creative_upload_status`				Deprecated.
`description`		no	string (400)	Optional description associated with the creative.
`filter`				Deprecated.
`flash_backup_url`		no	string	Backup for flash format creatives, which will be served if the user's browser doesn't support flash.
`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 Xandr 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.
`format`				Deprecated.
`height`	client	yes	int	The height of the creative in pixels.
`id`	internal	yes (on update)	int	The ID of the creative; used for internal matching purposes only.
`impression_trackers`				Deprecated.
`is_expired`	internal	no	boolean	Indicates whether the creative has been served or modified in the past 15 days.
`is_prohibited`	internal	no	boolean	True if the Xandr 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 Xandr 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
`last_activity`	internal	no	timestamp	The date and time when the creative was last modified. Timezone is UTC. Read Only.
`last_checked`	internal	no	timestamp	The timestamp that the URL was last checked for existence.
`media_subtypes`				Deprecated.
`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.
`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.
`native`				Deprecated.
`native_attribute`	client	yes (required for native ads with template 39461)	object	This is the native object that contains elements required for native ads. For more information, see the description of the Native Attribute object below.
`no_iframes`				Deprecated.
`no_iframes`				Deprecated.
`not_found`	internal	no	boolean	How many times the URL has failed to load. After a certain number of checks, the creative will deactivate.
`original_content`	internal	no	string	This field is for reference only. When a tag with third party content is uploaded to Xandr, the original content uploaded with the creative will be stored in this field. Default: 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.
`passed_sherlock_audit`	internal	no	boolean	Indicates whether the creative has been recently checked by the Xandr automated creative auditing system ("Sherlock").
`pixel_type`				Deprecated. Please use the `pixels` field instead.
`pixel_url`				Deprecated. Please use the `pixels` field instead.
`pixel_url_secure`				Deprecated. Please use the `pixels` field instead.
`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.
`placement`	client	no	string(50)	The (optional) name of the placement for this creative - used for reporting/management purposes.
`pop_values`				Deprecated.
`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: `"segments": [ { "id": 11111, "action": "add_on_view" }, { "id": 22222, "action": "add_on_click" } ]`
`size_in_bytes`	internal	no	int	The size of the media file in bytes.
`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. Note: When requesting a standard audit, the api will populate this field with a value of null.
`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". Default: 'disabled'
`state`	internal	no	enum	The state of the creative. Possible values are "active" or "inactive"
`status`	client	no	object	The status of the creative describing if the creative is ready to serve. See Status below for details.
`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.
`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. Warning: 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 Default: `POST`
`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
`text_title`	client	yes, only if format is text	string up to 25 characters	The top line of text displayed in a text creative
`track_clicks`				Deprecated.
`track_clicks`				Deprecated.
`video_attribute`	client	no	object	Attributes for third-party in-stream (VAST) video creatives. See Video Attribute below for more details.
`width`	client	yes	int	The width of the creative in pixels.

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

Note

Audio The video attribute object is also used to create audio creatives. The template id for audio is 38745 - Xandr 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
`duration_ms`	double	The duration, in milliseconds, of the in-stream (VAST) video creative. This must be greater than `0`.
`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`.
`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
`elements`	array	Elements of the VAST wrapper.
`secure_url`	string	Secure URL of the VAST document.
`url`	string	URL of the VAST document.

Video attribute wrapper element

The elements array contains the following fields:

At least one element must be specified.

Field	Type	Description
`trackers`	array	VAST event trackers.
`type`	string	Read only. Type of element. Possible value: "linear"
`vast_element_type_id`	int	VAST element ID. Possible value: `1`: linear

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
`event_type`	string	Read only. The type of event corresponding to `vast_event_type_id`.
`is_segment_pixel`	boolean	Defines the pixel as a segment pixel, and ensures the userid for that event is added to segment regardless of device type. Default value = false. Where this is set to true, the url must be configured in the standard format: https://ib.adnxs.com/seg?add=segmentID, otherwise you will receive an error.
`name`	string	The name of the event tracker.
`secure_url`	string	The secure URL of the event tracker.
`url`	string	The URL 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

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.

ID	Format	Name
`1`	url-html	Standard Banner
`2`	url-js	Standard Banner
`3`	flash	Standard Banner
`4`	image	Standard Banner
`5`	raw-js	Standard Banner
`6`	raw-html	Standard Banner
`7`	iframe-html	Standard Banner
`8`	url-xml	In-Banner Video
`9`	url-html	Popup
`10`	url-js	Popup
`11`	flash	Popup
`12`	image	Popup
`13`	raw-js	Popup
`14`	raw-html	Popup
`15`	iframe-html	Popup
`6439`	VAST, VPAID	Standard VAST

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

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	Read-only. Status of the creative uploaded by Xandr's 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 .

Field	Type	Description
`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.
`image_trackers`	array of objects	A list of third-party impression tracking URLs intended to be used with native creatives. For more information, see Image Trackers below.
`javascript_trackers`	array of objects	A list of third-party impression tracking URLs. For more information, see Javascript Trackers below. All OpenRTB and Xandr macros are supported for this field except for ${AUCTION_PRICE} and ${PRICE_PAID}.
`link`	object	URLs associated with the native creative. See Link below for details.
`privacy_url`	string	If support was indicated in the request, URL of a page informing the user about the buyer’s targeting activity. Xandr does not provide a default privacy link.
`video_assets`	array of objects	Attributes of the video assets. See Video Assets for more details.

Note

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
`fallback_url`	string	A backup url if the main deeplink url is not supported.
`trackers`	array of objects	A 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.
`url`	string	The landing page of the native creative. Required On : `POST`,`PUT`

Note

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 wit `https`, the creative will be submitted for secure audit.

Trackers

Name	Type	Description
`url`	string	A third-party impression tracking URL. This should contain your impression tracker.
`url_secure`	string	A third-party impression tracking URL (that uses SSL). This should contain your impression tracker.

Image trackers

Name	Type	Description
`url`	string	A third-party impression tracking URL. This should contain your impression tracker.
`url_secure`	string	A third-party impression tracking URL (that uses SSL). This should contain your impression tracker.

Javascript trackers

Name	Type	Description
`url`	string	A third-party javascript tracking URL.
`url_secure`	string	A third-party javascript tracking URL (that uses SSL)

Data assets

The data_assets object includes the following fields:

Field	Type	Description
`data_type`	string	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
`value`	string	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:

Field	Type	Description
`creative_asset_image`	object	The object containing details of the creative asset. Required for third-party native creatives. See details in Creative Asset Image below.
`image_type`	string	The format of the image. Possible values include: - icon_image - main_image

Creative asset image

Field	Type	Description
`height`	int	The height of the image. Value must be > 0
`url`	string	The url of the image.
`url_secure`	string	The secure url of the image.
`width`	int	The width of the image. Value must be > 0

Video assets

The video_assets object includes the following fields:

Field	Type	Description
`video_creative_id`	int	The Xandr 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 Xandr-approved and custom pixels to a creative.

Xandr-approved pixels are from trusted, commonly-used providers. Most of them do not cause the creative to be resubmitted for audit. To add a Xandr-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 a Xandr-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
`content`	string (255)	If the pixel format is "raw-js", the HTML or JavaScript content to serve with the creative.
`format`	enum	The format of the pixel. Possible values: "raw-js", "url-html", "url-js", or "url-image".
`id`	int	Read-only. The ID of the pixel.
`param_1`	string	For Xandr-approved pixel: The value for the first parameter in the pixel content or URL. To find out how many parameters are required for a Xandr-approved pixel, use the [Pixel Template Service](pixel-template-service .md).
`param_2`	string	For Xandr-approved pixel: The value for the second parameter in the pixel content or URL.
`param_3`	string	For Xandr-approved pixel: The value for the third parameter in the pixel content or URL.
`param_4`	string	For Xandr-approved pixel: The value for the fourth parameter in the pixel content or URL.
`param_5`	string	For Xandr-approved pixel: The value for the fifth parameter in the pixel content or URL.
`pixel_template_id`	int	The ID of the Xandr-approved pixel. You can use the Pixel Template Service to get this ID.
`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
`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
`id`	int	The ID of the segment. Required On: POST, PUT
`name`	string	The segment's name.
`segment_id`	int	The ID of the segment. This field contains the same information as the id field.

Field	Type	Description
`landing_page_url`	string	The landing page URL entered by the Xandr administrator during the audit process. Default: `null`
`thirdparty_campaign_id`	int	Read-only. If the campaign has been synced with a third-party, this is the ID in the third-party system. Default: `null`
`thirdparty_creative_id`	int	Read-only. If the creative has been synced with a third-party such as Yahoo Ad Exchange, this is the ID in the third-party system.If an issue arises with the sync, you can reset `thirdparty_creative_id` to null with the following PUT call: `$ curl -b cookies -c cookies -X PUT -d '{"creative":{}}' 'https://api.adnxs.com/creative/MEMBER_ID/CREATIVE_ID&reset_thirdparty_creative_id'` Default: `null`

Changes that cause Re-Audit

Once a creative has passed Xandr 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 a Xandr-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 Xandr audit.

Examples

Adding a creative

$ cat creative
{
 "creative":
  {     "width" : 300,
        "height" : 250,
        "media_url" : "https://ad.doubleclick.net/adi/ABC.Advertising.com/DEF.40;sz=300x250;click0=",
        "template":{
           "id": 1 
        }
  }
}

$ curl -b cookies -c cookies -X POST -d @creative.json "https://api.adnxs.com/creative/5"
{
  "response": {
    "status": "OK",
    "count": 1,
    "id": 703355,
    "creative": {
      "id": 703355,
      "active": true,
      "member_id": 5,
      "description": null,
      "code": null,
      "code2": null,
      "media_url": "https:\/\/ad.doubleclick.net\/adi\/ABC.Advertising.com\/DEF.40;sz=300x250;click0=",
      "audit_status": "pending",
      "allow_audit": true,
      "size_in_bytes": 0,
      "last_checked": null,
      "not_found": 0,
      "added_by_bidder": null,
      "campaign": null,
      "placement": null,
      "format": null,
      "width": 300,
      "height": 250,
      "click_url": null,
      "landing_page_url": null,
      "flash_click_variable": null,
      "no_iframes": false,
      "content": null,
      "original_content": null,
      "track_clicks": true,
      "audit_feedback": null,
      "created_on": "2013-10-31 21:17:17",
      "flash_backup_url": null,
      "is_self_audited": false,
      "file_name": null,
      "is_prohibited": false,
      "last_activity": "2013-10-31 21:17:17",
      "passed_sherlock_audit": true,
      "is_expired": false,
      "creative_upload_status": null,
      "backup_upload_status": null,
      "filter": null,
      "is_suspicious": false,
      "suspicious_activity_timestamp": null,
      "media_subtypes": [
        "banner"
      ],
      "no_adservers": false,
      "is_blanking": false,
      "is_rotating": false,
      "text_title": null,
      "text_description": null,
      "text_display_url": null,
      "click_action": "click-to-web",
      "click_target": null,
      "ssl_status": "disabled",
      "allow_ssl_audit": false,
      "media_url_secure": null,
      "content_secure": null,
      "original_content_secure": null,
      "flash_backup_url_secure": null,
      "is_hosted": false,
      "content_source": "standard",
      "thirdparty_creative_id": null,
      "thirdparty_campaign_id": null,
      "custom_request_template": null,
      "brand": {
        "id": 1,
        "name": "Unknown",
        "category_id": 8
      },
      "language": {
        "id": 1,
        "name": "English"
      },
      "template": {
        "id": 1
      },
      "segments": null,
      "pixels": null,
      "mobile": null,
      "brand_id": 1,
      "sla": "0",
      "sla_eta": "2013-11-01 11:18:17"
    }
  }
}

View the creative that was added

$ curl -b cookies -c cookies 'https://api.adnxs.com/creative/5/6'
{
   "response":{
        "status":"OK",
        "creative":{
                "id": 6,
                "active": true,
                "member_id": 5,
                "description": null,
                "code": null,
                "brand_id": 43,
                "media_url": "https:\/\/ad.doubleclick.net\/adi\/ABC.Advertising.com\/DEF.40;sz=300x250;click0=",
                "audit_status": "pending",
                "allow_audit": true,
                "size_in_bytes": 18467,
                "last_checked": null,
                "not_found": false,
                "added_by_bidder": 14,
                "campaign": null,
                "placement": null,
                "format": "url-html",
                "width": 300,
                "height": 250,
                "click_url": "",
                "flash_click_variable": null,
                "pixel_url": "",
                "no_iframes": false,
                "content": null,
                "original_content": null,
                "track_clicks": true,
                "pixel_type": "image",
                "audit_feedback": null,
                "created_on": "0000-00-00 00:00:00",
                "flash_backup_url": null,
                                "is_self_audited": false,
                "last_activity": "2008-08-26 05:41:04",
                                "passed_sherlock_audit": true,
                                "is_expired": false,
                                "creative_upload_status": null,
                                "backup_upload_status": null,
                        "filter": null,
                        "is_suspicious": false,
                        "suspicious_activity_timestamp": null,
                        "media_subtypes": [
                                "banner"
                        ],
                        "no_adservers": false,
                        "is_blanking": false,
                        "is_rotating": false,
                        "text_title": null,
                        "text_description": null,
                        "text_display_url": null,
                        "click_action": "click-to-web",
                        "click_target": null,
                        "ssl_status": "disabled",
                        "allow_ssl_audit": false,
                        "media_url_secure": null,
                        "content_secure": null,
                        "original_content_secure": null,
                        "flash_backup_url_secure": null,
                        "is_hosted": false,
                        "content_source": "standard",
                        "thirdparty_creative_id": null,
                        "thirdparty_campaign_id": null,
                        "custom_request_template": null,
                        "brand": {
                                "id": 5,
                                "name": "Adobe",
                                "category_id": 27
                        },
                        "language": {
                                "id": 16,
                                "name": "Norwegian"
                        },
                        "template": {
                                "id": 1
                                },
                        "segments": null,
                        "pixels": null,
                        "mobile": null,
                        "brand_id": 5,
                        "sla": null,
                        "sla_eta": null
                        }
  }
}

Modifying a creative

If you then decide to add a campaign name "Triple Play - October 2008" to the creative for reporting purposes:

$ cat creative_mod
{"creative" : {
        "campaign":"Triple Play - October 2008"
        }
}
$ curl -b cookies -c cookies -X PUT --data-binary @creative_mod 'https://api.adnxs.com/creative/5/6'
{
   "response":{
        "status":"OK",
        "id":6
}}

And then to view the change:

$ curl -b cookies -c cookies 'https://api.adnxs.com/creative/5/6'
{
    "response": {
        "creatives": [
            {
                "id": 6,
                "active": true,
                "member_id": 5,
                "description": null,
                "code": null,
                "brand_id": 43,
                "media_url": "https:\/\/ad.doubleclick.net\/adi\/ABC.Advertising.com\/DEF.40;sz=300x250;click0=",
                "audit_status": "pending",
                "allow_audit": true,
                "size_in_bytes": 18467,
                "last_checked": null,
                "not_found": 0,
                "added_by_bidder": 14,
                "campaign": "Triple Play - October 2008",
                "placement": null,
                "format": "url-html",
                "width": 300,
                "height": 250,
                "click_url": "",
                "flash_click_variable": null,
                "pixel_url": "",
                "no_iframes": false,
                "content": null,
                "original_content": null,
                "track_clicks": true,
                "pixel_type": "image",
                "audit_feedback": null,
                "created_on": "2008-08-26 05:41:04",
                "flash_backup_url": null,
                "last_activity": "2008-09-14 06:20:04"
            }
        ],
        "status": "OK"
    }
}

Submit a creative for audit

If you would like to request an audit for a creative it must be active and have the allow_audit field set to true:

$ cat creative_mod
{"creative" : {
        "audit_status": "pending",
                "allow_audit" : true
        }
}
$ curl -b cookies -c cookies -X PUT --data-binary @creative_mod 'https://api.adnxs.com/creative/5/6'
{
   "response":{
        "status":"OK",
        "id":6
}}

Unexpire a creative and resubmit for audit

If a creative has expired, you can update it with these settings to set the status to "pending" and resubmit the creative for audit. Note that as of November 2017, creatives that have been expired for over one year will be permanently deleted. See "Expired Creative Policy" at the top of this page for more information.

$ cat unexpire_creative
{
    "creative": {
    "audit_status": "pending",
    "allow_audit": true,
    "status": {
        "user_ready": true
        }
    }
}

Submit a mobile creative for audit

This example uses the new mobile object:

$ cat mobile_creative
{
    "creative" : {
        "audit_status": "pending",
        "allow_audit" : true,
        "mobile" : {
                 "alternative_landing_page_url" : "https://..."
        }
    }
}
$ curl -b cookies -c cookies -X PUT --data-binary @creative_mod 'https://api.adnxs.com/creative/5/6'
{
   "response":{
        "status":"OK",
        "id":6
   }
}

Submit a creative for priority audit

If you would like to submit for a priority audit. Set "sla" to 2 (a value of 1 is not currently used). You will be charged a priority audit fee per your contract.

$ cat creative_mod
{"creative" : {
        "audit_status": "pending",
        "sla": 2
        }
}
$ curl -b cookies -c cookies -X PUT --data-binary @creative_mod 'https://api.adnxs.com/creative/5/6'
{
   "response":{
        "status":"OK",
        "id":6
}}

View the estimated audit time for your creative ('sla_eta')

$ curl -b cookies -c cookies 'https://api.adnxs.com/creative/5/6'
{
    "response": {
        "creatives": [
            {
                "id": 6,
                ...
                "audit_status": "pending",
                "sla": 0,
                "sla_eta": "2011-05-21 05:33:06"
            }
        ],
        "status": "OK"
    }
}

Adding a creative (third-party HTML tag)

$ cat creative
{
 "creative":
  { "width" : 300,
    "height" : 250,
    "media_url" : "https://ad.doubleclick.net/adi/ABC.Advertising.com/DEF.40;sz=300x250;click0=",
    "template":{
       "id": 1
    }
  }
}                       
$ curl -b cookies -c cookies -X POST -d @creative.json 'https://api.sand-08.adnxs.net/creative?member_id=1282'   
  
{
    "response":{
        "status":"OK",
        "count":1,
        "start_element":null,
        "num_elements":null,
        "id":816447,
        "creative":{
            "id":816447,
            "active":true,
            "member_id":1282,
            "description":null,
            "code":null,
            "code2":null,
            "media_url":"https:\/\/ad.dblclick.net\/adi\/ABC.Advertising.com\/DEF.40;sz=300x250;click0=",
            "audit_status":"pending",
            "allow_audit":true,
            "size_in_bytes":0,
            "last_checked":null,
            "not_found":0,
            "added_by_bidder":null,
            "campaign":null,
            "placement":null,
            "format":null,
            "width":300,
            "height":250,
            "click_url":null,
            "landing_page_url":null,
            "flash_click_variable":null,
            "no_iframes":false,
            "content":null,
            "original_content":null,
            "track_clicks":true,
            "audit_feedback":null,
            "created_on":"2014-01-24 16:02:31",
            "flash_backup_url":null,
            "is_self_audited":false,
            "file_name":null,
            "is_prohibited":false,
            "last_activity":"2014-01-24 16:02:31",
            "passed_sherlock_audit":true,
            "is_expired":false,
            "creative_upload_status":null,
            "backup_upload_status":null,
            "filter":null,
            "is_suspicious":false,
            "suspicious_activity_timestamp":null,
            "media_subtypes":[
                "banner"
            ],
            "no_adservers":false,
            "is_blanking":false,
            "is_rotating":false,
            "text_title":null,
            "text_description":null,
            "text_display_url":null,
            "click_action":"click-to-web",
            "click_target":null,
            "ssl_status":"disabled",
            "allow_ssl_audit":false,
            "media_url_secure":null,
            "content_secure":null,
            "original_content_secure":null,
            "flash_backup_url_secure":null,
            "is_hosted":false,
            "content_source":"standard",
            "thirdparty_creative_id":null,
            "thirdparty_campaign_id":null,
            "custom_request_template":null,
            "brand":{
                "id":1,
                "name":"Unknown",
                "category_id":8
            },
            "language":{
                "id":1,
                "name":"English"
            },
            "template":{
                "id":1
            },
            "segments":null,
            "pixels":null,
            "mobile":null,
            "brand_id":1,
            "sla":"0",
            "sla_eta":"2014-01-27 00:03:31"
        }

Adding an iframe-html creative

The creative service allows for a number of different types of creatives to be created. For example, to create a creative using the format "iframe-html", you would upload the raw html that will be embedded in an iframe in the page serving the ad.

$ cat iframe-html-creative
{
   "creative" : {
        "content":"<script type=\"text/javascript\" language=\"javascript\">
                   var sample_var = 350;
                   </script>
                   <script type=\"text/javascript\" language=\"javascript\" src=\"https://sample_source.com/sample_id?ord=${CACHEBUSTER}\"</script>",
        "width":"300",
        "height":"250",
        "format":"iframe-html",
        "brand_id" : 43
        }
}
$ curl -b cookies -c cookies --data-binary @iframe-html-creative 'https://api.adnxs.com/creative/5'
{
   "response":{
        "status":"OK",
        "id":7
}}

Adding a Xandr-approved pixel to a creative

This example walks you through the process of adding the Xandr-approved Evidon AdChoices Icon pixel to a creative.

First, you need to find out the pixel_template_id and the number of parameters you must define for the pixel. You use the Pixel Template Service to get this information.

$ curl -b cookies -c cookies 'https://api.adnxs.com/pixel-template'
{
    "response": {
        "status": "OK",
        "count": 3,
        "start_element": 0,
        "num_elements": 100,
        "pixel-templates": [
            {
                "id": 1,
                "name": "Evidon AdChoices Icon",
                "format": "raw-js",
                "content": "(function() {document.write('<sc'+'ript type=\"text/javascript\"' + ((\"https:\"
                 == document.location.protocol) ? \"https://c.betrad.com\" : \"https://c.betrad.com\") +
                 '/surly.js?;ad_wxh=${CREATIVE_SIZE};coid=${P1};nid=${P2};${P3}\"></scr'+'ipt>');}());",
                "num_required_params": 2,
                "require_reaudit": false
            },
            {
                "id": 2,
                "name": "Brilig Impression Tracker",
                "format": "url-image",
                "num_required_params": 1,
                "require_reaudit": false,
                "url": "https://p.brilig.com/contact/bct?pid=${P1}&_ct=pixel&adid=${CP_ID}&action=1"
            },
            ...
        ],
        "dbg_info": {
            ...
        }
    }
}

The Evidon AdChoices Icon pixel is the first in the response. You note that id is 1. You also note that num_required_params is 2. This means that, when adding the pixel to your creative, you must provide values for {P1} and {P2} in the pixel content.

Then you create the JSON-formatted file for adding the pixel to the creative. In the file, you set pixel_template_id to 2, and you set param_1 and param_2 to the values for {P1} and {P2} in the pixel content.

Note

The pixels array will be completely overwritten with the information in this file. Therefore, if the creative already includes any pixels, be sure to specify them in the file as well.

$ cat creative_update
{
    "creative": {
        "pixels": [
            {
                "pixel_template_id": 1,
                "param_1":"12",
                "param_2":"34"
            }
        ]
    }
}

Finally, you make a PUT call to update the creative. The pixels array in the response then shows that the pixel has been added. The two parameters are defined and have been populated in the pixel content. Note that, because the Evidon AdChoices Icon pixel does not cause the creative to require re-auditing, audit_status has not be reverted to "pending".

$ curl -b cookies -c cookies -X PUT -d @creative_update 'https://api.adnxs.com/creative/3/503577'
{
    "response": {
        "status": "OK",
        "count": 1,
        "id": "503577",
        "start_element": 0,
        "num_elements": 100,
        "creative": {
            "name": null,
            "brand_id": 1,
            "media_url": "https://creative.com/300x250",
            "id": 503577,
            "code": null,
            "code2": null,
            "state": "active",
            "click_track_result": "not_tested",
            "member_id": 3,
            ...
            "audit_status": "audited",
            ...
            "pixels": [
                {
                    "id": 163,
                    "pixel_template_id": 1,
                    "param_1": "12",
                    "param_2": "34",
                    "param_3": null,
                    "param_4": null,
                    "param_5": null,
                    "format": "url-image",
                    "content": "(function() {document.write('<sc'+'ript type=\"text/javascript\"' +
                     ((\"https:\" == document.location.protocol) ? \"https://c.betrad.com\" :
                     \"https://c.betrad.com\") + '/surly.js?;ad_wxh=${CREATIVE_SIZE};coid=12;nid=34;
                     \"></scr'+'ipt>');}());"
                }
            ],
            ...
        },
        "dbg_info": {
            ...
        }
    }
}

Adding a custom pixel to a creative

In this example, the PUT request adds a custom url-js pixel to creative 503577. In the JSON-formatted file, the format is set to "url-js", and the url is set to the location of the JavaScript that you want to serve with the creative. Note in the response that audit_status is "pending"; this is because adding a custom pixel to a creative causes the creative to be resubmitted for audit.

Note

The pixels array will be completely overwritten with the information in this file. Therefore, if the creative already includes any pixels, be sure to specify them in the file as well.

$ cat creative_update
{
    "creative": {
        "pixels": [
            {
                "format": "url-js",
                "url":"https://50.16.221.228/render_js?cb=${CACHEBUSTER}&uid=${USER_ID}&ref=${REFERER_URL}
                 &campaign_id=147"
            }
        ]
    }
}
$ curl -b cookies -c cookies -X PUT -d @creative_update 'https://api.adnxs.com/creative/3/503577'
{
    "response": {
        "status": "OK",
        "count": 1,
        "id": "503577",
        "start_element": 0,
        "num_elements": 100,
        "creative": {
            "name": null,
            "brand_id": 1,
            "media_url": "https://creative.com/300x250",
            "id": 503577,
            "code": null,
            "code2": null,
            "state": "active",
            "click_track_result": "not_tested",
            "member_id": 3,
            ...
            "audit_status": "pending",
            ...
            "pixels": [
                {
                    "id": 196,
                    "pixel_template_id": null,
                    "param_1": null,
                    "param_2": null,
                    "param_3": null,
                    "param_4": null,
                    "param_5": null,
                    "format": "url-js",
                    "url": "https://50.16.221.228/render_js?cb=${CACHEBUSTER}&uid=${USER_ID}
                     &ref=${REFERER_URL}&campaign_id=147"
                }
            ],
            ...
        },
        "dbg_info": {
            ...
        }
    }
}

Add a video creative with video attribute object and wrapper

{
    "creative": {
        "id": 145,
        ...
        "template_id": 6439,
        "video_attribute": {
            "is_skippable": true,
            "duration_ms": 21000,
                        "wrapper": {
                "url": "http://www.doubleclick.net/...",
                "secure_url": "https://www.doubleclick.net/...",
                "elements": [
                    {
                                                "vast_element_type_id": 1,
                        "name": "linear",
                        "trackers": [
                            {
                                                                "name": "startTracker",
                                "vast_event_type_id": 2,
                                "url": "http://tracker.com/...",
                                "secure_url": "https://tracker.com/...",
                                                                "event_type": "start"
                            },
                                                        {
                                                                "name": "completionTracker",
                                "vast_event_type_id": 8,
                                "url": "http://tracker.com/...",
                                "secure_url": "https://tracker.com/...",
                                                                "event_type": "completion"
                            }
                        ]
                    }
                ]
            }
        }
    }
}

Adding a native creative

When adding a native creative, use template ID 39461.

cat native
{
        "creative": {
                "description": "native_test",
                "brand_id": 1,
                "media_url": "https://mediaurl.com",
                "code": "test",
                "code2": null,
                "member_id": 4,
                "state": "active",
                "template": {
                        "id": 39461
                },
                "native_attribute": {
                        "link": {
                                "url": "https://url.com",
                                "fallback_url": "https://fallback.com",
                                "trackers": [{
                                        "url": "http://url.com",
                                        "url_secure": "https://secureurl.com"
                                }]
                        },
                        "data_assets": [{
                                "data_type": "sponsored_by",
                                "value": "a value"
                        }, {
                                "data_type": "rating",
                                "value": "8"
                        }],
                        "image_assets": [{
                                "image_type": "icon_image",
                                "creative_asset_image": {
                                        "url": "http://url.com",
                                        "url_secure": "https://secureurl.com",
                                        "height": 1,
                                        "width": 1
                                }
                        }],
                        "image_trackers": [{
                                "url": "http://url.com",
                                "url_secure": "https://secureurl.com"
                        }],
                        "javascript_trackers": [{
                                "url": "http://url.com",
                                "url_secure": "https://secureurl.com"
                        }]
                },
                "thirdparty_viewability_providers": null,
                "status": {
                        "user_ready": true
                },
                "sla_eta": null
        }
}
$ curl -b cookies -c cookies -X POST -s @native 'https://api.adnxs.com/creative/4'
{
        "response": {
                "status": "OK",
                "count": 1,
                "id": 411,
                "start_element": 0,
                "num_elements": 100,
                "dbg_info": {
                        ...
                },
                "creative": {
                        "description": "native_test",
                        "brand_id": 1,
                        "media_url": "https://mediaurl.com",
                        "id": 411,
                        "code": "test",
                        "code2": null,
                        "member_id": 4,
                        "state": "active",
                        "click_track_result": "not_tested",
                        "format": "url-file",
                        "width": null,
                        "height": null,
                        "click_url": null,
                        "flash_click_variable": null,
                        "no_iframes": false,
                        "content": null,
                        "original_content": null,
                        "file_name": null,
                        "track_clicks": true,
                        "audit_status": "pending",
                        "macros": null,
                        "profile_id": null,
                        "audit_feedback": null,
                        "is_prohibited": false,
                        "is_suspicious": false,
                        "created_on": "2017-03-09 21:54:11",
                        "flash_backup_url": null,
                        "last_modified": "2017-03-09 21:54:11",
                        "is_control": false,
                        "allow_audit": true,
                        "is_expired": false,
                        "creative_upload_status": null,
                        "backup_upload_status": null,
                        "use_dynamic_click_url": false,
                        "media_subtypes": [
                                "popunder",
                                "popup",
                                "banner"
                        ],
                        "size_in_bytes": 0,
                        "is_self_audited": false,
                        "no_adservers": false,
                        "text_title": null,
                        "text_description": null,
                        "text_display_url": null,
                        "click_action": "click-to-web",
                        "click_target": null,
                        "ssl_status": "pending",
                        "allow_ssl_audit": true,
                        "media_url_secure": "https://MEDIAURL.appnexus.com",
                        "content_secure": "document.write(\\\"\\\")",
                        "original_content_secure": null,
                        "flash_backup_url_secure": null,
                        "is_hosted": false,
                        "content_source": "standard",
                        "lifetime_budget": null,
                        "lifetime_budget_imps": null,
                        "daily_budget": null,
                        "daily_budget_imps": null,
                        "enable_pacing": null,
                        "allow_safety_pacing": null,
                        "landing_page_url": null,
                        "thirdparty_creative_id": null,
                        "thirdparty_campaign_id": null,
                        "facebook_audit_status": null,
                        "facebook_audit_feedback": null,
                        "custom_request_template": null,
                        "language": {
                                "id": 1,
                                "name": "English"
                        },
                        "brand": {
                                "id": 1,
                                "name": "Unknown",
                                "category_id": null
                        },
                        "template": {
                                "id": 329,
                                "name": "native ad",
                                "media_subtype_id": 17,
                                "format_id": 11
                        },
                        "ios_ssl_audit": null,
                        "adx_audit": null,
                        "custom_macros": null,
                        "segments": null,
                        "folder": null,
                        "campaigns": null,
                        "line_items": null,
                        "competitive_brands": null,
                        "competitive_categories": null,
                        "pixels": null,
                        "mobile": null,
                        "video_attribute": null,
                        "media_assets": null,
                        "sla": null,
                        "thirdparty_pixels": null,
                        "native": null,
                        "native_attribute": {
                                "link": {
                                        "url": "https://url.com",
                                        "fallback_url": "https://fallback.com",
                                        "trackers": [{
                                                "url": "http://url.com",
                                                "url_secure": "https://secureurl.com"
                                        }]
                                },
                                "data_assets": [{
                                        "data_type": "sponsored_by",
                                        "value": "a value"
                                }, {
                                        "data_type": "rating",
                                        "value": "8"
                                }],
                                "image_assets": [{
                                        "image_type": "icon_image",
                                        "creative_asset_image": {
                                                "url": "https://vcdn.adnxs.com/sand/creative-image/ea/f5/30/28/eaf53028-e6c6-4ac0-bcbb-ce8fe14b73ab.png",
                                                "url_secure": "https://secureurl.com",
                                                "height": 12,
                                                "width": 34
                                        }
                                }],
                                "image_trackers": [{
                                        "url": "http://url.com",
                                        "url_secure": "https://secureurl.com"
                                }],
                                "javascript_trackers": [{
                                        "url": "http://url.com",
                                        "url_secure": "https://secureurl.com"
                                }]
                        },
                        "thirdparty_viewability_providers": null,
                        "status": {
                                "user_ready": true,
                        },
                        "sla_eta": null,
                        "currency": "USD",
                        "type": "standard"
                }
        }
}

Determining the Technical Atttributes assigned to your creative

Although technical attributes isn't something that can be added to the automated reports today, this can be retrieved through the Creative service in the bidder API. For more information please refer to the Technical Attribute Service

This can be accessed by adding the query string parameter "?attributes=true" as: "adnxs.com/creative/MEMBER_ID/CREATIVE_ID?attributes=true"

"technical_attributes": [
{
 "id": 2,
 "name": "Flash"
},
{
 "id": 9,
"name": "Initial Load > 40kb"
},
 {
  "id": 13,
  "name": "Banner has AdChoices Icon"
 },
 {
  "id": 15,
  "name": "Animated: 15 seconds or less"
 }
 ]

The Meta Service provides the most up to date information about interfacing with objects in our API.

Creative Macros

The impression bus supports two types of creative macros replaced in real time: pre-defined Xandrcreative 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.

Warning

Macro Restrictions

Only pre-defined Xandr 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.

Xandr creative macros

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

Click Tracking Example:

"media_url": "https://ad.doubleclick.net/adi/N5364.Ivillage.com/B2965815.5;sz=728x90;click0=${CLICK_URL};ord=${CACHEBUSTER}?"

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:

{
   "creative":{
       "media_url":"https://adserver.com/imp?z=300x250;camp=${CAMPAIGN_ID};int=${INT_CODE}",
       "format":"url-html",
       "width":"300",
       "height":"250"
}}

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:

"custom_macros":[
{
   "name":"CAMPAIGN_ID",
   "value":"452346"
},
{
   "name":"INT_CODE",
   "value":"a352-45we-sdr3"
}]

Note

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

<iframe src="https://adserver.com/sz=300x250;camp=452346;int=a352-45we-sdr3" width=300 height=250/>

Partilhar via

Bidders - Creative service

REST API

JSON structure

Mobile

Audio

Video attribute

Video attribute wrapper

Creative template

Status

Native attribute

Link

Trackers

Image trackers

Javascript trackers

Data assets

Image assets

Creative asset image

Pixels

Segments

Changes that cause Re-Audit

Examples

Adding a custom pixel to a creative

Recursos adicionais