# client.dnc

> The dnc methods of the morevoice Python SDK: The organisation's do-not-call list and registry checks.

The organisation's do-not-call list and registry checks. These methods are on `client.dnc`, where `client` is a `MoreVoice` client (see [the Python SDK](https://docs.morevoice.ai/sdk/python/#connect)). On `AsyncMoreVoice` the same methods are awaited. Each one returns the response object and raises an exception when the API answers with an error.

## `check()`

**Check numbers before calling.** For each number: your do-not-call list, recorded consent and the national registry, combined into `callable` for the purpose. Read-only.

```python
# client.dnc
def check(self, body: _m.DncCheckBody | Mapping[str, Any], *, more_voice_version: str | Unset = UNSET, idempotency_key: str | Unset = UNSET) -> _m.DncCheck
```

`client.dnc.check()` · `await async_client.dnc.check()` · `POST /dnc/check` · [API reference](https://docs.morevoice.ai/api/operations/dnc_check/)

### Request body

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `phones` | `string[]` | yes | Up to 100 numbers. |
| `purpose` | `"service" \| "marketing" \| "survey"` | yes | The call's purpose. `marketing` requires recorded consent and a national-registry clearance (Israeli numbers); every purpose respects your do-not-call list. |

### Returns

`DncCheck`:

| Field | Type | Description |
| --- | --- | --- |
| `object` | `"dnc_check"` | Always `dnc_check`. |
| `livemode` | `boolean` | `true` in live mode, `false` in test mode. |
| `purpose` | `"service" \| "marketing" \| "survey"` | — |
| `results` | `object[]` | — |

### Example

```python
from morevoice import MoreVoice

client = MoreVoice()  # MOREVOICE_API_KEY from the environment

dnc_check = client.dnc.check({
    "phones": [
        "+972501234567",
        "0527654321",
    ],
    "purpose": "marketing",
})
print(dnc_check)
```

## `create()`

**Add numbers to the do-not-call list.** Adds up to 1,000 numbers. Each new number emits one `contact.opted_out` event, and queued campaign contacts with it are taken out at once. Needs a live key.

```python
# client.dnc
def create(self, body: _m.DncCreateBody | Mapping[str, Any], *, more_voice_version: str | Unset = UNSET, idempotency_key: str | Unset = UNSET) -> _m.DncBatch
```

`client.dnc.create()` · `await async_client.dnc.create()` · `POST /dnc` · [API reference](https://docs.morevoice.ai/api/operations/dnc_create/)

### Request body

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `phones` | `string[]` | yes | Up to 1000 numbers. |
| `reason` | `string` | no | A note kept with each entry. |

### Returns

`DncBatch`:

| Field | Type | Description |
| --- | --- | --- |
| `object` | `"dnc_batch"` | Always `dnc_batch`. |
| `livemode` | `boolean` | `true` in live mode, `false` in test mode. |
| `added` | `string[]` | Numbers added now (E.164). Each emits one `contact.opted_out` event. |
| `already_listed` | `string[]` | Numbers that were on the list already (E.164). |
| `invalid` | `string[]` | Entries that are not valid phone numbers, as sent. |

### Example

```python
from morevoice import MoreVoice

client = MoreVoice()  # MOREVOICE_API_KEY from the environment

dnc_batch = client.dnc.create({
    "phones": [
        "+972501234567",
        "052-765-4321",
    ],
    "reason": "Opted out in the CRM",
})
print(dnc_batch)
```

## `delete()`

**Remove a number from the do-not-call list.** Calls to the number are allowed again (marketing calls still need consent and the registry). Needs a live key.

```python
# client.dnc
def delete(self, phone: str, *, more_voice_version: str | Unset = UNSET, idempotency_key: str | Unset = UNSET) -> _m.DeletedDncEntry
```

`client.dnc.delete()` · `await async_client.dnc.delete()` · `DELETE /dnc/{phone}` · [API reference](https://docs.morevoice.ai/api/operations/dnc_delete/)

### Parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `phone` | `str` | yes | The number (URL-encode the `+` as `%2B`). |

### Returns

`DeletedDncEntry`:

| Field | Type | Description |
| --- | --- | --- |
| `object` | `"dnc_entry"` | Always `dnc_entry`. |
| `phone` | `string` | — |
| `deleted` | `true` | — |

### Example

```python
from morevoice import MoreVoice

client = MoreVoice()  # MOREVOICE_API_KEY from the environment

deleted_dnc_entry = client.dnc.delete("+972501234567")
print(deleted_dnc_entry)
```

## `list()`

**List the do-not-call list.** Lists the numbers on your do-not-call list, newest first: how each one got there and when. Filter by `phone` (any common format). Test keys can read the list; changing it needs a live key.

```python
# client.dnc
def list(self, *, limit: int | Unset = 20, starting_after: str | Unset = UNSET, ending_before: str | Unset = UNSET, phone: str | Unset = UNSET, more_voice_version: str | Unset = UNSET) -> AsyncPage[_m.DncEntry]
```

`client.dnc.list()` · `await async_client.dnc.list()` · `GET /dnc` · [API reference](https://docs.morevoice.ai/api/operations/dnc_list/)

### Parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `limit` | `integer` | no | How many objects to return, 1–100 (default 20). |
| `starting_after` | `string` | no | A cursor (`next_cursor`) or object ID: return the objects after it (older). |
| `ending_before` | `string` | no | A cursor or object ID: return the objects before it (newer). |
| `phone` | `string` | no | Only this number (any common form). |

### Returns

A page of results (`DncEntryList`): `data`, `has_more` and `next_cursor`.

### Example

```python
from morevoice import MoreVoice

client = MoreVoice()  # MOREVOICE_API_KEY from the environment

for dnc in client.dnc.list():
    print(dnc)
```

## `retrieve()`

**Retrieve a do-not-call entry.** Returns the entry of one number on your do-not-call list: when it was added, how (`source`: the dashboard, an import, the API, or an opt-out during a call) and your note. `404` means the number is not on the list. To check a number against the national registry too, use `POST /v1/dnc/check`.

```python
# client.dnc
def retrieve(self, phone: str, *, more_voice_version: str | Unset = UNSET) -> _m.DncEntry
```

`client.dnc.retrieve()` · `await async_client.dnc.retrieve()` · `GET /dnc/{phone}` · [API reference](https://docs.morevoice.ai/api/operations/dnc_retrieve/)

### Parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `phone` | `str` | yes | The number (URL-encode the `+` as `%2B`). |

### Returns

`DncEntry`:

| Field | Type | Description |
| --- | --- | --- |
| `object` | `"dnc_entry"` | Always `dnc_entry`. |
| `livemode` | `boolean` | `true` in live mode, `false` in test mode. |
| `phone` | `string` | The number, E.164. |
| `source` | `string` | How it was added: `manual`, `import`, `api`, `opt_out_tool` (asked the AI), `opt_out_phrase` or `opt_out_dtmf`. |
| `reason` | `string` | A free-text note. |
| `campaign_id` | `string \| null` | `cmp_…` ID. |
| `call_id` | `string \| null` | `call_…` ID. |
| `created` | `string` | An ISO-8601 timestamp in UTC. |

### Example

```python
from morevoice import MoreVoice

client = MoreVoice()  # MOREVOICE_API_KEY from the environment

dnc_entry = client.dnc.retrieve("+972501234567")
print(dnc_entry)
```