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

# Add numbers to the Block list

> Adds up to 1,000 numbers to the numbers your account never calls. A listed number is refused at dial time, for campaign calls and manual calls alike. Numbers already on the list keep their first entry. Numbers that can't be read are returned in `invalid` and do not fail the request. A number can only be removed from the list in the dashboard. Requires scope: `leads:write`.



## OpenAPI

````yaml /api-reference/openapi.json post /v1/block-list
openapi: 3.0.3
info:
  title: TopCalls Voice API
  description: |
    Place and manage AI phone calls, campaigns, leads and phone numbers.

    ## Authentication

    Send your API key as a bearer token on every request:

    ```
    Authorization: Bearer tc_live_xxxxx
    ```

    A missing or invalid key gets `401`. Keys carry scopes, and a key without
    the scope an endpoint needs gets `403`.

    ## Rate limits

    The first three limits are per account, so every API key on the account
    shares them. The last is per IP address.

    - All `/v1` endpoints: 120 requests per minute unless we've raised it for
      your account. Over it, you get `429` with `Retry-After` and a plain-text
      body. Responses carry `RateLimit-Limit`, `RateLimit-Remaining` and
      `RateLimit-Reset`.
    - `POST /v1/calls` also counts against your account's
      `max_calls_per_minute` (default 20) in a fixed 60-second window. Going
      over returns `429`, `Retry-After: 60` and `code: RATE_LIMITED`. A request
      counts once its body validates, even if it then fails (say, a `404` on an
      unknown `lead_id`).
    - A call placed while every concurrent-call slot is busy gets `429` with
      `code: concurrency_limit` and no `Retry-After`. Retry once a call ends.
    - Failed authentication: after 600 requests within a minute whose API key
      is refused with `401`, every `/v1` request from that IP address gets
      `429` with `Retry-After` until the minute is up, even one with a valid key.

    On a `429` with `Retry-After`, wait that many seconds, then retry. Back off
    longer on repeats.

    ## Error format

    Errors are RFC 7807 Problem+JSON (`application/problem+json`), except the
    plain-text 120-per-minute `429`. Branch on `status` and `code`:

    ```json
    {
      "status": 402,
      "title": "Insufficient Quota",
      "code": "insufficient_quota",
      "detail": "Not enough credit to place this call. Add credit in Billing (steps: https://docs.topcalls.ai/concepts/credit#adding-credit).",
      "available": 0.5,
      "requested": 2
    }
    ```
  version: 1.0.0
  contact:
    name: TopCalls Support
    url: https://topcalls.ai
  license:
    name: Proprietary
servers:
  - url: https://api.topcalls.ai
    description: Production
security: []
tags:
  - name: Calls
    description: Place and manage phone calls
  - name: Campaigns
    description: Create, run and test call campaigns
  - name: Phone Numbers
    description: Phone numbers and carriers
  - name: Account
    description: Credit balance, credit ledger, call price quotes and daily call analytics
  - name: Webhooks
    description: Webhook subscriptions and events
  - name: Configuration
    description: Available models, voices and platform capabilities
paths:
  /v1/block-list:
    post:
      summary: Add numbers to the Block list
      description: >-
        Adds up to 1,000 numbers to the numbers your account never calls. A
        listed number is refused at dial time, for campaign calls and manual
        calls alike. Numbers already on the list keep their first entry. Numbers
        that can't be read are returned in `invalid` and do not fail the
        request. A number can only be removed from the list in the dashboard.
        Requires scope: `leads:write`.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BlockListAdd'
      responses:
        '200':
          description: >-
            The numbers added, those already listed, and those that could not be
            read
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BlockListAddResult'
        '400':
          description: Invalid input
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
        '401':
          description: Unauthorized
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
        '403':
          description: Forbidden
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
        '429':
          description: Rate limit exceeded
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
        '500':
          description: Internal error
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
      security:
        - bearerAuth: []
components:
  schemas:
    BlockListAdd:
      type: object
      additionalProperties: false
      required:
        - phone_numbers
      properties:
        phone_numbers:
          type: array
          minItems: 1
          maxItems: 1000
          items:
            type: string
            maxLength: 64
          description: >-
            Numbers with their country code (`+14155551234` or `0014155551234`).
            Spaces, dashes and brackets are ignored.
        note:
          type: string
          maxLength: 500
          description: Kept on each number this request adds.
    BlockListAddResult:
      type: object
      required:
        - added
        - already_listed
        - invalid
      properties:
        added:
          type: array
          items:
            type: string
          description: Numbers this request added, in E.164.
        already_listed:
          type: array
          items:
            type: string
          description: >-
            Numbers that were already on the list, in E.164. Their first entry
            is kept.
        invalid:
          type: array
          description: Numbers that could not be read. Nothing was added for them.
          items:
            type: object
            required:
              - phone_number
              - reason
            properties:
              phone_number:
                type: string
                description: The value as sent.
              reason:
                type: string
                enum:
                  - invalid_phone
                  - missing_country_code
    Problem:
      type: object
      required:
        - status
        - title
      properties:
        type:
          type: string
          format: uri
          description: Error type URI. Not every error sets it.
        title:
          type: string
          description: Short summary of the error.
        status:
          type: integer
          description: HTTP status code.
        detail:
          type: string
          description: What went wrong, in plain words.
        code:
          type: string
          description: >-
            Stable code to branch on, sent on errors that have one (such as
            `insufficient_quota` or `PROMPT_SAFETY_FRAUD`). Each endpoint's
            examples show its values.
        instance:
          type: string
          description: >-
            Request id, sent on some errors. It's your `X-Request-Id` header
            when you sent one.
        errors:
          type: array
          description: Field-level validation failures, on `400`.
          items:
            type: object
            properties:
              path:
                type: string
                description: Field path, such as `phone_number`.
              message:
                type: string
                description: What's wrong with the field.
              code:
                type: string
                description: Validation code, such as `invalid_string` or `custom`.
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: |
        Use `Authorization: Bearer tc_live_xxxxx`

````

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