> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.getdial.ai/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.getdial.ai/_mcp/server.

# Allow only known callers

> Decline inbound calls from anyone who isn't on an allow list — on every number, or just a few.

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.

> **Note**
>
> An allow list screens on the caller ID the network presents, and caller ID can be spoofed. Use it to keep unwanted callers out, not as proof of who is calling.

**`CLI`**

```bash title="CLI"
# 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
```

**`Node`**

```typescript title="Node"
const policy = await dial.createPolicy({
  name: "Known customers",
  scope: "account",
  entries: [{ number: "+14155550123", label: "Jordan Lee" }],
});
```

**`Python`**

```python title="Python"
policy = await dial.create_policy(
    name="Known customers",
    scope="account",
    entries=[{"number": "+14155550123", "label": "Jordan Lee"}],
)
```

**`cURL`**

```bash title="cURL"
curl https://api.getdial.ai/v1/policies \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Known customers",
    "scope": "account",
    "entries": [{ "number": "+14155550123", "label": "Jordan Lee" }]
  }'
```

> **Warning**
>
> An enabled list with no callers on it declines **every** inbound call on the numbers it covers.

## Add and remove callers

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

**`CLI`**

```bash title="CLI"
dial policy allow pol_123 +14155550199 --label "Sam Ortiz"
dial policy disallow pol_123 +14155550199
```

**`cURL`**

```bash title="cURL"
curl -X POST https://api.getdial.ai/v1/policies/pol_123/entries \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{ "entries": [{ "number": "+14155550199", "label": "Sam Ortiz" }] }'

curl -X DELETE https://api.getdial.ai/v1/policies/pol_123/entries \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{ "numbers": ["+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](/api-reference/calls/list-calls) with `status.terminationType` `blocked` (label "Blocked") and `blockedByPolicyId` set to the list that declined it.
* It emits a single [`call.status_changed`](/api-reference/events/call-status-changed) (`Terminated`, `previousState: null`) and a [`call.ended`](/api-reference/events/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](/api-reference/contacts/list-contacts) or [usage](/api-reference/usage/get-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.