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

# add_internal_dnc Tool

> Add or remove phone numbers from your Internal DNC list

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

<ParamField body="phoneNumbers" type="string[]" required>
  Phone numbers in 10-digit North American format (e.g., `"8663625478"`).
</ParamField>

<ParamField body="action" type="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)
</ParamField>

<Note>
  **`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](/api-reference/scrub/internal-dnc) for the underlying
  API.
</Note>

<ParamField body="loginId" type="string">
  API key. Only required if not provided via the `x-dncscrub-api-key` HTTP header.
</ParamField>

<ParamField body="projId" type="string">
  Project ID to scope the Internal DNC list. Useful for multi-client or multi-campaign setups.
</ParamField>

## Response

<ResponseField name="success" type="boolean">
  Whether the API call succeeded.
</ResponseField>

<ResponseField name="action" type="string">
  The action that was performed: `add` or `remove`.
</ResponseField>

<ResponseField name="phoneCount" type="number">
  How many phone numbers were processed.
</ResponseField>

<ResponseField name="phoneNumbers" type="string[]">
  The phone numbers that were processed.
</ResponseField>

<ResponseField name="results" type="array">
  Array of results for each phone number, in the order they were submitted.

  <Expandable title="results object">
    <ResponseField name="phone" type="string">
      The phone number processed.
    </ResponseField>

    <ResponseField name="status" type="string">
      Result: `added`, `removed`, `already_exists`, or `not_found`.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="errorCode" type="string">
  Machine-readable error code (when failed).
</ResponseField>

<ResponseField name="errorMessage" type="string">
  Human-readable error description (when failed).
</ResponseField>

<Note>
  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.
</Note>

## 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

<Tabs>
  <Tab title="Add Request">
    ```json theme={null}
    {
      "phoneNumbers": ["5039367187", "7075276405"],
      "action": "add"
    }
    ```
  </Tab>

  <Tab title="Add Response">
    ```json theme={null}
    {
      "success": true,
      "action": "add",
      "phoneCount": 2,
      "phoneNumbers": ["5039367187", "7075276405"],
      "results": [
        { "phone": "5039367187", "status": "added" },
        { "phone": "7075276405", "status": "already_exists" }
      ]
    }
    ```
  </Tab>

  <Tab title="Remove Request">
    ```json theme={null}
    {
      "phoneNumbers": ["5039367187"],
      "action": "remove"
    }
    ```
  </Tab>

  <Tab title="Remove Response">
    ```json theme={null}
    {
      "success": true,
      "action": "remove",
      "phoneCount": 1,
      "phoneNumbers": ["5039367187"],
      "results": [{ "phone": "5039367187", "status": "removed" }]
    }
    ```
  </Tab>
</Tabs>

## 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


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