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

# Check DNC Status

Check Do Not Call (DNC) registry status and phone type for an array of phone numbers. This is a lightweight endpoint that returns only DNC status and phone type — no full person enrichment.

<Note>Each request accepts up to **1,000 items** in the `phones` array.</Note>

## Body Parameters

<ParamField body="phones" type="array" required>
  Array of phone number objects to check (max 1,000).

  <Expandable title="Phone object properties">
    <ParamField body="number" type="string" required>
      Phone number. Can include formatting (dashes, spaces, parentheses) — the API normalizes automatically.
    </ParamField>
  </Expandable>
</ParamField>

***

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST "https://api.v2.dealmachine.com/v1/phones/dnc" \
    -H "Authorization: Bearer dm_sk_live_xxx" \
    -H "Content-Type: application/json" \
    -d '{
      "phones": [
        { "number": "5125551234" },
        { "number": "3145559876" },
        { "number": "(212) 555-0100" }
      ]
    }'
  ```

  ```typescript Node.js theme={null}
  const response = await fetch('https://api.v2.dealmachine.com/v1/phones/dnc', {
    method: 'POST',
    headers: {
      Authorization: `Bearer ${apiKey}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      phones: [{ number: '5125551234' }, { number: '3145559876' }, { number: '(212) 555-0100' }],
    }),
  });

  const { data, totals } = await response.json();

  console.log(`Matched ${totals.matched} of ${totals.submitted}`);
  for (const item of data) {
    if (item.matched) {
      const status =
        item.do_not_call == null
          ? 'DNC status unavailable'
          : item.do_not_call
            ? 'ON DNC'
            : 'NOT on DNC';
      console.log(`${item.input.number}: ${status} (${item.phone_type || 'unknown type'})`);
    } else {
      console.log(`${item.input.number}: No match found`);
    }
  }
  ```

  ```python Python theme={null}
  import requests

  response = requests.post(
      "https://api.v2.dealmachine.com/v1/phones/dnc",
      headers={"Authorization": f"Bearer {api_key}"},
      json={
          "phones": [
              {"number": "5125551234"},
              {"number": "3145559876"},
              {"number": "(212) 555-0100"},
          ]
      },
  )

  body = response.json()
  for item in body["data"]:
      if item["matched"]:
          if "do_not_call" not in item:
              status = "DNC status unavailable"
          else:
              status = "ON DNC" if item["do_not_call"] else "NOT on DNC"
          print(f"{item['input']['number']}: {status} ({item.get('phone_type', 'unknown type')})")
      else:
          print(f"{item['input']['number']}: No match found")
  ```
</RequestExample>

<ResponseExample>
  ```json 200 OK theme={null}
  {
    "data": [
      {
        "input": { "number": "5125551234" },
        "matched": true,
        "do_not_call": false,
        "phone_type": "wireless"
      },
      {
        "input": { "number": "3145559876" },
        "matched": true,
        "do_not_call": true,
        "phone_type": "landline"
      },
      {
        "input": { "number": "(212) 555-0100" },
        "matched": false,
        "match_failure": {
          "code": "no_match",
          "reason": "No person found with this phone number"
        }
      }
    ],
    "totals": {
      "submitted": 3,
      "matched": 2,
      "unmatched": 1
    },
    "credits": {
      "used": 2,
      "people": 2,
      "deduplicated": 0
    }
  }
  ```

  ```json 400 Validation Error theme={null}
  {
    "error": {
      "code": "validation_error",
      "message": "Validation failed",
      "request_id": "req_abc123def456",
      "details": {
        "issues": [
          {
            "path": "phones[0].number",
            "message": "Required"
          }
        ]
      }
    }
  }
  ```
</ResponseExample>

## Response Fields

### Matched Result

| Field         | Type    | Description                                                                                                        |
| ------------- | ------- | ------------------------------------------------------------------------------------------------------------------ |
| `input`       | object  | Echo of the original input object                                                                                  |
| `matched`     | boolean | `true`                                                                                                             |
| `do_not_call` | boolean | Whether the requested phone number is on the Do Not Call registry. Omitted if exact phone metadata is unavailable. |
| `phone_type`  | string  | `wireless`, `landline`, `voip`, or `unknown`. Omitted if exact phone metadata is unavailable.                      |

### Unmatched Result

| Field           | Type    | Description                                 |
| --------------- | ------- | ------------------------------------------- |
| `input`         | object  | Echo of the original input object           |
| `matched`       | boolean | `false`                                     |
| `match_failure` | object  | Structured failure with `code` and `reason` |

### Totals

| Field       | Type    | Description                                   |
| ----------- | ------- | --------------------------------------------- |
| `submitted` | integer | Number of phones in the request array         |
| `matched`   | integer | Number of phones that matched a person record |
| `unmatched` | integer | Number of phones that did not match           |

## Credits

Each matched phone number consumes **1 credit**. Unmatched numbers are free. Credits are deduplicated within your billing period — checking the same phone number again is free.

## Notes

* Phone numbers are normalized automatically — formatting characters (dashes, spaces, parentheses) are stripped before matching.
* The DNC status reflects the national Do Not Call registry. State-level DNC lists are not included.
* This endpoint is optimized for DNC/type lookups. For full person data, use [Enrich by Phone](/api-reference/enrichment/enrich-by-phone) instead.