Do Not Contact: add, remove and check entries
Search, add, remove and check entries on your Operelio Do Not Contact list over the API: how each value is matched, batch sizes, duplicates and your plan's cap.
By Operelio team · Updated October 30, 2026
On this page7
What you can do
The Operelio API keeps your Do Not Contact list in step with the systems that know who has opted out: add entries as people unsubscribe, remove one added by mistake, and check up to 100 values before you contact anyone. The CRM Formatter and every trail step that screens Do Not Contact use the same list.
Searching and checking work with any key and don't count toward your monthly API calls. Adding and removing need a read-and-write key made by an admin, and each request counts as one call, however many entries it adds. The list holds up to 25,000 entries on Pro and 100,000 on Agency.
Search the list
GET /dnc/entries lists your entries, newest first. Add search to find entries that contain some text, and valueType (email, phone, domain or company) to see one kind.
curl -G https://operelio.com/api/v1/dnc/entries \
-d search=northwind \
-H "Authorization: Bearer op_your_api_key_here"
# Response 200
{
"data": [
{
"id": "6d1c9e2a-4b7f-4a30-8e5d-2f9a1b7c3e64",
"value": "jane.cole@northwind.example",
"valueType": "email",
"label": "Jane Cole",
"reason": "Unsubscribed",
"source": "api",
"createdAt": "2026-10-30T10:02:11.000Z"
}
],
"nextCursor": null
}Add entries
POST /dnc/entries adds up to 500 entries in one request. Each entry needs a value. valueType is optional: leave it out and Operelio works it out from the value. reason is a note for your team, and label is a name to show beside the value. Neither is ever matched on.
An entry already on the list is skipped, not added twice, so you can send the same entries again safely. The response says how many were added and how many were duplicates, and gives each value's status.
curl -X POST https://operelio.com/api/v1/dnc/entries \
-H "Authorization: Bearer op_your_api_key_here" \
-H "Content-Type: application/json" \
-d '{
"entries": [
{ "value": "jane.cole@northwind.example", "label": "Jane Cole", "reason": "Unsubscribed" },
{ "value": "+44 20 7946 0958", "valueType": "phone" },
{ "value": "brightwave.example", "valueType": "domain" }
]
}'
# Response 200
{
"added": 2,
"duplicates": 1,
"invalid": 0,
"total": 2184,
"results": [
{ "value": "jane.cole@northwind.example", "valueType": "email", "status": "added", "id": "6d1c9e2a-4b7f-4a30-8e5d-2f9a1b7c3e64" },
{ "value": "+44 20 7946 0958", "valueType": "phone", "status": "added", "id": "0b7e4f21-9c3d-4a58-b6e2-5d1f8a3c7e90" },
{ "value": "brightwave.example", "valueType": "domain", "status": "duplicate" }
]
}When the entries would take the list past your plan's cap, the request returns 422 with code cap_exceeded and adds nothing. The cap is 25,000 entries on Pro and 100,000 on Agency.
How values are matched
Operelio stores each value as you sent it and also in a matching form, so small differences in how a value is written don't let someone slip through. A file or a lead matches an entry when their matching forms are the same.
| Type | How it's matched | These match |
|---|---|---|
| Lowercased, with any +tag dropped. For Gmail addresses, dots before the @ are ignored and googlemail.com counts as gmail.com. | Jane.Cole+news@Gmail.com and janecole@gmail.com | |
| phone | Digits and a leading +. A 00 prefix becomes +, a trailing extension is dropped, and a (0) after the country code is ignored. | 0044 20 7946 0958 and +44 (0)20 7946 0958 |
| domain | Lowercased, without https://, www., a path or a port. | https://www.brightwave.example/about and brightwave.example |
| company | Lowercased, without commas and periods, and with legal endings such as Inc, Ltd, LLC, GmbH or Holdings dropped from the end. | Northwind Holdings Ltd and northwind |
When you leave valueType out, a value with an @ and a dot after it counts as an email, one with at least 7 digits and only phone characters as a phone, and a web address as a domain. Anything else counts as a company. Send valueType when you know it.
Remove an entry
DELETE /dnc/entries/:id removes one entry, using the id from a search. An id that isn't on your list returns 404.
curl -X DELETE https://operelio.com/api/v1/dnc/entries/6d1c9e2a-4b7f-4a30-8e5d-2f9a1b7c3e64 \ -H "Authorization: Bearer op_your_api_key_here"
Check values before you contact anyone
POST /dnc/check takes up to 100 values and says which are on your list: suppressed is true when a value is on it (reason list) or caught by a country you block (reason country). It changes nothing, so it works with a read-only key and doesn't count toward your monthly calls. Each value is matched the way the table above describes.
curl -X POST https://operelio.com/api/v1/dnc/check \
-H "Authorization: Bearer op_your_api_key_here" \
-H "Content-Type: application/json" \
-d '{ "values": ["Jane.Cole+news@northwind.example", "tom@harbor.example"] }'
# Response 200
{
"data": [
{ "value": "Jane.Cole+news@northwind.example", "valueType": "email", "suppressed": true, "reason": "list" },
{ "value": "tom@harbor.example", "valueType": "email", "suppressed": false, "reason": null }
]
}Frequently asked questions
Does adding an entry change a record already in my CRM?
Every file Operelio screens against the list from then on leaves that person out. It doesn't change a record already in your CRM, so mark it there as well.
What happens if I add the same email twice?
The second one is skipped and counted under duplicates in the response. Two values that match the same way count as the same entry, so Jane.Cole@Gmail.com is skipped when janecole@gmail.com is already on the list.
Which plan do I need?
Do Not Contact is on Starter and up in the app, and the API is on Pro and Agency. Pro lists hold up to 25,000 entries and Agency lists up to 100,000.
Connect Operelio to your code or your assistant
Start free and add Operelio to Claude or ChatGPT today. The API and webhooks come with Pro.