Buyers

After this guide you will be able to add the companies you sell to, put a limit where it belongs to the company rather than to one phone line, pause a buyer for a holiday without touching their destinations, and find the figures you invoice them from.

A buyer is a company you sell calls to. It has one destination — their phone, or their dashboard — made with it in one dialog, so it can take a call the moment it is saved; see A buyer's destination. It may own further targets too, and it is the record your reports group revenue by and the place to put a limit that should hold however many lines that company has.

Why buyers are separate from targets

A buyer's own destination is where most of their calls ring. But a real buyer can also have an overflow line, a SIP trunk for one state or a bidding endpoint for another vertical, and each of those is a further target. The buyer is what they have in common — and what they have in common is usually a budget and a contract.

Adding one

Under Buyers, Add a buyer is one dialog and one save: who they are, where their calls ring, what their phone shows as the caller, press 1 to accept, when a call counts, and — ticked — an invitation to their dashboard. The buyer, its destination and the invitation are written together or not at all, and a buyer with a phone destination can take a call at once. The destination half is A buyer's destination; whatever you leave out comes from Settings → Defaults for new buyers.

{
  "name": "Acme Health",
  "company": "Acme Health Insurance Services",
  "contactName": "Dana Reyes",
  "contactEmail": "dana@example.com",
  "contactPhone": "+12145550117",
  "timezone": "America/Chicago",
  "revenueCents": 4200,
  "destination": {
    "type": "phone",
    "e164": "+12145550188",
    "callerIdPolicy": "tracking_number",
    "whisperMode": "press_to_accept",
    "thresholdSeconds": 90
  },
  "invite": {
    "email": "dana@example.com",
    "name": "Dana Reyes"
  }
}

Caps, your reference and notes are on the buyer's Edit once it exists — PATCH /api/tracking/buyers/:id:

{
  "concurrencyCap": 12,
  "hourlyCap": 0,
  "dailyCap": 120,
  "monthlyCap": 2400,
  "dailyRevenueCapCents": 500000,
  "externalRef": "ACC-10044",
  "notes": "Net 15. Invoice from the converted-calls report on the 1st."
}

Buyer caps hold across every target

A buyer's caps and a target's caps are both tested for every call, and the tighter of the two stops it. A target skipped for the buyer's cap shows buyer_capped, and the waterfall names the company: "The buyer Acme Health has reached its daily cap of 120 calls."

• The buyer's concurrency slot is taken at the dial, atomically, straight after the target's. If the buyer is full the target's slot is handed straight back and the call moves on.
• The buyer's hourly, daily and monthly counters move at the same moment as the target's, decided by that target's A cap counts a call setting.
• The buyer's daily revenue cap counts money at settlement, and has no code of its own: a buyer full for the day reads as buyer_capped.
• The windows roll in UTC, like every other cap window. See Windows roll over in UTC.
• A buyer has no hours. Opening times belong to a target, because a company with two rooms may staff them differently.

{
  "buyer": {
    "id": "f1e2d3c4-b5a6-4978-8a9b-0c1d2e3f4a5b",
    "name": "Acme Health",
    "company": "Acme Health Insurance Services",
    "status": "active",
    "timezone": "America/Chicago",
    "concurrencyCap": 12,
    "hourlyCap": 0,
    "dailyCap": 120,
    "monthlyCap": 2400,
    "dailyRevenueCapCents": 500000,
    "usage": {
      "liveCalls": 7,
      "hour": 19,
      "day": 96,
      "month": 1840,
      "total": 24187,
      "dayRevenueCents": 403200
    },
    "liveCalls": 7,
    "externalRef": "ACC-10044",
    "primaryTargetId": "a9b8c7d6-e5f4-4a3b-9c2d-1e0f9a8b7c6d",
    "destination": {
      "type": "phone",
      "e164": "+12145550188",
      "seatName": null,
      "ready": true,
      "reason": null
    },
    "seats": {
      "active": 1,
      "invited": 0
    },
    "targets": {
      "total": 3,
      "active": 3
    },
    "today": {
      "calls": 141,
      "connected": 108,
      "converted": 62,
      "connectRate": 0.766,
      "conversionRate": 0.5741,
      "revenueCents": 403200,
      "payoutCents": 264000
    }
  }
}

Read usage against the caps above it: 7 of 12 lines busy, 96 of 120 calls today, $4,032 of $5,000 of revenue booked. The console draws each as a bar, amber from 80 per cent and red at 100. total is the lifetime count of calls counted against this buyer: a figure rather than a limit, since a buyer has no lifetime cap.

Status

Pausing a buyer changes one row. None of their targets is written to: each simply becomes ineligible until the buyer is resumed, and resuming puts them all back exactly as they were. The response tells you how many targets that touched:

{
  "buyer": {
    "id": "f1e2d3c4-b5a6-4978-8a9b-0c1d2e3f4a5b",
    "name": "Acme Health",
    "status": "paused"
  },
  "changed": true,
  "targetsAffected": 3
}

• Setting a status a buyer already has answers changed: false and does nothing.
• Restoring an archived buyer re-checks your plan's allowance, so it can answer 402, and is refused with a 409 if the name has been taken in the meantime.
• Restoring an archived buyer brings its destination back with it. Archiving took the buyer off every routing plan, and those routes stay off — put the buyer back on its campaigns. The destination itself cannot be archived while its buyer is in use.
• Every status change is written to the activity log, with an optional note of up to 500 characters.

Money and buyers

The platform records what each buyer owes you, call by call, and never collects it. When a call converts, its revenue is stamped on the call and counted against the buyer — and no wallet moves, because your buyers pay you directly. That is what books-only money means.

• A call converts when the buyer's leg talked for at least the target's duration threshold, or when a conversion is posted for it.
• Revenue is what the buyer owes you. Payout is what you owe the publisher. The difference is your margin, and all three are stored per call in whole cents.
• Group the report builder by buyer for the figures to invoice from, and export the same rows as CSV.
• The only thing the platform charges your workspace is its own usage — connected minutes and number rent. Your buyers' money is never held here.

Reading the buyers list

The Buyers page lists them with their status, where their calls ring (and whether it could take a call now), their seat (held, or invited), how many are on a call now, calls today with how many qualified, and revenue today; it filters by name, company, contact or your reference. A buyer's own page has the tabs Overview, Destination, Seats, SMS alerts, Numbers, Calls and Activity.

curl "https://api.buy3.io/api/v1/buyers?status=active&pageSize=50" \
  -H "Authorization: Bearer $BUY3_API_KEY"

An API key with buyers:read can read buyers, their caps and their targets. Creating, editing and pausing a buyer are acts for a person in the console — a key cannot do them. Full request and response shapes are in the Buyers API reference.

Worked example: a buyer who outgrows one number

1. You add Acme Health with no caps at all and their Dallas floor as its destination. For a fortnight the buyer record does little but hold a name and a phone number.
2. Acme adds an overflow line. You add a target under the same buyer. Now two lines share one company, and your reports still show one row for Acme.
3. Acme says "no more than 120 a day, across everything". That is a fact about the company, so it goes on the buyer: dailyCap: 120. The targets keep their own concurrency limits, because those are about phone lines.
4. At 96 calls the buyer's bar is amber. At 120 both lines start being skipped with buyer_capped and the calls go to your next buyer instead — which is exactly what the routing plan is for.
5. Acme closes for Thanksgiving. You pause the buyer. Both lines leave every plan, one row changed, one entry in the activity log. On Friday you resume, and nothing needs rebuilding.

Next steps