Skip to end of metadata
Go to start of metadata

Bid Request

We have disabled the AppNexus Supply Integration (ASI) protocol for server-side supply integrations beginning on October 1st, 2017. We strongly encourage that you migrate your supply to the OpenRTB protocol. Everything in this section is legacy content.

To send a bid request to AppNexus, you POST a JSON-formatted file containing the bid request details to the following endpoint:

For testing in our client-testing environment, you POST to the endpoint:

For guidance on formatting your request, see the Examples at the bottom of the page.

On This Page

JSON Fields

Where fields are available for internal and external values (for example, int_blocked_categories and ext_blocked_categories), include only one of the fields in your JSON-formatted file. If both are included, the internal value will be used.  

Field

Type

Description

Default

Required

an_user_id

int

The AppNexus ID for the user viewing the page. You include this field if you store user ID mappings in your system. See User ID Mapping for more details.

 

yes, if ext_user_id is not included

ext_user_id

string

The supply partner ID for the user viewing the page. You include this field if you store user ID mappings with AppNexus. Se User ID Mapping for more details.

 

yes, if an_user_id is not included

ext_auction_id

string

The supply partner ID for the auction. 

 

yes

width

int

The width of the placement.

 

yes

height

int

The height of the placement.

 

yes

ad_format

enum

The format of the creative that should be returned. Possible values: "iframe", "javascript", or "vast". Note about VAST: The "vast" format is not supported. However, see the VAST bid request below for an example of what a bid request for a VAST video creative is likely to look like.

 

yes

template_id

int

Not yet supported. For VAST video creatives, you may want AppNexus to include custom parameters in the ad_tag field of the bid response. To accomplish this, AppNexus can create a "supply template" for you, which you then reference here when requesting VAST video. For more details, see Supply Templates in the Bid Response documentation.

 

no

ip_address

string

The IP address for the user viewing the page.

 

no

is_securebooleantrue or false. The supply partner can request an SSL version of the creative by setting this to true.  

page_url

string

The full domain of the bid request (do not pass an encoded URL).

 

no

position

enum

The position of the placement on the page. Possible values: "above" (above the fold), "below" (below the fold), or "unknown".

"unknown"

no

ext_pub_code

string

The supply partner code for the publisher.

 

no

ext_placement_code

string

The supply partner code for the placement.

 

no

an_placement_id

int

The AppNexus ID for the placement. To retrieve placement IDs, use the Placement Service.

 

no

language

int

The AppNexus ID for the language of the page. To retrieve language IDs, use the Language Service

0

no

user_agent

string

The user agent for the request (i.e., the browser). 

 

no

int_blocked_technical_attributes

array of ints 

The AppNexus IDs for the creative technical attributes that are not permitted. To retrieve technical attribute IDs, use the Technical Attribute Service.

 

no

ext_blocked_technical_attributes

array of ints

The supply partner IDs for the creative technical attributes that are not permitted.

 

no

int_blocked_categories

array of ints

The AppNexus IDs for the creative categories that are not permitted. To retrieve category IDs, use the Category Service.

 

no

ext_blocked_categories

array of ints

The supply partner IDs for the creative categories that are not permitted. 

 

no

int_content_categories

array of ints

The AppNexus IDs for the content categories applied to the placement. You can use the Content Category Service to view all possible values. This includes custom content categories created by the supply partner under its AppNexus member.

0

no

ext_content_categories

array of ints

The supply partner IDs for the content categories applied to the placement. 

0

no

blocked_urls

array of strings

The creative landing page URLs that are not permitted. Up to 20 URLs can be blocked. Example formatting:

 

no

blocked_languages

array of ints 

The creative languages that are not permitted. To retrieve language IDs, use the Language Service.

 

no

int_blocked_brands

array of ints 

The AppNexus IDs for the brands that are not permitted. To retrieve brand IDs, use the Brand Service.

 

no

age

int

The age of the user viewing the page.

0

no

gender

enum

The gender of the user viewing the page. Possible values: "male", "female", or "unknown".

"unknown"

no

supply_type

enum

The display environment. Possible values: "web", "mobile_app", "mobile_web", "in-stream-video", or "other".

The value of supply_type will override the supply type set at the site level.

The "in-stream-video" format is not yet supported.

"web"

no

The license could not be verified: License Certificate has expired!

Placement Mapping

AppNexus will submit a bid only when we can map your request to a placement in AppNexus. We look up the following, in the following sequence:

  1. an_placement_id
  2. ext_placement_code
  3. ext_pub_code (the publisher's default tag)
  4. Your member's default placement (set up for your account by your Technical Account Manager before production login credentials are even assigned)

If none of the above are available, AppNexus will not submit a bid. Note that each ext_placement_code can map to only one placement in AppNexus, and each ext_pub_code can map to only one publisher in AppNexus.

User ID Mapping

AppNexus will submit a bid only when we can map your request to an AppNexus user ID. We look up the following, in the following sequence:

  1. an_user_id
  2. ext_user_id

If neither are included in the request, or neither map an AppNexus user ID, AppNexus will not submit a bid. See User ID Mapping for more details.

Examples

Sending a minimally acceptable bid request
Sending a bid request that includes AppNexus values only
Sending a bid request that includes external values only
Sending a bid request that does not include blocking details
  Sending a bid request for a VAST video creative (NOT YET SUPPORTED)

  • No labels