Allow only known callers

An allow list is a policy that screens inbound calls. Only the callers on the list ring through, and every other inbound call is declined before it connects: it isn’t answered, no AI voice agent runs, and nothing is billed. Calls you place and messages aren’t affected.

A list covers either every number on the account, including numbers you add later, or a set of numbers you choose. You can manage lists in the dashboard under Policies, or with the API, CLI, MCP tools and SDKs.

Which list applies to a number

• A number’s own list replaces the account-wide list on that number. The two never combine.
• An account has at most one account-wide list, and a number can be on at most one list of its own. Trying to create a second of either is refused with 409 (account_policy_exists or number_policy_conflict).
• A list that’s turned off counts as if it weren’t there. A number whose own list is off falls back to the account-wide list, if there is one.
• Only numbers that can take calls can be put on a list.

Each phone number reports the list that screens it right now as inboundCallPolicy (or null when every caller rings through).

Create an allow list

Callers are matched on their exact E.164 number. Paste numbers in full international format, without a national trunk 0 (+44 20 7946 0958, not +44 020…; a (0) after the country code is dropped for you). 10-digit numbers are read as US, and a number that can’t be a real US number is refused rather than stored.

# Every number on the account
dial policy create --name "Known customers" --all-numbers \
  --allow +14155550123 --allow +442079460100
# Just two numbers
dial policy create --name "Field team only" --number +14155550155 --number "Appointment reminders" \
  --allow +14155550311

Add and remove callers

You don’t have to resend the whole list to change one caller.

dial policy allow pol_123 +14155550199 --label "Sam Ortiz"
dial policy disallow pol_123 +14155550199

To pause a list without deleting it, set enabled to false (dial policy update pol_123 --off).

What a declined call looks like

A declined call is still recorded, so you can see who tried to reach you:

• It appears in Voice Calls and in List calls with status.terminationType blocked (label “Blocked”) and blockedByPolicyId set to the list that declined it.
• It emits a single call.status_changed (Terminated, previousState: null) and a call.ended with status: "blocked", so agents and webhooks waiting on calls learn about it.
• Each list reports how many calls it declined in the last 7 days as blockedCallsLast7Days.
• Blocked calls don’t count toward contacts or usage, and they are never billed.

A caller with a hidden or withheld caller ID can’t match any entry, so it’s declined on every number a list covers.