# Number lists

An inbound **Number List** filters calls by the caller's number (CLI). Assign a
Number List to an inbound [SIP trunk](../sip-trunks/index.html) or
[PSTN trunk](../pstn-trunks/index.html) to allow or reject calls from specific
numbers or prefixes before they reach your destination.

Each Number List has a **Mode** that defines how its items are matched, a set of
items with their own **Action**, and a **Default Action** for callers that no
item matches. Create and manage Number Lists under **Voice > Inbound Trunks >
Number Lists**.

## How number lists work

When a call arrives on a trunk with an assigned Number List, DIDWW compares the
caller's number with the list items according to the list's **Mode**:

- **Full number match** matches only an item identical to the complete calling
  number.
- **Prefix match** matches an item whose digits appear at the beginning of the
  calling number, provided the complete calling number meets the item's
  **Min. Length** and **Max. Length** limits.

If an item matches, its **Action** allows or rejects the call. If no item
matches, the list's **Default Action** applies.

```
        %%{init: {
  "theme": "base",
  "themeVariables": {
    "fontSize": "14px",
    "primaryColor": "#e0f2fe",
    "primaryBorderColor": "#38bdf8",
    "primaryTextColor": "#1f2d3d",
    "secondaryColor": "#ccfbf1",
    "secondaryBorderColor": "#2dd4bf",
    "secondaryTextColor": "#1f2d3d",
    "lineColor": "#0066cc",
    "textColor": "#1f2d3d",
    "nodeTextColor": "#1f2d3d",
    "edgeLabelBackground": "#ffffff"
  }
}}%%

flowchart LR

    caller["Caller"] --> |dials DID| trunk["SIP or PSTN trunk"]
    trunk --> list{"Item matches<br>caller's number?"}
    list --> |yes| item["Item Action"]
    list --> |no| default["Default Action"]
    item --> result["Call allowed or rejected"]
    default --> result

    classDef endpoint fill:#e0f2fe,stroke:#0066cc,color:#1f2d3d,stroke-width:1.5px
    classDef process fill:#ccfbf1,stroke:#2dd4bf,color:#1f2d3d,stroke-width:1.5px

    class caller,result endpoint
    class trunk,list,item,default process

    linkStyle default stroke:#0066cc,stroke-width:1.5px
```

## Allow and block lists

Combine the **Default Action** with item actions to build either a blocklist
or an allowlist.

| Objective | Configuration | Behavior |
| --- | --- | --- |
| Block specific callers | Set **Default Action** to **Allow call** and add items with **Reject call**. | DIDWW rejects calls from the listed numbers or prefixes and allows all other calls. |
| Allow only specific callers | Set **Default Action** to **Reject call** and add items with **Allow call**. | DIDWW allows calls from the listed numbers or prefixes and rejects all other calls. |

## Number lists and trunks

Assign a Number List in the trunk's **CLI Number List** field on the **Number
Translations** tab. Each trunk can use one Number List, and the same list can
be assigned to multiple trunks.

- For a SIP trunk, the list is matched against the caller's number after the
  trunk's **CLI Format** and **CLI Prefix** are applied. If you change those
  settings, update the list items to the new format.
- For a PSTN trunk, the list is matched against the caller's number presented
  to the PSTN destination.

A Number List that is assigned to a trunk cannot be deleted. To find the trunks
that use a list, filter the **Trunks** tab by **CLI Number List**.

---

## Get started

Create a list, add its filtering rules, then assign it to a SIP or PSTN trunk.

**Create a number list**

Choose how caller numbers are matched and what happens when no
rule matches.

[1. Create a Number List](how-to-guides/configure-number-lists.html#inbound-number-lists-create)

**Add numbers or prefixes**

Add full numbers or prefixes and choose whether matching calls
are allowed or rejected.

[2. Add and Configure Numbers in the Number List](how-to-guides/configure-number-lists.html#inbound-number-lists-add-numbers)

**Assign the list to a trunk**

Apply the list to a SIP or PSTN trunk to start filtering incoming calls.

[3. Assign a Number List to a Trunk](how-to-guides/configure-number-lists.html#inbound-number-lists-assign)

## Manage lists and rules

Update list settings or change individual filtering entries.

**Manage number lists**

Change the list's name, matching mode, or default action, or delete
an unused list.

[Manage number lists](how-to-guides/manage-number-lists.html)

**Edit numbers and prefixes**

Update numbers, prefixes, and their allow or reject actions.

[Edit Numbers in a Number List](how-to-guides/manage-number-lists.html#inbound-number-lists-edit-numbers)

## Example configurations

Choose an example that matches the filtering or routing you need.

**Block a phone number**

Reject incoming calls from a specific caller number.

[Block a phone number](use-cases/block-phone-number.html)

**Block calls from a prefix**

Reject calls whose caller numbers begin with a specified prefix.

[Block calls from a prefix](use-cases/block-calls-from-prefix.html)

**Allow calls from selected countries**

Allow calls from chosen country-code prefixes and reject other callers.

[Allow calls from selected countries](use-cases/allow-calls-from-countries.html)

**Route callers by prefix**

Use caller prefixes to route calls through different SIP trunks
in a trunk group.

[Use number lists for load balancing](use-cases/use-number-lists-for-load-balancing.html)

## References and troubleshooting

Look up matching settings and investigate calls rejected by filtering.

**Number list settings reference**

Find fields, defaults, matching modes, entry actions, and number
length limits.

[Number List settings reference](number-list-settings-reference.html)

**Check calls rejected by a number list**

Check filtering rules for calls marked **Rejected by trunk settings**
in Inbound Call Logs.

[Call Logs & Number List Rejection Codes](how-to-guides/configure-number-lists.html#inbound-number-lists-reject-code)

On this page