Skip to end of metadata
Go to start of metadata

Integrate a Bidder

This page describes how to integrate a bidder with Xandr. It begins with an overview of the different "layers" of the integration, and ends with a worked example (using actual API calls) of a simple integration that will get you up and running quickly in our testing environment. It also provides links to more detailed information elsewhere on our wiki.
On This Page

System Overview

At a high level, there are two "layers" of the system we need to be concerned with during bidder setup:

  • Real-Time Layer (RTB): This is the heart of the action, where your bidder will participate in the real-time auction.
  • Configuration Layer (API): This is where you will configure your bidder' s "business logic" so it can bid on impressions; in other words, filtering out unwanted impressions, setting up users, adding the creatives your members want to serve, etc.

The diagram below shows the high-level architecture of a bidder and the various requests and responses it receives and sends.

In the diagram below, click on the request and response bubbles in the Real-Time Layer and the names of API services (such as the Bidder Profile) in the Configuration Layer to open the corresponding documentation in a new browser tab.

How to Set Up Your Bidder

In this section we'll walk through the entire process of setting up a bidder on the platform. We'll begin by making the API calls necessary to hook up the pipes.

Authenticate with the API

Before we can do anything else, we have to log in.

For more detailed information about authenticating via our API, see the Authentication Service.

Post to the test environment to authenticate:

View your Bidder Object

The bidder object represents your bidder in our system. As such, it has a lot of fields that you can use to configure how your bidder interacts with our platform. Think of it as the central "hook" on which you'll hang much of the rest of your configuration. A bidder object should already have been created for you by your Xandr representative.

In the example below, we make a GET call to view the bidder object, but we don't explain any of its details. For more detailed information about the bidder object, see the Bidder Service.

Update your Bidder object to receive unaudited inventory

In order to avoid drastically limiting the number of bid requests sent to your bidder, you need to set the send_unaudited field on the bidder object to true using the Bidder Service. This is true even though there is a non_audited_url_action (which defaults to "include") on the Legacy Bidder Profile Service.

View your Member Object

You need to have at least one member that buys through your bidder. You should have had a member created for you by your Xandr representative as part of the onboarding process. The member is where you will configure much of the "business logic" such as user segments, creatives, etc.

Create a Segment for your Member and add yourself to it

In this step, we'll create a segment and put ourselves in it to test the integration. Later on, we'll target this segment with the Bidder Profile during testing. This will serve several purposes:

  • Test that the "pipes" are open
  • Test that our ability to set up the profile's targeting works as expected
  • Allow us to send our bidder a very small amount of traffic (since presumably only a few users will be added to the testing segment)

Add yourself to the segment by visiting this URL:


Create a Bidder Profile

In this step, we'll create a bidder profile that only allows impressions shown to users in our test segment (created in the last step) to be sent in bid requests.

In the example below, the targeting breaks down like this:

  • We include (that is, target) the testing segment ID we just created.
  • Although we set the passthrough percent to 0, we should still receive bid requests for users in our members' segments. For details, see the docs for passthrough_percent on the Legacy Bidder Profile Service.
  • The segment boolean operator is set to "or" in case we'd like to add more testing segments later.
  • Finally, we target a few common mobile sizes just for fun.

This profile is meant to provide a simple example for onboarding use. It's unlikely to be appropriate for production scenarios. For more information about all of the options available with profiles, see the Legacy Bidder Profile Service and the Bidder Profile - FAQ.

Associate your Profile with your Bidder Object

The profile we've just configured can't take effect until it's associated with your bidder object. Since we're doing integration testing, we'll set the profile we just created as the parent profile.

Much more complex targeting configurations are possible in production settings with the right combination of parent and child profiles. For more information, see the Legacy Bidder Profile Service and the Bidder Profile - FAQ.

Add a Test Creative

In this step, we'll add a creative to serve to the users in our testing segment. After we upload this creative, we'll need to set up our bidder to respond to a Bid Request in the testing environment with a Bid Response that includes this creative when you bid on the test TinyTags provided to you by your Xandr representative. This will test that our profile (along with the rest of our integration) is working as expected.

This simple example creative uses very few of the creative configuration options we support. For more detailed information about the many types of creative configurations, see the Creative Service.

For more information on using the Client Testing environment to test creatives, see Using the Client Testing environment below. 

Add a Bidder Instance

The bidder instance object represents a particular bidder server running in the data center. In this example, we set the data center ID to  (NYM), since that's where the client testing environment lives.

This step assumes that you already have a bidder up and running that can respond to bid requests, ready requests, etc., as detailed in the System Overview.

For more information about configuring a bidder instance, see the Bidder Instance Service

Test the Integration

First, you should test the integration using our Client Testing environment, explained below. If this works as expected, you should be able to pull a debug log for the TinyTags provided to you by your Xandr contact as shown on our Troubleshooting page. If all is well, you will be able to compare the debug logs with your bidder's own logging to make sure that the integration is working as expected.

If you are still not seeing the bid requests you expect:

  1. Double check your configuration against the instructions on this page.
  2. Check out our Troubleshooting documentation

Using the Client Testing environment

The Client Testing environment provides a version of the Impbus and Impbus API that you can use to test your workflows and API implementations without incurring spend (as you would in production). The Client Testing environment's codebase and data are now updated every month. This means your testing environment will never be more than 30 days (and often less) behind the version of Xandr code that is running in Production. In addition, all Production data will also automatically be copied over to the Client Testing environment (including your member accounts and credentials) each month. This will allow far more robust testing against the latest features.

For reference, here are the endpoints for the Production and new Client Testing environments.

ProductProduct endpointClient Testing endpoint

Impbus API

Read more about the Client Testing Environment.

Related Topics