Skip to end of metadata
Go to start of metadata

Bidder Service

The Bidder Service connects a bidder to the AppNexus Impression Bus and allows the bidder and Imp Bus to begin communication. Your AppNexus representative will create the bidder in the system, and you will use the Bidder Service to make modifications or retrieve your bidder ID.

You may need your bidder ID for some of the Services. To find out what your bidder ID is, run the "see all bidders" command described below.

Some bidder functions are accessible only to certain users, as they are based upon contractual obligations:

  • Modifying the data provider fields (via PUT) - requires a data access agreement with each provider

In bidder sandbox environments, all functionality is available for integration purposes.

On This Page

REST API

To see the bidder that your user has permissions to see (will not show other users' bidders):

To see a particular bidder:

To add a new bidder:

To modify an existing bidder (note limitations above):

To delete an existing bidder:

JSON Fields

Field

Required

Type

Description

id

yes, on update

int

The ID of the bidder.

short_name

yes (on add)

string

An optional short name for the bidder. While not technically required, this field is necessary for metrics, so it should be considered required.  Note: Only alphanumeric characters (A-Z, 0-9) and underscores are allowed. Please do not use spaces, special characters, periods, or other punctuation marks.

name

yes (on add)

string

Name associated with the bidder.

active

no, default is true

Boolean

Whether the bidder will receive requests or not.

bid_uri

yes (on add)

string(255)

The URI for bid requests (for example, /bid).

notify_uri

no

string (255)

The URI for notification requests (for example, /notify). Use null, not an empty string, to set this to blank.

  • The notify_uri must be a relative URI. AppNexus does not currently support putting the bid_uri and notify_uri on separate hosts.
  • If null, the bidder does not receive notify requests.

click_uri

no

string(255)

The URI for click requests (for example, /click). Use null, not an empty string, to set this to blank. Click Request

pixel_uri

no

string(255)

The URI for pixel requests (for example, /pixel). Use null, not an empty string, to set this to blank. Pixel Request

ready_uri

yes (on add)

string(50)

The URI for a Bidder Instance status check (for example, /ready).

audit_notify_uri

no

string(255)

The URI for passing creative auditing updates (eg http://send.mycompany.com/auditnotifyrequests)

userdata_javascript

no

string

Custom JavaScript functions that can be called when a bidder updates a user's cookie data. See User Data Integration (JS) for details.

setuid_function

no

string

The name of the JavaScript function to be used on SetUID calls. See User Data Integration (JS) for details.

parent_profile_id

no

int

The ID of the parent bidder profile. Bidder profiles can be used to filter bid request traffic that reaches a bidder. See Bidder Profile Service and Bidder Profile - FAQ.

child_profiles

no

Array of objects with the ID of the bidder profiles

Array of objects specifying the child profiles to be used. For example: [{"id":123}, {"id":124}].

dongle

no

string

A password that protects a bidder's debug output in a debug impression. See debug_text in the Bid Response. Available to users of type "bidder" only.

notify_full_auction

no

Boolean

Setting this to "true" means that the Impression Bus will include full_tag_info and bid_info in the Notify Request. Post-pending notifies (post_pending set to true in the Notify Request) do not include these tags because the bid acceptance callback has not yet been received.

notify_lostno, default is falseBoolean

Indicates whether the bidder is notified about all lost bids at the URI specified in the notify_uri field. If no URI is provided, no notifications are sent.

  • If true, the bidder is notified about all lost bids.
  • If false, the bidder is only notified about lost bids with Notify Request error code IDs above 100. We don't log errors or send lost notifies if the error id is less than 100 for OpenRTB bidders.
notify_pendingno, default is falseBoolean

Indicates whether the bidder is notified about pending bids at the URI specified in the notify_uri field. If no URI is provided, no notifications are sent.

notify_no_bidno, default is falseBooleanIndicates whether the bidder is notified when the bidder has no bid for a request. The notification is sent to the URI specified in the notify_uri field. If no URI is provided, no notifications are sent.

exclude_unowned

no

Boolean

Exclude inventory not owned by a member associated with this bidder.

send_unaudited

no, default is false

Boolean

This flag determines whether or not your bidder will be sent unaudited traffic.

Strictly speaking, this field is deprecated, but it should ALWAYS be set to true. If this field is set to false, your bidder will not receive any Bid Requests.

bid_percent

no

int

The percent (50 = 50%) of total platform traffic that you wish to receive. Requests that are sent to your bidder are randomly chosen, although you can choose for your bidder to always receive requests for users in segments of members associated with your bidder. If you set bid_percent to 0, your bidder will only receive requests for users in at least one of your members' segments. This filter is applied to traffic that makes it through the Bidder Profile Service.

always_send_owned_segments

no

Boolean

Determines whether impressions for users in segments owned by or shared with the Bidder should bypass passthrough_percent on Bidder Profiles. Note: this only overrides the passthrough_percent on the bidder profile; all other restrictions such as country, member, size, or domain filters would still be taken into consideration when deciding whether an impression will be sent to the bidder. 

object_limit_notify_email

no

array of strings

AppNexus limits the number of objects each bidder can create and use on the platform. This limit includes inactive and unused objects. This field contains the email addresses that will be notified when you hit the 85%, 95%, and 100% threshold for object limits.

protocol_idno

int

Read-only. This describes the protocol associated with this bidder, which describes the type of bidder it is. For example, a protocol_id of 6 means that this bidder uses the OpenRTB 2.0 specification for its integration with AppNexus. The default integration value for a newly created bidder is 1, none. This is the default protocol as defined in Bid Request and Bid Response. Bidders with a protocol_id of 6 integrate according to the OpenRTB 2.0 Spec (PDF).

Spec for OpenRTB 2.4 , protocol_id :10

The following values are supported (each ID is followed by the protocol_name associated with that ID):

  • 1: none
  • 2: wp7
  • 3: contentads
  • 4: admarket
  • 5: adexpert
  • 6: openrtb2.0
  • 10: openrtb2.4
protocol_namenostringRead-only. The name of the protocol associated with this bidder. See the definition of protocol_id   above for all of the the accepted values of   protocol_id   and their mappings to names.

last_activity

no

timestamp

The timestamp of last modification to this bidder instance.

override_for_dealsnoBoolean

Determines whether or not to use the bidder profile to determine if a bid request should be sent. Deals are usually negotiated directly between sellers and buyers and are generally not subject to bidder profile restrictions.

  • true: Ignore the bidder profile and send bid request regardless of bidder profile
  • false (default): Use bidder profile to determine whether the bid request should be sent

Note: Use Bidder Profile Service to Filter and Throttle

To filter the traffic your bidder will receive, please use the Bidder Profile Service. A few filtering and throttling fields still exist in the Bidder Service, but they will be migrated to the Bidder Profile Service soon. Class filters are available in both; we recommend using the Bidder Profile Service for these.

Deprecated fields

send_class_2

no, default is true

Boolean

This flag determines whether or not your bidder will be sent Class 2 traffic. Please note that throttling by inventory class is also possible via the Bidder Profile Service .

send_class_3

no, default is true

Boolean

This flag determines whether or not your bidder will be sent Class 3 traffic. Please note that throttling by inventory class is also possible via the Bidder Profile Service .

send_unaudited

no, default is false

Boolean

This flag determines whether or not your bidder will be sent unaudited traffic. Please note that throttling by inventory class is also possible via the Bidder Profile Service

You must set this field in order to see bid requests

You must set send_unaudited to true in order for your bidder to receive bid requests. For more information, see Integrate a Bidder.

send_owned_blacklist

no

Boolean

Send blacklist inventory if owned by a member associated with this bidder.

userdata_entity_id

no

int

This field is deprecated.

Examples

Authentication Token
Authentication is always the first step when using the API Services. The authentication token can then be written to our cookie file for future use. Please see Authentication Service for more detailed instructions.

View bidder information
If AppNexus has already added your bidder for you, you will already have some bidder information, like your bidder ID, in JSON format. You can view this information with the below command.

Modify a bidder
Now that you know your bidder ID, you can use a text file in JSON format to modify your bidder. Below is an example JSON that will change the ready URI parameter. (Note that only these included fields will be updated. All other fields will be unchanged.)

Then you use the PUT command to update this data in the Impression Bus cache.

Now when you view Bidder 4, you get:

Related Topics