> ## 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. # Add Number to Carrier Account > Add a number you own in the connected Telnyx account. Yappr asks Telnyx, with your key, whether it is an active number in your account, and adds it only if it is. It becomes a phone number of your workspace with `provider: external`: use it as `from` on [POST /calls](/api-reference/calls/create), as a campaign's number, or as an agent's outbound number. Requires `carrier_accounts:manage`. Limit: 50 per workspace per day. Add a number you own in the connected Telnyx account. Yappr asks Telnyx, **with your API key**, whether it is an active number in your account, and adds it only if it is. It becomes a phone number of your workspace with `provider: "external"`, and from then on it works everywhere a number you bought does for outbound: `from` on [POST /calls](/api-reference/calls/create), a campaign's number, or the number an outbound agent calls from. Requires `carrier_accounts:manage`. [Choose the Call Control App](/api-reference/carrier-accounts/connection) first. ```bash theme={null} curl -X POST https://api.goyappr.com/carrier-accounts/7c1e…/numbers \ -H "Authorization: Bearer ypr_live_..." \ -H "Content-Type: application/json" \ -d '{ "number": "+972501234567", "friendly_name": "Sales line", "outbound_agent_id": "5b0f…" }' ``` ```json theme={null} { "data": { "id": "e2a4…", "number": "+972501234567", "friendly_name": "Sales line", "provider": "external", "status": "active", "is_active": true, "inbound_agent_id": null, "outbound_agent_id": "5b0f…", "sip_inbound_configured": false, "sip_outbound_configured": true, "country_code": "IL", "monthly_cost": null, "created_at": "2026-09-23T10:02:00Z", "carrier_account": { "id": "7c1e…", "name": "Main Telnyx account", "provider": "telnyx", "status": "untested" }, "ownership_verified_at": "2026-09-23T10:02:00Z" } } ``` ## Outbound only Calls **to** the number keep going where they go today in Telnyx. The agent calls out from it but does not answer it. Setting `inbound_agent_id` on it answers `422 INBOUND_NOT_AVAILABLE_ON_EXTERNAL_NUMBER`. To have an agent answer, route the number in Telnyx to a [SIP endpoint](/api-reference/sip-endpoints/create). Leave the number's own settings in Telnyx as they are. ## A number someone else registered Every number is in Yappr once. If another workspace registered your number but its Telnyx key no longer proves it, Yappr releases that claim and adds the number to you. If it is a number bought from Yappr, or its holder still proves it, the answer is `409 NUMBER_ALREADY_REGISTERED`, which does not say where. The same `409` comes back when the lapsed claim is still in use there (a campaign calls from it, or past calls were made from it): that claim is switched off so it can never call, but it is not removed, so the other workspace's history stays intact. Contact Yappr support to move the number. ## Errors | Status | `code` | Meaning | | ------ | --------------------------------------------------- | ---------------------------------------------------------------------------------- | | 400 | `INVALID_NUMBER` | Not E.164. `+972` numbers are `+972` followed by 8 or 9 digits. | | 400 | `INVALID_AGENT` | `outbound_agent_id` is not an agent in this workspace. | | 400 | `INVALID_NAME`, `INVALID_JSON` | Fix the field named in `error`. | | 403 | `CARRIER_ACCOUNTS_NOT_ENABLED` | Yappr has switched carrier accounts off for this workspace. Contact Yappr support. | | 404 | `CARRIER_ACCOUNT_NOT_FOUND` | Not in this workspace. | | 409 | `CONNECTION_REQUIRED` | Choose the Call Control App first. | | 409 | `NUMBER_ALREADY_REGISTERED` | The number is in use in Yappr, or held by a lapsed claim still in use there. | | 422 | `NUMBER_NOT_IN_YOUR_TELNYX_ACCOUNT` | Telnyx does not list it as an active number in your account. Nothing was added. | | 422 | `TELNYX_KEY_REJECTED` | Telnyx refused the saved key. | | 429 | `RATE_LIMITED` | 50 numbers added in this workspace today. | | 503 | `TELNYX_UNAVAILABLE`, `OWNERSHIP_CHECK_UNAVAILABLE` | Telnyx did not answer. Nothing was added. | ## OpenAPI ````yaml POST /carrier-accounts/{id}/numbers 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}/numbers: parameters: - in: path name: id required: true schema: type: string format: uuid post: tags: - Carrier Accounts summary: Add a number description: > Add a number you own in the connected Telnyx account. Yappr asks Telnyx, with your key, whether it is an active number in your account, and adds it only if it is. It becomes a phone number of your workspace with `provider: external`: use it as `from` on [POST /calls](/api-reference/calls/create), as a campaign's number, or as an agent's outbound number. Requires `carrier_accounts:manage`. Limit: 50 per workspace per day. operationId: addCarrierAccountNumber requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/ExternalNumberCreate' responses: '201': description: Number added content: application/json: schema: type: object properties: data: $ref: '#/components/schemas/PhoneNumber' '400': description: '`INVALID_NUMBER`, `INVALID_NAME`, `INVALID_AGENT` 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' '409': description: >- `CONNECTION_REQUIRED` — choose the app first. `NUMBER_ALREADY_REGISTERED` — the number is in use in Yappr, or held by another workspace's lapsed claim that a campaign or past calls still use (that claim is switched off, not removed; support can move the number). content: application/json: schema: $ref: '#/components/schemas/Error' '422': description: '`NUMBER_NOT_IN_YOUR_TELNYX_ACCOUNT` or `TELNYX_KEY_REJECTED`.' content: application/json: schema: $ref: '#/components/schemas/Error' '429': description: '`RATE_LIMITED`.' content: application/json: schema: $ref: '#/components/schemas/Error' '503': description: >- `TELNYX_UNAVAILABLE` or `OWNERSHIP_CHECK_UNAVAILABLE`. Nothing was added; try again. content: application/json: schema: $ref: '#/components/schemas/Error' components: schemas: ExternalNumberCreate: type: object required: - number properties: number: type: string example: '+972501234567' description: >- An active number in the Telnyx account you connected, in E.164 (`+972` numbers are 12 or 13 characters). Yappr checks it with your key before adding it. friendly_name: type: string maxLength: 100 nullable: true outbound_agent_id: type: string format: uuid nullable: true description: The agent that calls from this number by default. 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**. ````