How numbers get on the list
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 namedphone_number, or from the first column when there’s no such header. A note column is saved with each number.
- One upload takes up to 5,000 rows.
- Every number needs its country code.
- An upload only adds numbers. It never removes one.
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.
In an AI app connected over MCP, 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
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.