add_internal_dnc Tool - Contact Center Compliance, a Sonera company

The add_internal_dnc tool manages your organization’s private Do Not Call list. Use it to add numbers when contacts request no further calls, or remove numbers when appropriate.

Parameters

string[]

required

Phone numbers in 10-digit North American format (e.g., "8663625478").

string

required

Action to perform:

add - Add numbers to Internal DNC list
remove - Remove numbers from Internal DNC list (requires an elevated role, see below)

remove requires an elevated role. The API key’s user must be a Supervisor or Administrator, unless removal has been enabled for the Agent role on your account. add is available to every role. An Agent key attempting remove fails with API_ERROR.See Internal DNC List for the underlying API.

API key. Only required if not provided via the x-dncscrub-api-key HTTP header.

string

Project ID to scope the Internal DNC list. Useful for multi-client or multi-campaign setups.

Response

boolean

Whether the API call succeeded.

string

The action that was performed: add or remove.

number

How many phone numbers were processed.

string[]

The phone numbers that were processed.

array

Array of results for each phone number, in the order they were submitted.

Show results object

string

The phone number processed.

string

Result: added, removed, already_exists, or not_found.

string

Machine-readable error code (when failed).

string

Human-readable error description (when failed).

The underlying API confirms an add or remove without saying what each number’s prior state was, so the tool reads the list immediately before changing it and reports the difference. Each status therefore reflects a snapshot taken just before the change; a concurrent edit to the same list can make it stale. results is omitted entirely if that read does not return JSON — success still tells you whether the change itself went through.

Error Codes

Code	Description
`MISSING_API_KEY`	No API key provided in header or parameter
`INVALID_API_KEY`	The API key is invalid or unauthorized
`API_ERROR`	DNCScrub API returned an error
`MISSING_INPUT`	Required parameters are missing
`INVALID_PHONE`	One or more phone numbers are invalid

Examples

Add Request
Add Response
Remove Request
Remove Response

{
  "phoneNumbers": ["5039367187", "7075276405"],
  "action": "add"
}

{
  "success": true,
  "action": "add",
  "phoneCount": 2,
  "phoneNumbers": ["5039367187", "7075276405"],
  "results": [
    { "phone": "5039367187", "status": "added" },
    { "phone": "7075276405", "status": "already_exists" }
  ]
}

{
  "phoneNumbers": ["5039367187"],
  "action": "remove"
}

{
  "success": true,
  "action": "remove",
  "phoneCount": 1,
  "phoneNumbers": ["5039367187"],
  "results": [{ "phone": "5039367187", "status": "removed" }]
}

Usage Notes

Adding a number that already exists has no effect (idempotent); results reports it as already_exists
Removing a number that isn’t on the list has no effect; results reports it as not_found
Use projId to maintain separate Internal DNC lists per project or client
Phone numbers must be exactly 10 digits without formatting

​Parameters

​Response

​Error Codes

​Examples

​Usage Notes

Parameters

Response

Error Codes

Examples

Usage Notes