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

# Add to Do-Not-Contact

> Add a phone number or email to your workspace's Do-Not-Contact list so Tuco never messages it. REST endpoint in the Tuco AI iMessage API — bearer-token auth.

<Note>
  Use this to push opt-outs from your other channels (WhatsApp, email, forms) into Tuco. Every message is checked against this list before it is sent. A successful add fires the [`dnc.added` webhook](/api-reference/message-webhooks#dnc-added).
</Note>

## Authentication

```bash theme={null}
Authorization: Bearer tuco_xxxxxxxxxxxxx
```

## Example

```bash theme={null}
curl -X POST "https://app.tuco.ai/api/dnc" \
  -H "Authorization: Bearer tuco_xxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{ "phone": "555-010-0778", "reason": "whatsapp-opt-out" }'
```

## Success response (200)

```json theme={null}
{ "ok": true, "id": "6ad60002d963dc1e85d12148" }
```

## Errors

| Status | Body | When |
| - | - | - |
| `400` | `{ "error": "Either phone or email is required" }` | Neither field sent |
| `400` | `{ "error": "Body must be JSON: { phone?, email?, reason? }" }` | Body is not JSON |
| `401` | `{ "error": "Unauthorized" }` | Missing or invalid API key |
| `409` | `{ "error": "This contact is already on the DNC list" }` | Already listed |
| `429` | `{ "error": "Rate limit exceeded" }` | Rate limit exceeded |

To add many contacts at once, use [Bulk add](/api-reference/endpoint/bulk-add-dnc). Removing a contact from the list is done in the dashboard only.


## OpenAPI

````yaml POST /api/dnc
openapi: 3.1.0
info:
  title: Tuco AI API
  description: >-
    Send iMessages, SMS, and email at scale. Create leads, get lines, check
    replies. All endpoints support Bearer API key (`Authorization: Bearer
    tuco_...`).
  version: 1.0.0
  contact:
    email: support@tuco.ai
    url: https://app.tuco.ai
servers:
  - url: https://app.tuco.ai
    description: Production
security:
  - bearerAuth: []
paths:
  /api/dnc:
    post:
      summary: Add to Do-Not-Contact
      description: Add one phone or email. Fires the `dnc.added` webhook.
      operationId: addDnc
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AddDncRequest'
            example:
              phone: 555-010-0778
              reason: whatsapp-opt-out
      responses:
        '200':
          description: Added
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AddDncResponse'
              example:
                ok: true
                id: 6ad60002d963dc1e85d12148
        '400':
          description: Neither phone nor email, or body is not JSON
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error: Either phone or email is required
        '401':
          description: Missing or invalid API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error: Unauthorized
        '409':
          description: Already on the list
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error: This contact is already on the DNC list
        '429':
          description: Rate limit exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error: Rate limit exceeded
components:
  schemas:
    AddDncRequest:
      type: object
      properties:
        phone:
          type: string
          description: >-
            Phone number in any common format; stored as E.164. Either `phone`
            or `email` is required.
          example: 555-010-0778
        email:
          type: string
          format: email
          description: Email address; stored lower case
        reason:
          type: string
          default: manual
          example: whatsapp-opt-out
    AddDncResponse:
      type: object
      required:
        - ok
        - id
      properties:
        ok:
          type: boolean
        id:
          type: string
    ErrorResponse:
      type: object
      required:
        - error
      properties:
        error:
          type: string
        code:
          type: string
        reason:
          type: string
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: API Key
      description: 'Workspace API key: Authorization: Bearer tuco_xxxxxxxxxxxxx'

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.