Bidders - Creative service
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.
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 |
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. |
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. |
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. |
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. |
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 |
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.
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. |
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.
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.
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. |
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. |
Name | Type | Description |
---|---|---|
url |
string | A third-party javascript tracking URL. |
url_secure |
string | A third-party javascript tracking URL (that uses SSL) |
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 |
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 |
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. |
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. |
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 |
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.
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": {
...
}
}
}
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/>