Publisher ping and handoff

Separate the two connections

A publisher asks Lead Source for an opportunity. Lead Source may in turn ask configured external buyers for bids. These are different API contracts. Use the publisher.ping scope and a publisher configuration that explicitly allows the account key; confirm the campaign, publisher, and route before any live delivery.

Begin in the sandbox

POST /public/v1/publisher/ping requires Authorization and an Idempotency-Key. sandbox defaults to true and does not request live buyer bids or create a live quote. Use account-owned campaign and publisher references supplied by your integration setup. The fictional phone and references below illustrate the JSON shape only.

{
  "campaignId": "00000000-0000-4000-8000-000000000001",
  "publisherId": "00000000-0000-4000-8000-000000000002",
  "callerNumber": "+12165550123",
  "state": "OH",
  "zip": "44101",
  "sandbox": true
}

Read a sandbox response

This constructed no-winner example follows the reviewed schema; it is not a captured production response. accepted remains false and bid remains null in sandbox mode. The sample publisher terms are fictional and must not be used as a live offer.

Publisher request → eligibility and buyer evaluation → sandbox result or live quote → matching call acceptance → call completion and qualification. An expired quote or no eligible buyer stops delivery; acceptance never substitutes for a completed call.

{
  "auctionId": "00000000-0000-4000-8000-000000000003",
  "sandbox": true,
  "winner": null,
  "results": [],
  "publisherTerms": {
    "payoutCents": 6500,
    "qualifiedSeconds": 90,
    "conversionRule": "Example duration rule",
    "currency": "USD"
  },
  "expiresAt": null,
  "accepted": false,
  "bid": null
}

Interpret the result before handing off

A 200 response alone does not mean a live quote exists. In live mode, use the returned bid contract, expiry, and destination under the current schema. Never turn sandbox bids into a live request. Live mode also needs carrier setup, signing, exclusive tracking numbers, an active route, eligible buyers, and sufficient credit.

Accept only the matching call

POST /public/v1/publisher/accept uses the exact key that received the live quote. The call must match the account, campaign, publisher, and caller in the contract. Acceptance reserves the opportunity; it does not prove the call completed or that a payment was transferred. The API operation is named accept, even though the overall industry workflow is called ping/post.

Exercise the failure paths

1. No eligible bid

   Treat a no-quote result as no accepted opportunity. Do not invent a destination or promised payout.

2. Expired or changed terms

   A 410 means the quote expired. Request a new quote deliberately with a new reference. For 409 conflicts, inspect the cause before changing data or retrying.

3. Unknown response

   Retry an uncertain ping with the same reference and data. Do not generate a new reference automatically and create a second opportunity.

4. Unanswered call

   Inspect the routing timeline and qualification outcome. An accepted bid is not evidence that a buyer answered.