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

# internal_dnc Tool

> Add or remove phone numbers from your Internal DNC list

The `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
  * `status` - Check if numbers are on the list
</ParamField>

<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="results" type="array">
  Array of results for each phone number.

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

    <ResponseField name="status" type="string">
      Result: `added`, `removed`, `already_exists`, `not_found`, or `on_list`/`not_on_list` for status checks.
    </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>

## 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,
      "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="Status Request">
    ```json theme={null}
    {
      "phoneNumbers": ["5039367187"],
      "action": "status"
    }
    ```
  </Tab>
</Tabs>

## Usage Notes

* Adding a number that already exists has no effect (idempotent)
* Removing a number that doesn't exist has no effect
* Use `projId` to maintain separate Internal DNC lists per project or client
* Phone numbers must be exactly 10 digits without formatting