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

# Update Carrier Account

> Rename it, or replace its API key or public key. Requires `carrier_accounts:manage`. Limit: 20 per workspace per day.

Rename the account, or replace its API key or public key. Send at least one field.
Requires `carrier_accounts:manage`.

```bash theme={null}
curl -X PATCH https://api.goyappr.com/carrier-accounts/7c1e… \
  -H "Authorization: Bearer ypr_live_..." \
  -H "Content-Type: application/json" \
  -d '{ "api_key": "KEY0199…new" }'
```

A new `api_key` must be from **the same Telnyx account**: Yappr checks that it can see
the account's Call Control App, or answers `422 KEY_ACCOUNT_MISMATCH`. Calls already
in progress switch to the new key on their own, so you can switch the old key off in
Telnyx right away.

A new `public_key` is checked again on the next call event. Until it verifies, call
events are accepted on the account's secret webhook URL.

## Errors

| Status | `code`                                                                                       | Meaning                                        |
| ------ | -------------------------------------------------------------------------------------------- | ---------------------------------------------- |
| 400    | `NOTHING_TO_UPDATE`, `INVALID_NAME`, `INVALID_API_KEY`, `INVALID_PUBLIC_KEY`, `INVALID_JSON` | Fix the field named in `error`.                |
| 404    | `CARRIER_ACCOUNT_NOT_FOUND`                                                                  | Not in this workspace.                         |
| 422    | `TELNYX_KEY_REJECTED`, `KEY_ACCOUNT_MISMATCH`, `KEY_IS_YAPPR_ACCOUNT`                        | The new key was not accepted. Nothing changed. |
| 429    | `RATE_LIMITED`                                                                               | 20 updates in this workspace today.            |
| 503    | `TELNYX_UNAVAILABLE`                                                                         | Telnyx did not answer. Nothing changed.        |


## OpenAPI

````yaml PATCH /carrier-accounts/{id}
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/{id}:
    parameters:
      - in: path
        name: id
        required: true
        schema:
          type: string
          format: uuid
    patch:
      tags:
        - Carrier Accounts
      summary: Update carrier account
      description: >-
        Rename it, or replace its API key or public key. Requires
        `carrier_accounts:manage`. Limit: 20 per workspace per day.
      operationId: updateCarrierAccount
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CarrierAccountUpdate'
      responses:
        '200':
          description: Updated
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/CarrierAccount'
        '400':
          description: >-
            `NOTHING_TO_UPDATE`, `INVALID_NAME`, `INVALID_API_KEY`,
            `INVALID_PUBLIC_KEY` or `INVALID_JSON`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          $ref: '#/components/responses/CarrierAccountsNotEnabled'
        '404':
          description: '`CARRIER_ACCOUNT_NOT_FOUND` — not in this workspace.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '422':
          description: >-
            `TELNYX_KEY_REJECTED`, `KEY_ACCOUNT_MISMATCH` (the new key is from
            another Telnyx account) or `KEY_IS_YAPPR_ACCOUNT`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: '`RATE_LIMITED`.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '503':
          description: >-
            `TELNYX_UNAVAILABLE` — Telnyx did not answer. Nothing changed; try
            again.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  schemas:
    CarrierAccountUpdate:
      type: object
      description: >
        Send at least one field. A new `api_key` must be from the same Telnyx
        account

        (it must see the account's Call Control App). A new `public_key` is
        verified

        again on the next call event.
      properties:
        name:
          type: string
          minLength: 1
          maxLength: 100
        api_key:
          type: string
          format: password
          writeOnly: true
        public_key:
          type: string
          writeOnly: true
    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
    Error:
      type: object
      properties:
        error:
          type: string
        code:
          type: string
    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.
  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**.

````