> ## Documentation Index
> Fetch the complete documentation index at: https://docs.topcalls.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Block List

> Numbers your account never calls. Add them by hand, by CSV, through the API or MCP, and let the AI add anyone who asks on a call not to be called again.

Every account has a Block list. TopCalls never calls a number on it. The check runs right before each dial, so it covers campaign calls, retries, scheduled calls, test calls, calls placed through the API or MCP, and the browser dialer. A number stays on the list until an owner of your account removes it. Entries don't expire.

Open it in the dashboard under **Leads**, then **Block list**.

## How numbers get on the list

| How | Who | Shown on the list as |
| - | - | - |
| The person asks on a call not to be called again | The AI, after the call | **AI on a call**, with a **View call** link |
| **Add number** in the dashboard | Any member who can manage leads | **Added by** and the member's name |
| **Upload CSV** in the dashboard | Any member who can manage leads | **CSV** |
| `POST /v1/block-list` or the `add_to_block_list` MCP tool | Your integration or AI app | **API** |

Adding a number that's already on the list changes nothing. Its first entry, with its note and origin, stays.

## When someone asks not to be called again

You don't have to listen to calls for this. When a call ends, TopCalls reads the conversation. When the person asked not to be called again, their number goes on your Block list, and the entry links to that call so you can hear exactly what they said. From then on, no campaign or person on your team can call that number from TopCalls.

The AI only hears what's said on a call. When someone asks by email, text or to one of your people, add the number yourself, by hand, by CSV or through the API.

## Add a number by hand

**1. Open the Block list**

Go to **Leads**, then **Block list**, and select **Add number**.

**2. Enter the number**

Type it with `+` and the country code, for example `+14155551234`. Add a note if you want to remember why, such as "asked by email not to be called".

**3. Save**

Select **Block number**. It applies to the next dial.

## Upload a CSV

Select **Upload CSV** and choose your file. TopCalls reads the numbers from a column named `phone_number`, or from the first column when there's no such header. A `note` column is saved with each number.

```csv theme={null}
phone_number,note
+14155551234,Asked by email on 3 Nov
+447700900123,Former customer
```

* One upload takes up to 5,000 rows.
* Every number needs its country code.
* An upload only adds numbers. It never removes one.

When it's done, you see how many numbers were added, how many were already on the list and which rows were skipped because the number wasn't valid.

## Add numbers through the API or MCP

`POST /v1/block-list` adds up to 1,000 numbers per request, with an optional `note`. Numbers that can't be read come back in `invalid` and don't fail the request. `GET /v1/block-list` lists the entries with how each one got there. Both need an API key: `leads:write` to add, `leads:read` to list. See the [API reference](https://docs.topcalls.ai/api-reference/introduction.md).

In an AI app connected over [MCP](https://docs.topcalls.ai/mcp/tools.md), `add_to_block_list` adds up to 500 numbers at a time and `list_block_list` reads the list. If any number in an `add_to_block_list` call is missing its country code, nothing is added.

Neither the API nor MCP can remove a number.

## What a blocked call looks like

| Where the call came from | What you see |
| - | - |
| A campaign, including a retry or a scheduled call | The call shows in **Calls** with the status **On your block list**. It isn't retried and doesn't count toward the campaign's automatic pause. |
| `POST /v1/calls` | `422` with the code `on_block_list`. No call is created. |
| A test call | The test call is refused with `on_block_list`. |
| The browser dialer | The panel says the number is on your Block list and doesn't dial. |

Nothing is dialed, so a blocked call costs nothing.

## Remove a number

Only an owner of your account can remove a number, and only in the dashboard.

**1. Find the number**

Search the Block list by number or note, then select **Remove** on its row.

**2. Give a reason**

Write why it's coming off, for example "the customer asked us to call again".

**3. Confirm**

Select **Remove number**. Campaigns and the browser dialer can call it again from the next dial. TopCalls keeps the removal, who made it and the reason in your account history.

## What the Block list doesn't do

TopCalls doesn't check national do-not-call registries, such as the US National Do Not Call Registry. Consent, opt-outs that reach you outside a call, and scrubbing your lists against those registries stay with you. For US numbers, TopCalls asks you to confirm this when you import leads: see [US numbers on a lead list](https://docs.topcalls.ai/concepts/campaigns.md#us-numbers-on-a-lead-list).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.