Skip to end of metadata
Go to start of metadata

Bidder Profile Service

Bidder Profiles are used to create and manage filtering criteria for which real-time Bid Requests you wish to receive. Profiles allow you to limit resources required to process unwanted bid requests. See the Bidder Profile - FAQ.

On This Page:

Important Notes

  • For a bid request to pass a bidder profile, the bid request must meet ALL of the specified filter criteria.
  • You may create multiple profiles for your bidder, but only one parent profile can be active for your bidder at any given time. Activate a profile by associating it with your bidder, using the Bidder Service.
  • Note that your bidder will always receive bid requests for inventory that is owned by a member associated with your bidder. Bidder profiles are not applied in this case.
  • Data Provider bidders can only have one parent profile and no child profiles.

Profiles must be attached to an active bidder object

After you create a profile, you must attach the profile to your bidder by specifying "parent_profile_id" via the Bidder Service

Do not use deprecated fields

Do not include any of the fields marked as deprecated below when you are configuring your profile(s). This will lead to your bidder not receiving the expected volume of bid requests.

Frequent profile updates may temporarily lock that profile

If you make multiple updates to a bidder profile within 30 minutes, the profile can potentially get locked as a safety precaution. If a profile gets locked, traffic matching only this profile will not go through for approximately 5 minutes.

Supported Filtering Criteria

The following filtering criteria are currently supported:

  • Selling Member
  • Geography
    • Country
      • Include/exclude requests for a specified set of countries, OR
      • Receive bid requests for any countries EXCEPT a specified set of countries
    • Region
      • Include/exclude requests for a specified set of regions, OR
      • Receive bid requests for any regions EXCEPT a specified set of regions
    • DMA
      • Include/exclude requests for a specified set of DMAs, OR
      • Receive bid requests for any regions EXCEPT a specified set of DMAs
  • Inventory
    • Domain List
      • Include/exclude requests for impressions that meet the requirements of white- or black-lists
    • Inventory Attribute
      • Include/exclude requests for impressions that contain certain inventory attributes
    • Audit Status
      • Exclude requests from domains that have not been audited by Xandr
  • Audience

    As of April 27, 2019, Xandr no longer supports segments on the platform for externally integrated DSPs.

    • Segment Targeting
      • Include/exclude requests for users that satisfy the segment targeting criteria
  • Creative Size
    • Include/exclude bid requests for the specified set of creative sizes
  • Supply Type (web / mobile_app / mobile_web)
    • Include/exclude impressions for regular web and mobile apps.

REST API

View Profiles

To see all of the profiles attached to your bidder:
GET https://api.adnxs.com/profile/BIDDER_ID
To see a specific profile attached to your bidder:
GET https://api.adnxs.com/profile/BIDDER_ID/PROFILE_ID

Add a Profile for your bidder

To add a new profile, use the following:
POST https://api.adnxs.com/profile/BIDDER_ID
(profile JSON)

Modify an Existing Profile

To modify an existing profile, use the following:
PUT https://api.adnxs.com/profile/BIDDER_ID/PROFILE_ID
(profile JSON)

Delete an existing profile

To delete a specific profile attached to your bidder:
DELETE https://api.adnxs.com/profile/BIDDER_ID/PROFILE_ID

Note: only inactive profiles can be deleted; that is profiles which are not associated with the bidder object.

Activate a profile for your bidder as the parent profile

Use the Bidder Service to set the profile_id field on the bidder to the id of the desired bidder profile.

Activate a profile for your bidder as a child profile

Use the Bidder Service to update the child_profiles array on the bidder to include id of the desired bidder profile.

JSON Fields

Field

Required

Type

Description

ID

yes, on update

String

Unique identifier for the bidder profile

code

no

String

Alternative identifier for the bidder profile, specific to the bidder

description

no

String

Description of the bidder profile

last_activity

no

timestamp

The timestamp of the last modification to the profile

Bid Throttling

 

 

 

passthrough_percent

no

double

The percent (50 = 50%) of bid requests which satisfy your profile targeting 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 passthrough_percent to 0, your bidder will only receive requests for users in at least one of your members' segments. These values take effect in increments of 0.1.

Member Filtering

 

 

 

member_targets

no

Array of Objects

Array of objects that include the member ids of members. The default action, if no action is specified, is "include" - meaning the member IDs must be included. This may be overridden by specifying an "action" in the object, e.g. "member_targets":[{"id":"100","action": "exclude"}]. See Platform Member Service for more details. 

Geography Filtering

 

 

 

country_action

no

Enum - "exclude" or "include"

If "exclude", only bid requests for countries NOT in "country_targets" will be sent to the bidder. If "include", only bid requests for countries in "country_targets" will be sent to the bidder. Default is exclude.

country_targets

no

Array of Objects

The country IDs to be either excluded or included, as defined by the country_action field. You can use the Country Service to retrieve a list of country IDs. See Country Targets for more details and format.

region_action

no

Enum - "exclude" or "include"

If "exclude", only bid requests for regions NOT in "region_targets" will be sent to the bidder. If "include", only bid requests for regions in "region_targets" will be sent to the bidder. Default is exclude.

region_targets

no

Array of Objects

The region/state IDs to be either excluded or included, as defined by the region_action field. You can use the Region Service to retrieve a list of region IDs. See Region Targets for more details and format.

dma_targets

no

Array of Objects

Array of objects specifying the dmas to be targeted (for inclusion or exclusion). E.g. [{"dma":123}, {"dma":124}]

dma_action

no

Enum - "exclude" or "include"

Defaults to "exclude". See dma_targets

city_targetsnoArray of Objects

The IDs of cities to be either included or excluded, as defined by the city_action field. You can use the City Service to retrieve a list of city IDs. See City Targets for more details and format.

city_actionnoEnum - "exclude" or "include"If "exclude", only bid requests for cities NOT in "city_targets" will be sent to the bidder. If "include", only bid requests for cities in "city_targets" will be sent to the bidder. Default is exclude.

Inventory

 

 

 

inventory_action

no

Enum - "exclude" or "include"

Deprecated. Please leave it as "exclude" and don't use this field, as this can reduce the available inventory sent to your bidder.

use_inventory_attribute_targets

no

Boolean

If set to "true", then inventory_attribute_targets will be applied. This flag allows you to "opt-in" to receive certain inventory attributes, such as toolbars, if they exist for a piece of inventory. If "false", the bidder will receive all inventory. 

inventory_attribute_targets

no

Array of inventory attribute objects

An array of objects for the targets to include, e.g. [{"id":12}]. If use_inventory_attribute_targets is enabled, we will send bid requests that contain the selected attributes. We will also send bid requests that contain no inventory attributes. To exclude a particular inventory attribute, simply include all the IDs except for the attribute you wish to exclude.

non_audited_url_action

No

string

If this is set to "exclude", all inventory that has not been audited by Xandr will be excluded. Otherwise, all inventory will be included.

domain_list_action

no

Enum - "exclude" or "include"

Default action to apply to domain_list_target.

domain_list_targets

no

Array of objects with the ID of the domain lists

Array of objects for the domain list targets, e.g. []. Only bid requests for inventory that match the domain_list_action for the enumerated domain lists will be sent to the bidder.

domain_action

deprecated

 

 

domain_targets

deprecated

 

 

Audience

 

 

 

segment_targets

no

Array of segment targets with the ID and action for each.

If "segment_boolean_operator" is "and", then if "action" for a segment is set to "exclude", then impressions for users that are in that segment not be sent to the bidder; if any "action" is set to "include", then users in the segments being included will be sent to the bidder. If "segment_boolean_operator" is set to "or", then users that meet any of the segment_targets criteria will be sent to the bidder.

As of April 27, 2019, Xandr will no longer support segments on the platform for externally integrated DSPs.

segment_boolean_operator

no

Enum - "and" or "or"

Action to apply to the segment_targets. "And" means all of the criteria must be satisfied. "Or" means at least one must be met.

As of April 27, 2019, Xandr will no longer support segments on the platform for externally integrated DSPs.

Supply Type (web / mobile)

 

 

 

supply_type_targets

no

Array of supply type targets:
"mobile_app" (for mobile app inventory),
"mobile_web" (for mobile web inventory),
"web" (for regular display inventory)

Determines which supply type targets should be included or excluded pursuant to supply_type_action

supply_type_action

no

Enum - "exclude" or "include"

Action to apply to supply_type_targets

Mobile-Specific

 

 

 

carrier_targets

no

Not yet supported

 

carrier_action

no

Enum - "exclude" or "include"

Action to apply to carrier_targets

handset_make_targets

no

Not yet supported

 

handset_make_action

no

Enum - "exclude" or "include"

Action to apply to handset_make_targets

handset_model_targets

no

Not yet supported

 

handset_model_action

no

Enum - "exclude" or "include"

Action to apply to handset_model_targets

location_target_radius

no

Not yet supported

 

location_target_latitude

no

Not yet supported

 

location_target_longitude

no

Not yet supported

 

Other

 

 

 

size_targets

no

Array of Objects

Array of widths and heights, specifying creative sizes that your bidder will bid on. E.g. [{"width":300,"height":250},{"width":600,"height":160}]

Not Currently Supported

 

 

 

language_targets

 

 

This field is not currently available

postal_code_targets

 

 

This field is not currently available

age_targets

 

 

This field is not currently available

daypart_targets

 

 

This field is not currently available

browser_targets

 

 

This field is not currently available

Country Targets

Each object in the country_targets array contains the following fields.

Field

Type

Description

idintThe ID of the country. You can use the Country Service to retrieve a complete list of country IDs.
namestringRead-only. The name of the country.
codestringRead-only. The code for the country.


Example

Region Targets

Each object in the region_targets array contains the following fields.

Field

Type

Description

idintThe ID of the region. You can use the Region Service to retrieve a list of region IDs.
namestringRead-only. The name of the region.
codestringRead-only. The code for the region.
country_namestringRead-only. The name of the country to which the region belongs.
country_codestringRead-only. The code for the country to which the region belongs.


Example

City Targets

Each object in the city_targets array contains the following fields.

Field

Type

Description

id

int

The ID of the city to target. You can use the City Service to retrieve a list of city IDs.

name

string

Read-only. The name of the city to target.

region_name

string

Read-only. The name of the region to which the city belongs.

region_code

string

Read-only. The code of the region to which the city belongs.

country_name

enum

Read-only. The name of the country to which the region belongs.

country_code

enum

Read-only. The code of the country to which the region belongs.

Example

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.

Add a new profile to bidder 6. The ID of the new profile is 123
See all profiles currently associated with bidder 6
To update profile ID 123 on bidder 6
Add a domain list to your bidder profile as a "blacklist"

Related Topics