Ping and post

After this page a publisher's developer can integrate end to end: check a key, ping for a price, post to claim the bid, transfer the caller, release a bid that is not needed, sign requests when the key demands it, and retry safely. It is written for the person writing that code. The same endpoints are listed field by field in the RTB ping and post reference.

The protocol is two requests on purpose. The ping answers with a firm price and no destination. The destination only comes back from the post, which is a second authenticated request that the platform can meter. That is what stops a price list being harvested by pinging without ever sending a call.

Before you start

• A publisher key. It begins b3k_live_ and belongs to one lane: one publisher on one campaign. The key alone names both, so neither appears in any request. The workspace that buys your calls issues it. See Keys and security.
• A key on the right protocol. The key's protocol must be rtb_v1 or both. A legacy key answers 403 wrong_protocol here.
• A live publisher and a live campaign. Until both are live every request is refused with 403 publisher_not_live or 403 campaign_not_live.

https://api.buy3.io/api/rtb/v1

Check the key first

GET /api/rtb/v1/whoami answers with everything you would otherwise have to ask the buyer: the campaign's rules, the key's limits, whether it must sign, its IP allowlist and the exact URLs to call. Run it before you write anything else.

curl "https://api.buy3.io/api/rtb/v1/whoami" \
  -H "Authorization: Bearer $BUY3_PUBLISHER_KEY"

{
  "ok": true,
  "problem": null,
  "protocol": "rtb_v1",
  "environment": "production",
  "publisher": { "id": "c4e1a2b3-9d8f-4f6e-b5a4-1c2d3e4f5a6b", "name": "Northwind Media", "status": "live" },
  "campaign": {
    "id": "6a2d1f0e-8b7c-4c55-a1d3-0e9f8a7b6c5d",
    "name": "Medicare inbound",
    "status": "live",
    "pricingMode": "fixed",
    "bufferSeconds": 90,
    "requireCallerId": true,
    "requiredTags": []
  },
  "key": {
    "prefix": "b3k_live_9f2a",
    "label": null,
    "issuedAt": "2026-09-01T09:00:00.000Z",
    "rotated": false,
    "graceUntil": null,
    "requireSignature": false,
    "signingSecretLast4": null,
    "ipAllowlist": []
  },
  "signing": {
    "required": false,
    "post": "HMAC-SHA256 over `{timestamp}.{nonce}.{raw request body}`",
    "get": "HMAC-SHA256 over `{timestamp}.{nonce}.{raw query string, without the leading ?}`"
  },
  "limits": { "perMinute": 120, "perHour": 5000, "perDay": 50000, "maxLiveBidsPerCaller": 4, "bidTtlSeconds": 60 },
  "supply": { "targetsActive": 3, "internalFloorEligible": 0, "agentsOnline": 0 },
  "endpoints": {
    "ping": "https://api.buy3.io/api/rtb/v1/ping",
    "post": "https://api.buy3.io/api/rtb/v1/post",
    "release": "https://api.buy3.io/api/rtb/v1/release",
    "conversion": "https://api.buy3.io/api/rtb/v1/conversion"
  }
}

Authentication and errors

Send the key as Authorization: Bearer b3k_live_… on every request. Bodies are JSON, at most 32 KB. A form-encoded body (application/x-www-form-urlencoded) is accepted too, and a ping can be a GET with the same fields as query parameters.

Requests are checked in this order, and the first failure is the answer. Every one of them is written to the ping ledger, so the buyer can see the same refusal you did.

The exchange

1. 1

   Ping

   Describe the caller. A win reserves a slot for that caller until the bid expires and answers with a bidId, the payout and its terms. It never includes a destination.

   POST/api/rtb/v1/pingPing for a bid
2. 2

   Post

   Claim the bid before it expires, with an Idempotency-Key header. The answer is 201 with the destination and a callId. The call record exists from this moment, with the price and terms frozen as they were quoted.

   POST/api/rtb/v1/postPost to claim a bid
3. 3

   Send the call

   Transfer the caller to sipAddress if you were given one, otherwise to phoneNumber. When the caller arrives the platform starts the failover clock, dials the buyer who won and, if that buyer does not answer, works down the runners-up from the same auction.

4. 4

   Or release the bid

   If the caller hung up before you posted, release the bid. The reserved slot is freed at once instead of when the bid expires, which keeps capacity open for your next caller.

   POST/api/rtb/v1/releaseRelease a bid

Ping

Request fields

Unknown fields become tags

Any top-level field that is not one of the protocol's own names is kept as a tag with the source publisher, exactly as if it had been sent inside tags. A partner's existing payload therefore usually works unchanged. In the example below age_band is a top-level field and utm_source is inside tags; both arrive on the call as tags.

• Only scalar values are kept. Objects, arrays and null are dropped.
• At most 40 tags. A key is cut at 64 characters and a value at 512.
• When the same name is sent at the top level and inside tags, the value inside tags wins.
• The protocol's own names never become tags: callerId, state, zip, city, sipOk, exposeCallerId, publisherRef, externalCallId, test, tags, bidId, reason, key, callId, converted, value, disposition, occurredAt, and their snake_case spellings.
• Tags are part of what a bid is for. The buyer's tag filters read them, and two pings with different tags are two different requests.

curl -X POST "https://api.buy3.io/api/rtb/v1/ping" \
  -H "Authorization: Bearer $BUY3_PUBLISHER_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 7c9e6679-7425-40de-944b-e07fc1f90ae7" \
  -d '{
    "callerId": "+12145550142",
    "state": "TX",
    "zip": "75201",
    "sipOk": true,
    "publisherRef": "lead-88231",
    "age_band": "65plus",
    "tags": { "utm_source": "search" }
  }'

A bid

{
  "ok": true,
  "auctionId": "AU-100482",
  "bidId": "0f8fad5b-d9cb-469f-a165-70867728950e",
  "payout": 27.5,
  "payoutCents": 2750,
  "currency": "USD",
  "expiresInSeconds": 60,
  "expiresAt": "2026-09-20T14:04:11.000Z",
  "expiresAtEpochMs": 1789913051000,
  "nextStep": "post",
  "terms": [
    { "code": 101, "description": "Call must connect" },
    { "code": 100, "description": "Minimum connected duration 90 seconds", "seconds": 90 },
    { "code": 110, "description": "Duplicate callers are not paid within 86400 seconds", "seconds": 86400 }
  ],
  "campaign": { "id": "6a2d1f0e-8b7c-4c55-a1d3-0e9f8a7b6c5d", "name": "Medicare inbound" },
  "warnings": [
    { "code": 205, "description": "SIP delivery is preferred over the DID" }
  ]
}

A no-bid

{
  "ok": false,
  "bidId": null,
  "payout": 0,
  "payoutCents": 0,
  "reject": {
    "code": 1003,
    "reason": "no_capacity",
    "description": "No target had capacity for that call"
  },
  "retryAfterSeconds": 15,
  "auctionId": "AU-100483"
}

Post

curl -X POST "https://api.buy3.io/api/rtb/v1/post" \
  -H "Authorization: Bearer $BUY3_PUBLISHER_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 1b4e28ba-2fa1-41d2-883f-0016d3cca427" \
  -d '{
    "bidId": "0f8fad5b-d9cb-469f-a165-70867728950e",
    "callerId": "+12145550142",
    "externalCallId": "pbx-5531902"
  }'

{
  "ok": true,
  "callId": "0b9f6c1e-52a4-4a0e-9f0a-3d1c7e8b2a11",
  "ref": "CA-482137",
  "bidId": "0f8fad5b-d9cb-469f-a165-70867728950e",
  "payout": 27.5,
  "payoutCents": 2750,
  "sipAddress": "sip:0f8fad5bd9cb469fa16570867728950e@sip.example.com",
  "expiresInSeconds": 52,
  "expiresAt": "2026-09-20T14:04:11.000Z",
  "terms": [
    { "code": 101, "description": "Call must connect" },
    { "code": 100, "description": "Minimum connected duration 90 seconds", "seconds": 90 }
  ],
  "postback": {
    "url": "https://api.buy3.io/api/rtb/v1/conversion",
    "key": "b3p_4f1d2c3b4a5e6f70"
  }
}

Release

POST /api/rtb/v1/release with { "bidId": "…", "reason": "…" }. reason is optional, up to 120 characters, and is shown in the ledger. A bid that is still open answers 200 { "ok": true, "released": true }. Releasing a bid that has already closed is not an error: it answers 200 { "ok": true, "alreadyClosed": true, "status": "expired" }, with status saying how it closed, so a retried release is always safe. An unknown bid is 404 unknown_bid.

curl -X POST "https://api.buy3.io/api/rtb/v1/release" \
  -H "Authorization: Bearer $BUY3_PUBLISHER_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "bidId": "0f8fad5b-d9cb-469f-a165-70867728950e", "reason": "caller_hung_up" }'

A bid you neither post nor release simply expires and frees its slot then. Releasing is a courtesy that pays: while a bid is live it holds the winning target's capacity, and a caller with too many live bids on your key is refused with 1026.

Conversion postback

Some payouts depend on what happened after the call. The buyer reports that with POST /api/rtb/v1/conversion. It takes no publisher key, because a buyer never holds one. It is authorised by the per-call postback.key that came back from the post, so pass postback.url and postback.key to the buyer with the call.

curl -X POST "https://api.buy3.io/api/rtb/v1/conversion" \
  -H "Content-Type: application/json" \
  -d '{
    "key": "b3p_4f1d2c3b4a5e6f70",
    "callId": "0b9f6c1e-52a4-4a0e-9f0a-3d1c7e8b2a11",
    "converted": true,
    "value": 420.00,
    "disposition": "policy_sold"
  }'

The answer is 200 { "ok": true, "callId": "…", "ref": "CA-482137", "billable": true, "payoutCents": 2750 }, with the books as they stand after the conversion. A wrong key answers 404 unknown_call, never 403, so the endpoint cannot be used to discover which call ids exist. A call that is already converted answers 409 already_converted with convertedAt. Conversions close 72 hours after the call ends: 410 window_closed.

The buyer can also look the call up with the same key, whatever their phone system stripped on the way: GET /api/rtb/v1/calls/CA-482137 with Authorization: Bearer b3p_… (or ?key=). The caller's number is included only when the campaign exposes caller ID and the call has connected.

Signing requests

A bearer key proves who is asking. It does not prove the request was not altered on the way, or captured and sent again. A key can therefore require signed requests. whoami says whether yours does. When it does, every ping, post and release must carry three headers:

POST   {timestamp}.{nonce}.{raw request body}
GET    {timestamp}.{nonce}.{raw query string, without the leading ?}

v1 = hex( HMAC-SHA256( key = signing secret, message = the string above ) )

• Sign the exact bytes you send. The server verifies the raw body before it parses it. Serialise once, sign that string and send that string. A library that re-serialises the body after you signed it will fail with 4001.
• A GET is signed too, over its query string exactly as sent, percent-encoding and order included. A request with no body and no query signs an empty string after the second dot.
• The timestamp is the X-Buy3-Timestamp header. It must be within 300 seconds of the server's clock, either way, or the answer is 4002 signature_stale.
• The nonce is remembered once the signature has checked out. Sending it again is 4003 nonce_replay. Mint a new nonce for every request, retries included.
• The secret begins b3s_ and is shown once, when it is issued or rotated. Rotating it takes effect immediately. See Keys and security.

BODY='{"callerId":"+12145550142","state":"TX"}'
TS=$(date +%s)
NONCE=$(openssl rand -hex 16)
SIG=$(printf '%s.%s.%s' "$TS" "$NONCE" "$BODY" | openssl dgst -sha256 -hmac "$BUY3_SIGNING_SECRET" | sed 's/^.* //')

curl -X POST "https://api.buy3.io/api/rtb/v1/ping" \
  -H "Authorization: Bearer $BUY3_PUBLISHER_KEY" \
  -H "Content-Type: application/json" \
  -H "X-Buy3-Timestamp: $TS" \
  -H "X-Buy3-Nonce: $NONCE" \
  -H "X-Buy3-Signature: t=$TS,v1=$SIG" \
  -d "$BODY"

Rate limits

Pings are limited per key, in three fixed windows: the clock minute, the clock hour and the day. The defaults are 120 a minute, 5,000 an hour and 50,000 a day, and the buyer can set each one on your key; whoami reports yours under limits. Every ping counts, including the ones that are refused. Posts and releases are not counted.

RateLimit-Policy: "minute";q=120;w=60, "hour";q=5000;w=3600, "day";q=50000;w=86400
RateLimit: "minute";r=57

q is the quota and w the window in seconds; r is what is left of the minute. Over any of the three limits the answer is 429 with a no-bid body carrying reject code 1024, a retryAfterSeconds field and a Retry-After header. Both give the seconds until the window that overflowed rolls over. Wait that long; pinging through a limit only uses up the next window.

Retries and idempotency

Networks fail between the request and the response. Four mechanisms make a retry safe, and between them one caller is never sold twice.

• One caller can hold one live bid on a campaign at a time, across all publishers. A second attempt answers 409 caller_already_reserved.
• One caller can hold a limited number of live bids on your key across campaigns: limits.maxLiveBidsPerCaller, 4 unless the buyer changed it. Over it the ping is a no-bid with 1026. Post or release one first.
• Set your own time-outs short. The platform gives buyers' bidding endpoints a two-second budget by default, so a ping normally answers inside that plus network time. On a time-out, retry the ping with the same Idempotency-Key.

A worked example

Northwind Media sells Medicare calls to a buyer's campaign. Their platform answers a caller from Dallas at 14:03:11 and does this:

1. 14:03:11 — ping with callerId, state: "TX", sipOk: true and an Idempotency-Key. The answer is a bid: payoutCents: 2750, terms 101 and 100 with seconds: 90, expiresInSeconds: 60.
2. 14:03:12 — post the bidId with the same callerId and a new Idempotency-Key. The response times out on Northwind's side.
3. 14:03:15 — post again, same bidId. The answer is 201 with the first response: the same callId, the same sipAddress. No second call was created.
4. 14:03:16 — transfer the caller to the sipAddress. The platform recognises the bid id in the address, dials the buyer's target and the buyer answers at 14:03:24.
5. 14:06:28 — the call ends after 184 seconds of talk. That is over the 90-second term, so the call converts and Northwind is owed 2,750 cents. It shows in their portal with the payout attached.

Had the caller hung up at 14:03:13, before the post, Northwind would have sent a release, and the buyer's slot would have been free for the next caller straight away.

Next steps