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

# List Carrier Accounts

> Your connected Telnyx accounts, each with the numbers added to it. Requires
`carrier_accounts:read`.


Your connected Telnyx accounts, each with the numbers added to it and its current
status. Requires `carrier_accounts:read`.

```bash theme={null}
curl https://api.goyappr.com/carrier-accounts \
  -H "Authorization: Bearer ypr_live_..."
```

```json theme={null}
{
  "data": [
    {
      "id": "7c1e…",
      "name": "Main Telnyx account",
      "provider": "telnyx",
      "api_key_last4": "9XyZ",
      "public_key_set": true,
      "signature_verified": true,
      "connection": { "id": "2890…", "created_by_yappr": true, "outbound_voice_profile_id": "2890…" },
      "status": "active",
      "pause_reason": null,
      "last_error": null,
      "numbers": [{ "number": "+972501234567", "provider": "external", "ownership_verified_at": "2026-09-23T10:02:00Z", "…": "…" }]
    }
  ]
}
```

The API key is never returned: only its last four characters. `webhook_url` is not
in the list; [get one account](/api-reference/carrier-accounts/get) with a
`carrier_accounts:manage` key to see it.


## OpenAPI

````yaml GET /carrier-accounts
openapi: 3.1.0
info:
  title: Yappr API
  description: >
    Create and manage AI voice agents, purchase phone numbers, configure tools,
    and initiate calls — all via REST.
  version: 1.0.0
  contact:
    url: https://goyappr.com
servers:
  - url: https://api.goyappr.com
    description: Production
security:
  - apiKey: []
paths:
  /carrier-accounts:
    get:
      tags:
        - Carrier Accounts
      summary: List carrier accounts
      description: >
        Your connected Telnyx accounts, each with the numbers added to it.
        Requires

        `carrier_accounts:read`.
      operationId: listCarrierAccounts
      responses:
        '200':
          description: Your carrier accounts
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/CarrierAccount'
        '403':
          $ref: '#/components/responses/CarrierAccountsNotEnabled'
components:
  schemas:
    CarrierAccount:
      type: object
      description: >
        Your own Telnyx account, connected so agents can call from the numbers
        you

        own there. Yappr places each call **on your Call Control App, with your
        API

        key**, so the call runs on your Telnyx account and Telnyx bills you for
        it.

        The API key is write-only: no response ever contains it.
      properties:
        id:
          type: string
          format: uuid
        name:
          type: string
          example: Main Telnyx account
        provider:
          type: string
          enum:
            - telnyx
        api_key_last4:
          type: string
          example: 9XyZ
          description: >-
            The last four characters of the saved key. The key itself is never
            returned.
        api_key_updated_at:
          type: string
          format: date-time
        public_key_set:
          type: boolean
          description: Whether you saved your account's public key.
        signature_verified:
          type: boolean
          description: >
            `true` once a call event from Telnyx verified against your public
            key.

            From then on every event for this account must carry a valid
            signature.
        connection:
          type: object
          nullable: true
          description: >-
            The Call Control App calls go through. `null` until you [choose
            one](/api-reference/carrier-accounts/connection).
          properties:
            id:
              type: string
              example: '2890000000000000001'
            created_by_yappr:
              type: boolean
            outbound_voice_profile_id:
              type: string
              nullable: true
        status:
          type: string
          enum:
            - untested
            - active
            - paused
          description: >
            `untested` — no call answered on your app since you connected or
            turned it

            back on. `active` — the last answered call ran on your app. `paused`
            —

            Telnyx refused your key, your app is gone, or Telnyx refused 5 calls
            in a

            row; every number on the account is paused (`is_active: false`)
            until you

            fix the cause and call
            [reactivate](/api-reference/carrier-accounts/reactivate).
        pause_reason:
          type: string
          nullable: true
          enum:
            - key_rejected
            - connection_invalid
            - carrier_rejections
        last_error:
          type: object
          nullable: true
          properties:
            code:
              type: string
              description: >-
                `carrier_rejected`, `key_rejected`, `connection_invalid`,
                `public_key_mismatch`, `connection_mismatch`, `inbound_on_app`
                or `number_released`.
            sip_code:
              type: string
              nullable: true
              example: '403'
              description: >-
                The SIP code Telnyx ended a ringing call with (`401`, `403`,
                `407`, …). `null` when Telnyx refused over its API instead: the
                call itself before it rang, a command on it, or a test.
            at:
              type: string
              format: date-time
              nullable: true
        last_success_at:
          type: string
          format: date-time
          nullable: true
        last_tested_at:
          type: string
          format: date-time
          nullable: true
        numbers:
          type: array
          items:
            $ref: '#/components/schemas/PhoneNumber'
        webhook_url:
          type: string
          format: uri
          description: >
            The exact webhook URL a Call Control App you made must use. Returned
            only

            to workspace owners and admins, and to API keys with

            `carrier_accounts:manage`. It carries a secret for your account:
            treat it

            like a password.
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
    PhoneNumber:
      type: object
      properties:
        id:
          type: string
          format: uuid
        number:
          type: string
          example: '+972551234567'
        friendly_name:
          type: string
          nullable: true
        provider:
          type: string
          description: >
            Where the number comes from: `telnyx` for a number bought from
            Yappr,

            `external` for a number in your own Telnyx account, added to a

            [carrier account](/api-reference/carrier-accounts/add-number).
        status:
          type: string
          enum:
            - active
            - pending_requirements
            - suspended
        is_active:
          type: boolean
        inbound_agent_id:
          type: string
          format: uuid
          nullable: true
        outbound_agent_id:
          type: string
          format: uuid
          nullable: true
        sip_inbound_configured:
          type: boolean
        sip_outbound_configured:
          type: boolean
        country_code:
          type: string
          nullable: true
        monthly_cost:
          type: number
          nullable: true
        created_at:
          type: string
          format: date-time
        carrier_account:
          type: object
          nullable: true
          description: >
            The Telnyx account an `external` number calls through. `null` on
            numbers

            bought from Yappr.
          properties:
            id:
              type: string
              format: uuid
            name:
              type: string
            provider:
              type: string
              enum:
                - telnyx
            status:
              type: string
              enum:
                - untested
                - active
                - paused
        ownership_verified_at:
          type: string
          format: date-time
          nullable: true
          description: >
            When your Telnyx API key last proved that this `external` number is
            an

            active number in your account. `null` means Telnyx no longer lists
            it: the

            number is not callable until a
            [test](/api-reference/carrier-accounts/test)

            finds it again. Always `null` on numbers bought from Yappr.
    Error:
      type: object
      properties:
        error:
          type: string
        code:
          type: string
  responses:
    CarrierAccountsNotEnabled:
      description: >
        `CARRIER_ACCOUNTS_NOT_ENABLED` — Yappr has switched calling out through
        your own

        Telnyx account off for this workspace. It is available in every
        workspace, so this

        is only the emergency-off answer; contact Yappr support. Every
        carrier-accounts

        route answers this while it is off (check with

        [GET /carrier-accounts/status](/api-reference/carrier-accounts/status)).
        An API key

        without the route's scope gets a 403 of its own.
      content:
        application/json:
          schema:
            allOf:
              - $ref: '#/components/schemas/Error'
              - type: object
                properties:
                  enabled:
                    type: boolean
                    example: false
          example:
            error: >-
              Calling out through your own Telnyx account is switched off for
              this workspace. Contact Yappr support.
            code: CARRIER_ACCOUNTS_NOT_ENABLED
            enabled: false
  securitySchemes:
    apiKey:
      type: http
      scheme: bearer
      bearerFormat: API Key
      description: >-
        Your Yappr API key (e.g. `ypr_live_...`). Generate one in the dashboard
        under **Settings → API Keys**.

````