OpenRTB Ad Server API Cookie Sync

Document created by catherine.racette on Sep 3, 2017Last modified by david.simerly on Sep 20, 2017
Version 8Show Document
  • View in full screen mode

OpenRTB 2.3 Documentation 

OpenRTB 2.3 Introduction 

OpenRTB 2.3 Integration Plan 

OpenRTB Bid Request Objects and Parameters 

OpenRTB Bid Response Objects and Parameters 

OpenRTB 2.3 PubMatic Extensions 

Open RTB 2.3 Examples 

OpenRTB Ad Server API Cookie Sync 

OpenRTB 2.3 Click Tracking 

OpenRTB 2.3 Win/Loss Notification 

OpenRTB 2.3 API Performance 

OpenRTB 2.3 Known Limitations & Reference 


OpenRTB Ad Server API cookie sync up is mandatory while integrating with PubMatic APIs on the OpenRTB Ad Server. Since there is no access to the browser's cookies as the ad serving request is sent from the server, the below mechanism will help in obtaining the PubMatic user IDs, storing it in a OpenRTB Ad Server cookie store.


A mapping between the publisher's user ID and the PubMatic user ID should be stored in the publisher's OpenRTB Ad Server cookie store.


EXAMPLE: is a service used by the publisher to keep a mapping of the user IDs. Let's assume that the publisher's user ID is stored on a user's browser in a cookie named "pub-user-id" with value "PUB_UserID_9890". Now if above URL is passed as then the publisher should map his user ID (PUB_UserID_9890) and PubMatic's user ID (PM_UserID_2200).

To encode such a URL as, you can use the following JavaScript code - encodeURIComponent('');


PubMatic's "user_sync.html" can call a given publisher's URL and append the PubMatic user ID to the publisher URL as mentioned below.


While sending a bid request to the PubMatic ad server, you may look up the PubMatic user ID in the cookie store and send it as a part of the request header. To do sync up-pixeling, the publisher should call the following URL in iframe on every page hit.


New URL to be used:


Where "p" indicates the publisher's ID, "s" indicates the site ID and "predirect" indicates the third-party user ID sync up URL to be called by PubMatic for the user sync up.

However, site ID is an optional parameter.


Old URL to be deprecated:



  • If the client ad request does not have the user cookie for PubMatic, please send a call to the above-mentioned URL with a beacon of your domain as a value to the "predirect" parameter.
  • The above call will create a PubMatic user ID, if it does not exist already.
  • The generated PubMatic user ID will be appended to the third-party URL that was sent as “predirect” parameter's value in the above call.
  • This PubMatic user ID should be sent in the User Object by the buyeruid attribute in the next bid request.
  • For the user ID sync-up with our data partners, you need to call the above URL multiple times.


Passing PubMatic User ID in Request Header

The PubMatic user ID should be sent in the User Object by the buyeruid attribute.


"user": {
"buyeruid": "169F3707-380A-4D76-BE37-B2DB05992D4A"