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 is the owner of one or more targets, the record your reports group revenue by, and the place to put a limit that should hold however many destinations that company has.

Why buyers are separate from targets

A real buyer rarely has one phone number. They have a day team and an overflow line, a SIP trunk for one state and a bidding endpoint for another vertical. Each of those is a 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, New buyer opens a drawer with the company's details, Caps across everything this buyer has and a private Notes field.

{
  "name": "Acme Health",
  "company": "Acme Health Insurance Services",
  "contactName": "Dana Reyes",
  "contactEmail": "dana@example.com",
  "contactPhone": "+12145550117",
  "timezone": "America/Chicago",
  "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",
    "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.
• 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 the columns Buyer, Status, Targets, today's figures and Caps, and filters by name, company, contact or your reference. A buyer's own page adds their targets, oldest first, with each one's health and caps.

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 one target, their Dallas floor, capped at 5 concurrent calls. For a fortnight the buyer record does nothing but hold a name.
2. Acme adds an overflow line. You add a second target under the same buyer. Now two targets 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 targets 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. Three targets leave every plan, one row changed, one entry in the activity log. On Friday you resume, and nothing needs rebuilding.

Next steps