# Do Not Call

Numbers your AI never calls. Reading needs `dnc:read`, changes need `dnc:write`. GH's own list is always enforced but not listed.

Base URL: `https://vocenya.com/api/public/v1`. Authenticate with `Authorization: Bearer $VOCENYA_API_KEY`.

- [List Do Not Call entries](#list-do-not-call-entries): `GET /do-not-call`
- [Add a number to the Do Not Call list](#create-do-not-call-entry): `POST /do-not-call`
- [Remove a number from the Do Not Call list](#delete-do-not-call-entry): `DELETE /do-not-call/{entry}`

## List Do Not Call entries

`GET https://vocenya.com/api/public/v1/do-not-call`

Required scope: `dnc:read`

Your Do Not Call list, newest first. Pass `phone_number` to look up one number.

### Query parameters

- `phone_number` (string, optional): Look up one number, in any common US format. Up to 32 characters.
- `source` (string, optional): One of: `opt_out`, `manual`.
- `per_page` (integer, optional): How many items per page, 1 to 100. Minimum 1. Maximum 100.
- `cursor` (string or null, optional): The `meta.next_cursor` (or `meta.prev_cursor`) of the previous page. Up to 1024 characters.

### Responses

- `200`: Paginated set of `DoNotCallEntryResource`
- `401`: The API key is missing, invalid, expired or revoked.
- `403`: The key does not have the `dnc:read` scope.
- `422`: Validation error
- `429`: Too many requests for this key. Wait for the `Retry-After` seconds.

### Response attributes (200)

- `data` (array of objects, required)
  - `id` (integer, required)
  - `livemode` (boolean, required): `true` for live data, `false` for test data (created with a `vk_test_` key).
  - `phone_number` (string, required)
  - `source` (string, required): `opt_out` when the person asked not to be called (permanent), `manual` when you added it. | | |---| | `opt_out` <br/> The person asked not to be called: on an AI call, to a GH Live agent, or to the client. | | `manual` <br/> Added by GH staff or the client. | | `national_registry` <br/> Imported from the FTC National Do Not Call Registry. | One of: `opt_out`, `manual`, `national_registry`.
  - `note` (string or null, required)
  - `removable` (boolean, required): Whether the entry can be removed. People who asked not to be called never can.
  - `created_at` (string or null, required)
- `links` (object, required)
  - `first` (string or null, required)
  - `last` (string or null, required)
  - `prev` (string or null, required)
  - `next` (string or null, required)
- `meta` (object, required)
  - `path` (string or null, required): Base path for paginator generated URLs.
  - `per_page` (integer, required): Number of items shown per page. Minimum 0.
  - `next_cursor` (string or null, required): The "cursor" that points to the next set of items.
  - `prev_cursor` (string or null, required): The "cursor" that points to the previous set of items.

### Example request

```bash
curl https://vocenya.com/api/public/v1/do-not-call \
  -H "Authorization: Bearer $VOCENYA_API_KEY"
```

```javascript
const response = await fetch('https://vocenya.com/api/public/v1/do-not-call', {
  headers: {
    Authorization: `Bearer ${process.env.VOCENYA_API_KEY}`,
  },
});

const data = await response.json();
console.log(data);
```

```php
$client = new \GuzzleHttp\Client();

$response = $client->request('GET', 'https://vocenya.com/api/public/v1/do-not-call', [
    'headers' => ['Authorization' => 'Bearer '.getenv('VOCENYA_API_KEY')],
]);

$data = json_decode((string) $response->getBody(), true);
print_r($data);
```

```python
import os

import requests

response = requests.get(
    "https://vocenya.com/api/public/v1/do-not-call",
    headers={"Authorization": f"Bearer {os.environ['VOCENYA_API_KEY']}"},
)

print(response.json())
```

### Example response (200)

```json
{
  "data": [
    {
      "id": 1,
      "livemode": true,
      "phone_number": "+15125550123",
      "source": "opt_out",
      "note": "string",
      "removable": true,
      "created_at": "2026-10-02T14:03:11+00:00"
    }
  ],
  "links": {
    "first": "string",
    "last": "string",
    "prev": "string",
    "next": "string"
  },
  "meta": {
    "path": "string",
    "per_page": 1,
    "next_cursor": "string",
    "prev_cursor": "string"
  }
}
```


## Add a number to the Do Not Call list

`POST https://vocenya.com/api/public/v1/do-not-call`

Required scope: `dnc:write`

Add a number. Send `opted_out: true` when the person asked not to be called: it becomes a
permanent opt-out and their AI-call consent is revoked. Adding a number already on the list
returns the existing entry with status 200.

### Request body

- `phone_number` (string, required): Up to 32 characters.
- `note` (string or null, optional): Up to 500 characters.
- `opted_out` (boolean, optional): The person asked not to be called. Recorded as a permanent opt-out that can never be removed, and any AI-call consent they gave is revoked.

### Responses

- `200`: The number was already on the list: the existing entry.
- `201`: The entry.
- `401`: The API key is missing, invalid, expired or revoked.
- `403`: The key does not have the `dnc:write` scope.
- `422`: Validation failed, or the number is not a valid US number (`invalid_number`).
- `429`: Too many requests for this key. Wait for the `Retry-After` seconds.

### Response attributes (200)

- `data` (object, required)
  - `id` (integer, required)
  - `livemode` (boolean, required): `true` for live data, `false` for test data (created with a `vk_test_` key).
  - `phone_number` (string, required)
  - `source` (string, required): `opt_out` when the person asked not to be called (permanent), `manual` when you added it. | | |---| | `opt_out` <br/> The person asked not to be called: on an AI call, to a GH Live agent, or to the client. | | `manual` <br/> Added by GH staff or the client. | | `national_registry` <br/> Imported from the FTC National Do Not Call Registry. | One of: `opt_out`, `manual`, `national_registry`.
  - `note` (string or null, required)
  - `removable` (boolean, required): Whether the entry can be removed. People who asked not to be called never can.
  - `created_at` (string or null, required)

### Example request

```bash
curl -X POST https://vocenya.com/api/public/v1/do-not-call \
  -H "Authorization: Bearer $VOCENYA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "phone_number": "+15555550123",
  "note": "Asked us to stop calling"
}'
```

```javascript
const response = await fetch('https://vocenya.com/api/public/v1/do-not-call', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.VOCENYA_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "phone_number": "+15555550123",
    "note": "Asked us to stop calling"
  }),
});

const data = await response.json();
console.log(data);
```

```php
$client = new \GuzzleHttp\Client();

$response = $client->request('POST', 'https://vocenya.com/api/public/v1/do-not-call', [
    'headers' => ['Authorization' => 'Bearer '.getenv('VOCENYA_API_KEY')],
    'json' => [
        'phone_number' => '+15555550123',
        'note' => 'Asked us to stop calling',
    ],
]);

$data = json_decode((string) $response->getBody(), true);
print_r($data);
```

```python
import os

import requests

response = requests.post(
    "https://vocenya.com/api/public/v1/do-not-call",
    headers={"Authorization": f"Bearer {os.environ['VOCENYA_API_KEY']}"},
    json={
        "phone_number": "+15555550123",
        "note": "Asked us to stop calling",
    },
)

print(response.json())
```

### Example response (200)

```json
{
  "data": {
    "id": 1,
    "livemode": true,
    "phone_number": "+15125550123",
    "source": "opt_out",
    "note": "string",
    "removable": true,
    "created_at": "2026-10-02T14:03:11+00:00"
  }
}
```


## Remove a number from the Do Not Call list

`DELETE https://vocenya.com/api/public/v1/do-not-call/{entry}`

Required scope: `dnc:write`

Remove a number you added. People who asked not to be called can never be removed.

### Path parameters

- `entry` (integer, required): The entry id.

### Responses

- `204`: Removed.
- `401`: The API key is missing, invalid, expired or revoked.
- `403`: The entry is an opt-out and cannot be removed (`opt_out_permanent`).
- `404`: No record with that id belongs to your account.
- `429`: Too many requests for this key. Wait for the `Retry-After` seconds.

### Example request

```bash
curl -X DELETE https://vocenya.com/api/public/v1/do-not-call/57 \
  -H "Authorization: Bearer $VOCENYA_API_KEY"
```

```javascript
const response = await fetch('https://vocenya.com/api/public/v1/do-not-call/57', {
  method: 'DELETE',
  headers: {
    Authorization: `Bearer ${process.env.VOCENYA_API_KEY}`,
  },
});

console.log(response.status);
```

```php
$client = new \GuzzleHttp\Client();

$response = $client->request('DELETE', 'https://vocenya.com/api/public/v1/do-not-call/57', [
    'headers' => ['Authorization' => 'Bearer '.getenv('VOCENYA_API_KEY')],
]);

echo $response->getStatusCode();
```

```python
import os

import requests

response = requests.delete(
    "https://vocenya.com/api/public/v1/do-not-call/57",
    headers={"Authorization": f"Bearer {os.environ['VOCENYA_API_KEY']}"},
)

print(response.status_code)
```