How RTB works
Real-time bidding for phone calls, in both directions: publishers ping you for a price before they send a call, and you ping buyers before you dial them.
After this page you will know what happens between a publisher's ping and a caller arriving, which settings decide the answer, and where each of them lives. It is the map; Ping and post is the protocol.
Real-time bidding prices a call before it is sent. Instead of agreeing one payout for every call in advance, the sender describes each call — the caller's state, a few tags — and the receiver answers with what that particular call is worth to them. The platform does this on both sides of a call.
The two directions
| Direction | Who asks whom | Where you set it up |
|---|---|---|
| Inbound | A publisher pings you: "what will you pay for this call?" You answer with a bid; if they accept, they claim it and send the call. | A lane and a routing key for the publisher. See Ping and post. |
| Outbound | You ping a buyer: "what will you pay for this call?" The best answer decides where the call goes. | An external RTB target on the routing plan. |
Both directions are optional and independent. A campaign can buy from publishers who ping while sending every call to fixed-price targets, or take calls only on tracking numbers while pricing each one by pinging buyers.
What each side needs
| To take pings from a publisher | To ping buyers for a price |
|---|---|
| A publisher account that is live. | A buyer, with an external RTB target on the campaign's routing plan. |
| A lane for them on the campaign, switched on, with payout terms. | A bidding endpoint the target can call, and response paths that say where the price is in the answer. |
| A routing key on the auction protocol, which the lane mints for you. | A ping timeout the campaign is willing to wait, and a margin it will not go below. |
| A campaign that is live. | A campaign that is live. |
What happens on an inbound ping
01
The key is checked
protocol, status, address, signature
02
The caller is filtered
hours, states, blocklist, duplicates, caps
03
Buyers are priced
fixed targets at their price, RTB targets in parallel
04
Bids are ranked
by the campaign's routing mode
05
Your margin is taken
and the lane turns the rest into their payout
06
Capacity is held
and the bid goes back with an expiry
The first step that refuses is the answer, and every ping — refused or not — becomes a row in the ping ledger with the reason attached.
- 1
The key is checked
Its protocol, whether the publisher and the campaign are live, its IP allowlist and, when the key demands one, the request's signature. See Keys and security.
- 2
Rate limits, before any work
Per minute, per hour and per day, on the key. Over any of them the answer is
429with reject code1024and aRetry-Afterheader. - 3
Repeats are recognised
An identical request still being scored is refused with
1025rather than run twice. A repeat of a request you already hold a live bid on is answered with that same bid, markedcached, rather than a second reservation on the same person. - 4
The caller is filtered
A caller ID where the campaign requires one, the tags the campaign requires, the blocklist, how many live bids that caller already holds on the key, the campaign's hours and states, and its duplicate window.
- 5
The publisher's own terms are applied
Their lane must be active. Then their caps, their concurrency limit, and the states and hours on their lane where those are narrower than the campaign's.
- 6
Every eligible target is priced
Fixed-price targets at their price; external RTB targets by pinging them in parallel, under one time budget. A buyer who misses the budget is excluded and warning
240is added to the answer. - 7
Bids are adjusted and ranked
Price modifiers and tag rules are applied, each bid is clamped to the campaign's limits, and the campaign's margin is taken. What is left is ranked.
- 8
The publisher's payout is worked out
Their lane's terms turn the winning price into their number, which is the only figure the answer carries. If that leaves less than the campaign's minimum margin, it is a no-bid with
1012. - 9
The winner's capacity is held
A slot is reserved for that caller until the bid expires, and the bid is returned with its terms and an expiry. Anything else is a no-bid with a reject code.
How the winner is chosen
A tracking campaign is a routing plan, not an open market: its owner wrote down an order, and a publisher's ping has to be answered by the target the plan would actually ring. So bids are ranked by the campaign's own routing mode.
| Routing mode | Order |
|---|---|
| Priority | The plan's priority first, then the bid. |
| Weighted | A weight-proportional draw across everyone eligible. |
| Highest bid | The bid first, then priority. |
Between the winning bid and the publisher's payout sits your margin: a percentage or a fixed amount, never below the campaign's minimum. That is the number the whole exchange exists to protect, and it is why 1012 margin_floor is a no-bid rather than a bid at a loss.
Timing
| Clock | What it governs | Set on |
|---|---|---|
| Ping timeout | How long the auction waits for buyers' bidding endpoints, all of them in parallel. A buyer who misses it is excluded from that auction only. | The campaign. |
| Bid expiry | How long the price and the reserved slot are held. The publisher posts before then. | The campaign. |
| Dial timeout | How long each buyer's line is rung before the platform moves on. | The campaign. |
| Failover budget | How long the platform keeps trying runners-up from the same auction before giving up on the caller. | The campaign. |
When the caller arrives, the platform dials the buyer who won. If that buyer does not answer inside the dial timeout, it works down the runners-up from the same auction until the failover budget runs out. Each attempt is on the call waterfall, with its own outcome.
Getting a caller onto the platform
A claimed bid is only worth something if the caller actually reaches you. There are two ways, and they are not equally reliable.
| The publisher transfers to | What happens |
|---|---|
A sipAddress | It always reaches the platform, and the call is recognised by the bid id inside the address. It is single-use, so it cannot be dialled twice. |
A phoneNumber | It reaches the platform only when the number is one of the platform's. The call is then matched by the caller's number against a bid claimed on that campaign in the last few minutes — so the caller must arrive from the number that was pinged. |
sipOk: true wherever a partner's platform can dial SIP. A claimed call whose caller never arrives is closed as never sent and earns nobody anything.What it costs
Pings are never charged, in either direction, however many you send or receive. The platform charges for connected minutes only, so a campaign that answers a hundred thousand pings and wins two hundred calls pays for two hundred calls. Rates are on the pricing page, and what you owe a publisher is separate — see Payout terms.
A worked example
Your Acme Health inbound campaign has two fixed-price targets and one external RTB buyer. Northwind Media ping at 14:03:11 with a Dallas caller.
- 14:03:11.000 — the key passes. Northwind are live, the campaign is live, the address is on the allowlist.
- 14:03:11.004 — the caller is not blocked, the state is on the lane, the campaign is inside its hours, and the lane's daily cap has room.
- 14:03:11.010 — two fixed-price targets are priced from their own settings, and the external buyer is pinged. They answer in 180 milliseconds, comfortably inside the budget.
- 14:03:11.200 — the external buyer's bid is the highest. Your margin is taken, Northwind's lane turns what is left into their payout, and the result clears the campaign's minimum margin.
- 14:03:11.210 — the buyer's capacity is held for that caller and the bid goes back with its terms and an expiry.
- 14:03:12 — Northwind post. They are given a SIP address and transfer the caller to it.
- 14:03:16 — the caller arrives. The platform dials the winning buyer, who answers at 14:03:24.
- 14:06:28 — the call ends after 184 seconds. It is over the buyer's threshold, so revenue books, and over Northwind's lane buffer, so their payout books too.
Had the buyer not answered, the platform would have rung the runner-up from the same auction inside the failover budget, and the call would have settled on that bid instead. Had the caller hung up before the post, releasing the bid would have freed the buyer's slot at once rather than at the expiry.