Publishers overview

After this page you can add a publisher, open a lane for them on a campaign, hand them the credential that lane mints, and read what the lane is doing. You will also know what happens to their traffic when you pause a lane, remove one, or take a publisher off the air.

A publisher is a partner who sends you calls — an affiliate, a media buyer, another network. Calls from media you run yourself have no publisher and no payout; everything on this page is about traffic somebody else generates and expects to be paid for.

Two ways a publisher sends calls

The publisher account

A publisher is an account with a lifecycle, not a label on a key. It carries a name, a contact, a time zone, a payout schedule and a status, and the status is checked on every ping.

The account also holds a time zone, which is the clock their own portal counts "today" on, and a payout schedule and method, which are a record of what you agreed rather than anything the platform acts on. See Payout terms.

Lanes

A publisher does not join a workspace in general; they join a campaign. That pairing is a lane, and it is where everything specific to this publisher on this campaign lives. Open one from the campaign's Publishers tab, or with PUT /api/tracking/campaigns/{id}/publishers/{publisherId}.

Because terms sit on the lane, the same publisher can be on a fixed payout for one campaign and a revenue share for another, and changing one never touches the other. The terms in force when a call starts are frozen onto that call, so a later change never rewrites a statement the publisher has already seen.

A lane mints its own key

Opening a lane issues the publisher's routing key in the same request, because a price agreed with a partner who has no way to send a call is not an agreement. The key comes back once, in the response that created the lane, and cannot be read back from that door afterwards.

curl -X PUT "https://api.buy3.io/api/tracking/campaigns/6a2d1f0e-8b7c-4c55-a1d3-0e9f8a7b6c5d/publishers/c4e1a2b3-9d8f-4f6e-b5a4-1c2d3e4f5a6b" \
  -H "Authorization: Bearer $BUY3_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "active": true,
    "payoutMode": "fixed",
    "payoutCents": 2750,
    "bufferSeconds": 60,
    "dailyCap": 200,
    "concurrencyCap": 5,
    "states": ["TX", "OK", "NM"],
    "notesPublic": "Weekday daytime only. No lead-form call-backs."
  }'

{
  "lane": { "campaignId": "6a2d1f0e-…", "publisherId": "c4e1a2b3-…", "active": true, "payoutMode": "fixed", "payoutCents": 2750 },
  "created": true,
  "key": "b3k_live_9f2a4c7e1d0b8a6f5e4d3c2b1a09f8e7",
  "keyNote": "Store this routing key now — it is shown only once. Send it to the publisher with the ping URL."
}

• A key opened from the campaign's Publishers tab speaks the auction protocol (rtb_v1), because that is the surface a tracking campaign can answer on.
• An existing lane is left alone. Editing a cap never re-keys a live publisher, which would take their traffic down. Rotation is its own action — see Keys and security.
• There is one live key per lane. Issuing a second is refused until the first is revoked or rotated.
• A lane whose publisher only advertises tracking numbers never uses its key. That is not a fault: their calls arrive by being dialled, not by being pinged.

{
  "lane": {
    "campaignId": "6a2d1f0e-8b7c-4c55-a1d3-0e9f8a7b6c5d",
    "publisherId": "c4e1a2b3-9d8f-4f6e-b5a4-1c2d3e4f5a6b",
    "publisher": { "id": "c4e1a2b3-9d8f-4f6e-b5a4-1c2d3e4f5a6b", "name": "Northwind Media", "status": "live" },
    "active": true,
    "payoutMode": "fixed",
    "payoutCents": 2750,
    "revsharePct": null,
    "minPayoutCents": null,
    "maxPayoutCents": null,
    "bufferSeconds": 60,
    "effectiveBufferSeconds": 60,
    "dedupeWindowSeconds": 86400,
    "hourlyCap": 0,
    "dailyCap": 200,
    "monthlyCap": 0,
    "concurrencyCap": 5,
    "dailyPayoutCapCents": 0,
    "blockWhenCapped": true,
    "states": ["TX", "OK", "NM"],
    "hoursSchedule": null,
    "timezone": "America/Chicago",
    "notesPublic": "Weekday daytime only. No lead-form call-backs.",
    "usage": { "liveCalls": 1, "hour": 4, "day": 37, "month": 611, "dayPayoutCents": 99000 },
    "key": {
      "id": "b7c8d9e0-1a2b-4c3d-8e4f-5a6b7c8d9e0f",
      "prefix": "b3k_live_9f2a",
      "state": "live",
      "protocol": "rtb_v1",
      "environment": "production",
      "requireSignature": false,
      "lastUsedAt": "2026-09-20T13:58:02.000Z",
      "useCount": "48211",
      "issuedAt": "2026-09-01T09:00:00.000Z"
    },
    "numbers": 2,
    "compat": { "enabled": false, "url": null },
    "assignedAt": "2026-09-01T09:00:00.000Z",
    "termsFrozenAt": "2026-09-18T16:22:41.000Z"
  },
  "created": false
}

Pausing, and removing

The three ways to stop a publisher's traffic are not the same, and the difference matters to both sides.

Removing a lane does not touch the tracking numbers assigned to that publisher on that campaign. They are your numbers, callers are still dialling them, and the platform tells you the count rather than silently switching off advertising you paid for. Reassign or unassign them from Numbers.

Reading a lane in the console

Open the campaign and choose Publishers. The Publisher lanes table has one row per lane:

A worked example

Northwind Media want to send Texas calls to your Acme Health inbound campaign. They have their own dialler and want to ping for a price.

1. Add the publisher. Name, contact and time zone. The account starts onboarding, so nothing it sends would be accepted yet.
2. Open the lane on Acme Health inbound: a fixed payout, Earns after 60 seconds, a daily cap of 200, five simultaneous calls, states TX, OK and NM. The response carries the routing key, once.
3. Send them the key and point them at Ping and post. If their platform can only call a single URL, switch on the single-step ping URL for the lane instead.
4. Set the publisher live. Their first ping is scored, and lands in the ping ledger whether it wins or not.
5. Watch the first afternoon. Their no-bids are all 1008 state_not_targeted — they are sending Arkansas too. Either they filter, or you add AR to the lane.

Two weeks later quality slips on one source. You lower the daily cap to 50 and write the reason into Shown to the publisher; they read it in their portal, and the change — old value and new — is on your activity log and on theirs.

Next steps