---
title: "Add a number to the Do Not Call list"
method: POST
path: "/do-not-call"
tags: ["Do Not Call"]
---

# Add a number to the Do Not Call list

`POST /do-not-call`

## Request

- Base URL: `https://vocenya.com/api/public/v1`
- URL: `https://vocenya.com/api/public/v1/do-not-call`
- Auth: HTTP bearer

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

- StoreDoNotCallEntryRequest
  - `phone_number` string, required
  - `note` string, nullable
  - `opted_out` boolean: 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.

## Response `200`

The number was already on the list: the existing entry.

- object
  - `data` DoNotCallEntryResource, 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` 'opt_out' | 'manual' | 'national_registry', required: | | |---| | `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. |
    - `note` string, nullable, required
    - `removable` boolean, required: Whether the entry can be removed. People who asked not to be called never can.
    - `created_at` string, nullable, required

## Other responses

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

---

[API](https://skmtc.dev/vocenya/apis/vocenya-api.md) · [All operations](https://skmtc.dev/vocenya/apis/vocenya-api/llms.txt) · [OpenAPI document](https://skmtc.dev/vocenya/apis/vocenya-api/revisions/946913941565?raw)