Epom as a seller: the /hb/bid endpoint

A detail page of the OpenRTB integration reference, which has the two directions, the currency rules and the bid floor chain. This page is the inbound direction: the contract of the endpoint Epom answers when a buyer asks it to bid. The outbound direction is on OpenRTB bid request fields and OpenRTB bid response, auction and macros.

Epom as a seller: /hb/bid

Epom also answers OpenRTB bid requests, as a bidder in a Prebid auction. This is the header bidding path; the operational side — tags, slots, Prebid Server, reporting — is documented in Header bidding. The wire contract:

Endpoint	POST /hb/bid on the ad-serving host. Any other method answers 405.
Protocol	OpenRTB 2.6
Request	id and at least one imp required; site or app required. Up to 40 impressions per request (configurable per network by Epom).
Validation	Cheap field checks only, not full JSON-Schema. A rejection is a 400 with a JSON {"error": "<reason>"} body naming the reason.
No bid	204 No Content — Epom does not send an OpenRTB no-bid object.
Floor	imp.bidfloor in imp.bidfloorcur (USD when absent), converted to USD at the day’s rate. A floor in a currency that cannot be priced gets no bid, counted and logged.
Response	One seatbid, seat epom, cur: "USD", whatever the request’s cur lists — Prebid Server, and a Prebid running the currency module, convert it.

Each returned bid carries id, impid, price, adm, crid, cid, w, h, mtype (1 banner / 2 video / 4 native), exp, adomain when known, and dealid: "epom-direct" on bought demand.

Note: adomain is the Advertiser domain declared on the advertiser when the advertiser has one, otherwise the adomain that came in on the DSP bid the creative was bought from. When neither exists the field is omitted — an absent adomain is deliberate, not a bug.

Corner case: bid.exp tells you how long the bid may sit in your cache, and it is derived from the impression beacon’s own validity minus a few seconds of travel time. Render later than that and the impression is never counted — the bid is still valid markup, but you will not be paid for it.

Warning: a /hb/bid call is a bid, not a served impression, but Epom does not yet treat it as one: selection still increments opportunity limits, request capping and pacing for bids that never win or render. Expect header-bidding traffic to consume capping and limit budget ahead of actual delivery, and read the header bidding reporting notes before reconciling numbers.

Corner case: requests for a placement that no active header-bidding tag lists are refused by default. That gate has three settings and its own diagnostics — see Header bidding.

Corner case: on a video slot, bid.adm is a VAST document Epom builds, and for a VPAID framework creative its <Duration> can legitimately be 00:00:00. VAST requires a Duration on every Linear, but a VPAID creative’s real length is only known once the unit runs, so Epom emits a placeholder unless the framework declares a parameter literally named duration that parses as a positive number of seconds. A real duration always carries milliseconds (00:00:15.000); the bare 00:00:00 is the placeholder. Do not reject the creative on it, and do not use it to size a player or a timeout.

Related

• OpenRTB integration reference — the two directions, currency and the bid floor
• Header bidding — the seller direction, end to end
• OpenRTB bid request fields
• OpenRTB bid response, auction and macros
• VAST vs VPAID explained