Repeat and blocked callers

After this guide you will be able to decide what happens to somebody who has called before, refuse callers who withhold their number, block a number across the workspace or on one campaign, and tell those three apart from the duplicate window that lives on a target.

Three settings deal with who is calling rather than what the call is worth. All three are gates: they run before any target is considered, so a call they stop is never offered to a buyer, never counts against anybody's cap and never costs you a connected minute.

Repeat callers

A repeat caller is somebody who has already reached a buyer on this campaign. "Reached" means a buyer's line answered them: a caller whose first try rang out is trying again, not repeating, and is treated as new.

• The look-back is the campaign's duplicate window (dedupeWindowSeconds), 0 to 90 days. 0 means for ever — every call this caller has ever made to the campaign counts.
• A caller who hid their number cannot be matched against anything, so the policy does not apply to them. The anonymous policy is the setting for those.
• same_target only reorders the plan. It does not force the call through: if that target is paused, closed, capped or full, the plan stands as it was drawn and the call goes to whoever is next.
• A blocked repeat call is still written to the call log, with the date of the earlier call in its sentence: "This caller already called the campaign on 2026-09-14, and the campaign blocks repeat callers."

The duplicate window is something else

Two settings share the words "duplicate" and "window" and they are not the same rule. Confusing them is the commonest reason a plan does not behave as expected.

A target's window is in its editor, under Duplicates, as Do not send the same caller again within, with buttons for an hour, 24 hours, 7 days and 30 days. Like the campaign's, it counts only calls that target actually answered — ringing a buyer who was not there does not burn the caller's window with them.

Anonymous callers

A caller is anonymous when the carrier sent no usable number: nothing at all, fewer than seven digits, or a word such as *anonymous*, *restricted*, *private*, *unavailable*, *unknown* or *withheld*.

• Such a caller cannot be looked up on the blocklist, cannot be matched to an earlier call and has no area code, so the platform knows no state for them.
• The anonymous-caller policy (anonymousPolicy) is allow — the default — or block. When it is block, the call ends with anonymous_blocked.
• When it is allow, the call is routed like any other. Targets that accept only certain states do not skip it: an unknown state is never read as "not in my states", or every withheld and toll-free caller would go to nobody.

Blocked callers

The Blocked callers list holds numbers you never want routed: somebody who has complained, a competitor checking your buyers, a number that calls thirty times a day. An entry applies either to the whole workspace or to one campaign.

• A number is stored as its last ten digits, so +1 (214) 555-0143, 214-555-0143 and 2145550143 are one caller. Any spelling with 7 to 15 digits is accepted when you add one.
• The reason you write is kept on the block and shown beside every call it refuses, so whoever reads the call log in three months knows why this number never gets through.
• A blocked call still appears in the call log and in your reports, with the reason caller_blocked. Nothing is hidden: a publisher asking where their caller went can be shown exactly what happened.
• Blocking costs nothing. An unrouted call books no revenue, owes no payout and is never charged a connected minute.

In the console, Blocked callers lists them with the columns Caller, Blocked on, Why and Since, and tiles counting the numbers blocked on every campaign and on one campaign. Block a caller takes the number, the scope and the reason.

From the API

Blocking is one of the few writes an API key can do, because it is the one that has to happen at three in the morning when a complaint arrives. The scope is blocklist:write, and it also opens the list and the delete.

{
  "callerNumber": "+1 (214) 555-0143",
  "campaignId": null,
  "reason": "Complained twice — do not sell this number on"
}

curl -X POST "https://api.buy3.io/api/v1/blocked-callers" \
  -H "Authorization: Bearer $BUY3_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "callerNumber": "+12145550143", "reason": "Complained twice" }'

{
  "blockedCaller": {
    "id": "3f2e1d0c-9b8a-4756-8493-2a1b0c9d8e7f",
    "callerLast10": "2145550143",
    "formatted": "(214) 555-0143",
    "scope": "workspace",
    "campaign": null,
    "reason": "Complained twice — do not sell this number on",
    "createdAt": "2026-09-20T09:41:30.000Z"
  },
  "created": true
}

• Send a campaignId to block on one campaign only; leave it out, or send null, for the whole workspace.
• Blocking somebody who is already blocked at that scope answers 200 with the existing row and created: false, so a retry is safe. In the console the same act answers 409.
• DELETE /api/v1/blocked-callers/{id} unblocks. There is no edit: remove the entry and add it again with the reason you meant.
• Every block and unblock is written to the activity log.

Worked example: the same caller, three campaigns

A caller on +1 214 555 0143 reaches your Medicare line on Monday and is sold to Acme Health. On Tuesday they ring three of your numbers:

1. The same Medicare number. The campaign's policy is same_target and its duplicate window is 30 days, so Monday's call is inside it. Acme Health — Dallas floor is moved to the front of the plan and takes the call again.
2. Your legal campaign, whose policy is block with a window of 0. They have never reached a buyer on that campaign, so 0 — for ever — finds nothing and the call is routed normally.
3. Your insurance campaign, after you have blocked them at workspace scope. The call ends at the blocklist gate with caller_blocked, before hours, caps or the plan are looked at. It is in the call log with your note beside it.

Had Acme's target carried a 24-hour duplicate window of its own, Tuesday's Medicare call would have skipped Acme with duplicate and gone to the next buyer instead — one target passed over, not the call refused.

Checking it before a caller does

Simulate a call takes a caller number and shows every gate with a tick or a cross, so you can confirm a block is in force, or that a number you expected to be blocked is not. A simulation is also the quickest way to see same_target doing its work: the target that took the caller last time appears first in the plan.

Next steps