A buyer's destination

After this page you can add a buyer who can take a call the moment you save them, decide what their phone shows, stop a voicemail box from taking your calls, and prove the line works before a caller depends on it.

Every buyer has one destination: the place its calls ring. It is made together with the buyer, in one dialog and one save, and rewritten in place afterwards on the buyer's Destination tab. A buyer may still own further targets — a SIP trunk, a bidding endpoint — but the destination is the one line that is theirs.

Their phone, or their dashboard

Adding a buyer in one dialog

Buyers → Add a buyer writes the buyer, its destination and — when you tick it — an invitation to its dashboard, in one transaction. Whatever you leave out comes from Settings → Defaults for new buyers.

1. 1

   Who they are

   Name (unique among your buyers), company, contact, email and phone — for your team, the buyer never sees them — and Their time zone, the clock "today" is counted in on this buyer's page and dashboard.

2. 2

   Where their calls ring

   Their phone number, or The buyer dashboard (which needs the contact's email: they are invited in the same save).

3. 3

   What their phone shows as the caller

   The number the caller dialled, or Masked with one of your numbers. Never the caller's own number — see below.

4. 4

   Before the caller is put through

   Press 1 to accept (the default), Off, or Announce only.

5. 5

   When a call counts

   Qualifies at — the talk time before a call counts as qualified and is booked — and an optional Revenue per qualified call, what the buyer owes you for one. Books only: they pay you off-platform. Left empty, their calls book $0 unless a routing plan sets a price.

6. 6

   Invite them to the buyer dashboard now

   Optional for a phone destination, required for the dashboard. They get an email with a link, choose a password, and can watch their calls. Their phone rings either way.

{
  "name": "Acme Roofing",
  "company": "Acme Roofing LLC",
  "contactName": "Jane Doe",
  "contactEmail": "jane@acmeroofing.example",
  "timezone": "America/Phoenix",
  "revenueCents": 3500,
  "destination": {
    "type": "phone",
    "e164": "+16025550131",
    "callerIdPolicy": "fixed",
    "callerIdNumberId": "0c4d2e1f-9a8b-4c7d-8e6f-5a4b3c2d1e0f",
    "whisperMode": "press_to_accept",
    "thresholdSeconds": 90
  },
  "invite": {
    "email": "jane@acmeroofing.example",
    "name": "Jane Doe"
  }
}

{
  "buyer": {
    "id": "f1e2d3c4-b5a6-4978-8a9b-0c1d2e3f4a5b",
    "name": "Acme Roofing",
    "status": "active",
    "primaryTargetId": "a9b8c7d6-e5f4-4a3b-9c2d-1e0f9a8b7c6d",
    "destination": {
      "type": "phone",
      "e164": "+16025550131",
      "seatName": null,
      "ready": true,
      "reason": null
    },
    "seats": {
      "active": 0,
      "invited": 1
    },
    "…": "…"
  },
  "destination": {
    "type": "phone",
    "e164": "+16025550131",
    "callerIdPolicy": "fixed",
    "callerIdNumber": {
      "id": "0c4d2e1f-9a8b-4c7d-8e6f-5a4b3c2d1e0f",
      "e164": "+18005550100",
      "formatted": "(800) 555-0100",
      "ready": true
    },
    "whisperMode": "press_to_accept",
    "ringTimeoutSeconds": 20,
    "thresholdSeconds": 90,
    "ready": true,
    "reason": null,
    "changedBy": {
      "name": "Sam Ortiz",
      "via": "publisher"
    },
    "…": "…"
  },
  "invitation": {
    "id": "8e7d6c5b-4a39-4827-9615-04938271650a",
    "kind": "buyer",
    "email": "jane@acmeroofing.example",
    "status": "pending",
    "emailed": true
  }
}

• A buyer counts against your plan's buyer allowance; its own destination counts against neither the target nor the delivery-endpoint allowance. The sixth buyer on a plan that allows five is refused before anything is written.
• A phone destination can take a call at once. Put the buyer on a campaign's routing plan and calls start reaching it.
• If the default caller-ID number has stopped being usable since you chose it, the buyer is saved showing the tracking number instead and the answer carries a warnings line saying so. A number you named in the request itself is checked strictly: another account's number, or one that cannot be presented, is a 404.

What their phone shows as the caller

The caller's number is yours until the call has qualified — and the carrier refuses to present a number your account does not own. So a buyer's phone is shown one of two numbers, never a third:

Press 1 to accept

A plain transfer puts the caller through to whatever answers — a voicemail box included, and a voicemail box that stays on the line long enough qualifies the call. Press 1 to accept is the default for a phone destination because it is the only setting that tells a person from a machine.

• The prompt is your own whisper text when you wrote one (a whisper that never names the key has "Press 1 to accept" added), else "Call from <campaign>." They have about eight seconds to press the key.
• The call counts as answered only at the moment they accept. Talk time, the qualifying timer, the recording and the buyer's win all start there, so a voicemail box can never qualify a call.
• A decline shows in the waterfall as Declined at the whisper, and counts nothing against the buyer's line: it is not a failed ring.
• It applies to a phone destination only. The dashboard answers in the browser by itself, and Announce only is saved but not played yet — the caller is put through without the announcement.

When a call qualifies

Qualifies at is the talk time a call must reach before it counts: it converts, books the buyer's revenue and your sub-publisher's payout, and — where you allow it — shows the buyer the caller's full number. It is the destination's own threshold (0 to 7,200 seconds on the tab; the account default is 30), frozen onto each call when it is dialled, and a route on a routing plan that sets its own threshold still wins.

The Destination tab

The buyer page's Destination tab is the editor for everything above. Switching between phone and dashboard changes the same destination in place: its history, its caps and every routing plan it is on stay. The last save wins — yours here, or the buyer's own seat changing it from their dashboard — and the tab says who changed it last.

Ready, or why not

Every buyer row says whether its destination could take a call right now, and if not, why — the same question the router asks of it on a real call. A reason about the moment (outside hours, a cap reached) is not one of these: those are about the call, not the line.

Send a test call

Send a test call on the Destination tab rings the destination for real, once: from the buyer's caller-ID number (or your first number that can make a call), to their phone or their browser. Whoever answers hears "This is a test call from <your account>" and the line is hung up. The button waits for the end — up to about a minute and a half — and says what happened.

{
  "outcome": "answered",
  "rangSeconds": 4,
  "cause": null,
  "detail": "Acme Roofing's phone answered and heard the test message."
}

• Not a call. No call row, no charge, nothing in your reports. It is written to the buyer's activity with its outcome.
• Once a minute per buyer — a second is 429 rate_limited with how long to wait.
• A browser is rung only when a real call would ring it — otherwise 409 seat_not_ready names why, in the words of the table above.
• Refused before anything rings: an archived buyer, no destination, their seat's own mobile while mobile delivery is switched off (409 mobile_not_allowed — a real call would skip it too), no number of yours to call from (409 no_caller_id_number), or telephony not set up.

Numbers that reach a buyer

A number reaches a buyer when the campaign it belongs to has the buyer on its routing plan. That is worked out from the plan, never stored on the number — move a route and the answer moves with it. The buyer page's Numbers tab lists them, and Buy a number there is the ordinary purchase (billed to you, as every number is), followed by assigning it to a campaign that routes to this buyer. When no campaign does yet, the tab drafts one: a draft campaign whose routing plan is one route to this buyer. Setting it live is still the campaign's own step.

The setup checklist

Until your first qualified call, Overview shows five steps, each ticked from what your account actually holds — nothing is ticked by hand: Buy a number, Create a campaign, Add a buyer, Route a campaign to a buyer, Take the first qualified call. Once a call qualifies the checklist goes away for good.

Next steps