RTB User Matching API

Revision 2012-03-19

Document History
Version 2012-01-17 2012-03-19 Changes Last beta version. In calls from adscale to the RTB partner, new parameters can be added at any time and without prior notification. The tpuid parameter is of type string.

RTB User Matching API

Overview
User matching allows RTB partners and adscale to exchange user IDs and is a prerequisite for RTB bidding. Two implementations are available: Implementation A adscale calls the RTB partner with adscales user ID, the RTB partner redirects back to adscale with the RTB partners user ID. Implementation B The RTB partner calls adscale with the RTB partners user ID, adscale redirects back to the RTB partner with adscales user ID.

Implementation A: adscale Calls the RTB Partner

User Matching API Parameters
The RTB partner must implement an API that accepts the following parameters: Parameter uid tpid cburl Type String Integer String Description adscale's unique user ID. Unique identifier of the RTB partner. URL to call back to adscale.

Note: Additional parameters can be added at any time and without prior notification. When the RTB partner receives a request, a callback to adscale must be generated. The following parameters are required: Parameter tpuid tpid Type String Description The RTB partner's unique user ID for the user. Set to 0 to disable user matching for this user. Integer Unique identifier of the RTB partner.

RTB User Matching API

Redirect API Implementation

The API is called as an HTTP request that returns an HTTP redirect to adscale. As an example, adscale is initiating the user match request:
<img width="0" height="0" src="http://rtb.partner.com/match?uid=12345&tpid=123& cburl=http://ih.adscale.de/adscale-ih/tpui" />

The RTB partner's user match response:

Location: http://ih.adscale.de/adscale-ih/tpui?tpid=123&tpuid=ABCDE

Implementation B: The RTB Partner Calls adscale

adscale provides a user matching URL which can be called by an RTB partner (via a redirect). This request includes the partners user ID and a mandatory redirect URL to retrieve adscale's user ID. This redirect is sent via a redirect header.

User Matching API Parameters

The RTB partner must call the adscale User Matching API with the following parameters: Parameter tpid tpuid cburl Required Yes Yes Yes Type Integer String String Description Unique identifier of the RTB partner. The unique user ID on partners side. The URL to which the user should be redirected afterwards (needs to be URL encoded). __ADSCALE_USER_ID__ will be replaced with the current adscale unique user ID (a string).

As an example, the RTB partner initiates the user match request:

http://ih.adscale.de/adscale-ih/tpui?tpid=123&tpuid=ABCDE&cburl= http%3A//rtb.partner.com/match%3Fuid%3D__ADSCALE_USER_ID__

adscale replies to the redirect using the given redirect URL with the token being replaced:
Location: http://rtb.partner.com/match?uid=12345

RTB User Matching API