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

# Bulk Add to Do-Not-Contact

> Add up to 10,000 phone numbers and emails to your workspace's Do-Not-Contact list in one request. Idempotent. REST endpoint in the Tuco AI iMessage API — bearer-token auth.

<Note>
  Use this to load an existing opt-out list, or to sync opt-outs from your other channels in batches. Contacts already on the list are counted as `skipped`, not errors, so it is safe to resend a whole batch after a timeout.

  Bulk adds do **not** fire the `dnc.added` webhook (you already know about these contacts). For one-at-a-time adds that should notify your webhooks, use [`POST /api/dnc`](/api-reference/endpoint/add-dnc).
</Note>

## Authentication

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

Phones are normalized to E.164 (`(904) 555-1234` → `+19045551234`). Emails are stored lower case.

## Example

```bash theme={null}
curl -X PATCH "https://app.tuco.ai/api/dnc" \
  -H "Authorization: Bearer tuco_xxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "reason": "whatsapp-opt-out",
    "entries": [
      { "phone": "+15550100001" },
      { "phone": "(555) 010-0002" },
      { "email": "jane@example.com" }
    ]
  }'
```

## Success response (200)

```json theme={null}
{ "ok": true, "added": 2, "skipped": 1, "invalid": 0, "failed": 0 }
```

New entries have `source: "api-bulk"` in [`GET /api/dnc`](/api-reference/endpoint/list-dnc).

## Errors

| Status | Body | When |
| - | - | - |
| `207` | `{ "ok": false, …, "failed": n }` | Some entries could not be saved — resend |
| `400` | `{ "error": "entries array is required" }` | Missing, empty or non-array `entries` |
| `400` | `{ "error": "Maximum 10,000 entries per request" }` | More than 10,000 items |
| `401` | `{ "error": "Unauthorized" }` | Missing or invalid API key |
| `429` | `{ "error": "Rate limit exceeded" }` | Rate limit exceeded (120/min per workspace) |


## OpenAPI

````yaml PATCH /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:
    patch:
      summary: Bulk add to Do-Not-Contact
      description: >-
        Add up to 10,000 phones/emails. Idempotent: already-listed contacts are
        `skipped`. Does not fire `dnc.added`.
      operationId: bulkAddDnc
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BulkAddDncRequest'
            example:
              reason: whatsapp-opt-out
              entries:
                - phone: '+15550100001'
                - phone: (555) 010-0002
                - email: jane@example.com
      responses:
        '200':
          description: All saved
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BulkAddDncResponse'
              example:
                ok: true
                added: 2
                skipped: 1
                invalid: 0
                failed: 0
        '207':
          description: Some entries failed to save — resend the batch
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BulkAddDncResponse'
              example:
                ok: false
                added: 1
                skipped: 0
                invalid: 0
                failed: 1
        '400':
          description: Missing/empty/non-array entries, or more than 10,000
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error: entries array is required
        '401':
          description: Missing or invalid API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error: Unauthorized
        '429':
          description: Rate limit exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error: Rate limit exceeded
components:
  schemas:
    BulkAddDncRequest:
      type: object
      required:
        - entries
      properties:
        entries:
          type: array
          maxItems: 10000
          minItems: 1
          description: Each item has a `phone`, an `email`, or both
          items:
            type: object
            properties:
              phone:
                type: string
              email:
                type: string
                format: email
          example:
            - phone: '+15550100001'
            - phone: (555) 010-0002
            - email: jane@example.com
        reason:
          type: string
          default: api-bulk
          example: whatsapp-opt-out
    BulkAddDncResponse:
      type: object
      required:
        - ok
        - added
        - skipped
        - invalid
        - failed
      properties:
        ok:
          type: boolean
          description: '`false` when `failed` > 0'
        added:
          type: integer
          description: New entries created
        skipped:
          type: integer
          description: Already on the list
        invalid:
          type: integer
          description: Items with neither phone nor email
        failed:
          type: integer
          description: Could not be saved — resend the batch
    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.