Bid protocol

Overview#

When a screen is about to play an ad slot, the network asks every partner assigned to that screen whether it wants to fill the slot. You answer with the creative you want to play and the price you pay. The highest price wins. After the creative has played, the network tells you, and that call is what you are billed for.

This page describes the calls the network makes to your server. You host three endpoints, or two if you skip the optional win notice. The calls you make to us (inventory, creative upload, status, reconciliation) are on the Partner API page, and you need them before you can bid. A creative must be uploaded and approved there before it can be used in a bid.

Player            Network (SSP)                         Your server
  |  slot request     |                                       |
  |------------------>|                                       |
  |                   |  1. bidRequest  (POST, all partners   |
  |                   |     assigned to the screen, in        |
  |                   |     parallel)                         |
  |                   |-------------------------------------->|
  |                   |  200 bid  /  204 no bid               |
  |                   |<--------------------------------------|
  |                   |  choose the highest valid price       |
  |                   |  2. winNotice  (GET, winner only)     |
  |                   |-------------------------------------->|
  |  creative + nurl  |                                       |
  |<------------------|                                       |
  |  plays the creative                                       |
  |  reports the play |                                       |
  |------------------>|                                       |
  |                   |  3. confirmation  (GET nurl,          |
  |                   |     only after a verified play)       |
  |                   |-------------------------------------->|

Timing#

The network sends the bid request to all partners of the screen at the same moment and waits until every one has answered or timed out. Then it chooses. A slow answer delays the slot for everybody, so answer as fast as you can.

The win notice and the confirmation have no limit of their own and use a default of 30 seconds. They are sent while the player is waiting for its answer, so answer them in well under a second. Neither call is repeated.

What you must implement#

1. A bid endpoint. It accepts POST with a JSON body (bidRequest) and answers 200 with a bid or 204 without a body. Its address is agreed at onboarding.
2. A confirmation endpoint. It accepts GET on the nurl you returned in the bid (confirmation). It must be on the same host as your bid endpoint.
3. Optionally, a win notice endpoint (winNotice). Tell us its address as a URI template. If you do not give one, no win notice is sent.

Requests from us carry the header X-Auth-Token with a secret that we agree with you at onboarding. Check it on all three endpoints. Without it, anybody who knows an address could create billable events. Use HTTPS.

Auction rules#

• Every partner assigned to the screen is asked. The auction is first price: the partner with the highest price wins and is billed exactly that price.
• A bid is valid only if the creative named in video_id is confirmed, belongs to you and is assigned to this screen. Otherwise the bid is dropped as if you had not bid. The creative is matched by the external_id you chose at upload, not by our numeric id.
• If two valid bids have the same price, the winner is chosen by our internal partner order. Do not rely on it.
• min_price is the floor for the slot. Send a price at or above min_price. Bids below the floor or without a price may be dropped.
• There is no currency field. All prices, including min_price, are in the currency of your contract and are amounts for one play, not CPM.
• The winning price is recorded with two decimal places. Prices of 1,000,000 or more cannot be recorded.
• Only the winner receives the win notice. Only a verified play produces a confirmation. A win that is never played is not billed.

Billing#

The confirmation (nurl) is the billable event. It is sent once for each play after the player has reported the playback and the report has been verified. If your confirmation endpoint is down at that moment, the call is not repeated, the play is not marked as confirmed, and it does not appear in GET /{partner}/reconciliation/impressions. A win notice that fails does not cancel the win.

Reconciliation lists the plays whose confirmation call succeeded. In a search by date a play is listed only after it has been matched with the playback log of the player, which usually takes a few hours. Search again later, or search by unique_id. Compare reconciliation with the confirmations you received. The key of a play is the request_id.

Test checklist#

Before you go live, check that your bidder:

• rejects a request without the right X-Auth-Token with 401 or 403;
• answers 204 with an empty body when it does not want the slot;
• answers 200 with Content-Type: application/json and a JSON object (not an array) when it bids;
• echoes request_id exactly as received;
• returns a video_id that is the external_id of a confirmed creative that is assigned to the screen;
• returns price as a number at or above min_price, with at most two decimals;
• returns a nurl on the same host as the bid endpoint, and serves it with GET and 2xx without any extra parameters;
• handles duration_ms and min_price being null;
• handles screen.gid and screen.operator_id as strings;
• answers within a second under normal load, and never needs more than the 5-second limit;
• treats a repeated confirmation of the same request_id as one play.

Versioning#

Changes to this protocol are additive: new optional request fields and new optional response fields. Read request fields by name and ignore the ones you do not know. Unknown fields in your response are ignored by us.