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

# List carriers

> Get all custom carriers (BYOC) you've added to your account.

**Note:** The TopCalls default carrier is not shown in this list, but you can still use it by omitting `voip_carrier_sid` when provisioning phone numbers.




## OpenAPI

````yaml /api-reference/openapi.json get /v1/phone-numbers/carriers
openapi: 3.0.3
info:
  title: TopCalls Voice API
  description: >
    TopCalls Voice Gateway API for creating and managing AI-powered phone calls.


    ## Authentication


    All API requests require authentication. Include your API key in the
    `Authorization` header:


    ```

    Authorization: Bearer tc_live_xxxxx

    ```


    ## Rate Limits


    Direct call creation via `POST /v1/calls` is limited to your account's

    `max_calls_per_minute` setting (default: 20) per minute. Exceeding it
    returns

    `429 Too Many Requests` with a `Retry-After` header.

    All endpoints are additionally subject to a flat limit of 120 requests per

    minute per account (all methods).


    On a `429`, wait for the number of seconds in the `Retry-After` header, then

    retry the same request. For automated clients, back off progressively on

    repeated `429`s. Limits are per account and are shared by all API keys.


    ## Error Format


    All errors follow RFC 7807 Problem+JSON format:


    ```json

    {
      "type": "https://api.topcalls.ai/errors/insufficient_quota",
      "title": "Insufficient Quota",
      "status": 402,
      "detail": "You need 5 minutes but have 3.5 remaining"
    }

    ```
  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: Create and manage phone calls
  - name: Phone Numbers
    description: Manage phone numbers and carriers
  - name: Account
    description: Account information and usage
  - name: Webhooks
    description: Webhook configuration and events
  - name: Configuration
    description: Available AI models, voices, and platform capabilities
paths:
  /v1/phone-numbers/carriers:
    get:
      tags:
        - Phone Numbers
      summary: List carriers
      description: >
        Get all custom carriers (BYOC) you've added to your account.


        **Note:** The TopCalls default carrier is not shown in this list, but
        you can still use it by omitting `voip_carrier_sid` when provisioning
        phone numbers.
      operationId: listCarriers
      responses:
        '200':
          description: List of carriers
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListCarriersResponse'
              example:
                carriers:
                  - voip_carrier_sid: 660e8400-e29b-41d4-a716-446655440001
                    carrier_name: My Custom Carrier
                    is_default: false
                    is_system: false
                    trunk_type: static_ip
                default_voip_carrier_sid: 550e8400-e29b-41d4-a716-446655440000
                count: 1
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
      security:
        - bearerAuth: []
components:
  schemas:
    ListCarriersResponse:
      type: object
      properties:
        carriers:
          type: array
          items:
            $ref: '#/components/schemas/Carrier'
        default_voip_carrier_sid:
          type: string
          format: uuid
          description: The default carrier UUID for this account
        count:
          type: integer
          description: Total number of carriers
    Carrier:
      type: object
      properties:
        voip_carrier_sid:
          type: string
          format: uuid
          description: Carrier UUID
        carrier_name:
          type: string
          description: Display name
        is_default:
          type: boolean
          description: Whether this is the default carrier for provisioning
        is_system:
          type: boolean
          description: Whether this is the TopCalls system carrier (true) or custom (false)
        trunk_type:
          type: string
          enum:
            - static_ip
            - auth
            - reg
          description: SIP trunk type (only shown for custom carriers)
    Problem:
      type: object
      required:
        - status
        - title
      properties:
        type:
          type: string
          format: uri
          description: Error type URI
        title:
          type: string
          description: Error title
        status:
          type: integer
          description: HTTP status code
        detail:
          type: string
          description: Human-readable error detail
        code:
          type: string
          description: >
            Machine-readable error code for programmatic handling. Present on

            errors that carry a stable identifier (e.g. `PROMPT_SAFETY_FRAUD`,

            `job_not_found`, `too_many_ids`, `no_matches`). Distinct from the

            per-field `errors[].code` used for validation failures. Scenario-

            specific — see each endpoint's response examples for the exact
            value.
        instance:
          type: string
          format: uuid
          description: Request instance ID
        errors:
          type: array
          description: Validation errors (for 400 responses)
          items:
            type: object
            properties:
              path:
                type: string
                description: Field path (e.g., "phone_number", "metadata.from_number")
              message:
                type: string
                description: Error message
              code:
                type: string
                description: Error code (e.g., "invalid_string", "custom")
        details:
          type: string
          description: Additional error details (for provider errors)
  responses:
    Unauthorized:
      description: Unauthorized (missing or invalid API key)
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Problem'
          example:
            status: 401
            title: Unauthorized
            detail: Invalid or missing API key
    Forbidden:
      description: Forbidden (missing required scope)
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Problem'
          example:
            status: 403
            title: Forbidden
            detail: 'Missing required scope: calls:write'
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: |
        Use `Authorization: Bearer tc_live_xxxxx`

````