> ## Documentation Index > Fetch the complete documentation index at: https://help.withallo.com/llms.txt > Use this file to discover all available pages before exploring further. # Add number > Adds a phone number to one of your accounts. The number is billed on the account's subscription, which you pay: Allo draws on your prepaid credit first, then charges your card on file for the rest. When the account already pays for a number slot that no number uses, the new number takes that slot and nothing is charged (`charged: false`). Allo checks that a number is available before charging anything. Requires the `PARTNER` scope. **Required scope:** `PARTNER` Adds a phone number to one of your accounts. The response returns the new number and whether it was charged. Call [Get number price](/en/v2/api-reference/partner/get-number-price) first to see the amount. ## Request The body is a number preference, the same as `number_preference` on [Create account](/en/v2/api-reference/partner/create-account): * `country` is required (ISO country code, for example `FR`). An unknown country fails with `INVALID_NUMBER_PREFERENCE`. * `prefix` is optional: the digits the number should start with, for example `7` or `+337`. * `esim` is optional, `false` by default. Set it to `true` to get a French mobile number that can carry an eSIM, which you then order with [Order eSIM](/en/v2/api-reference/partner/order-esim). With any `country` other than `FR`, the request fails with `ESIM_NOT_AVAILABLE_IN_COUNTRY`. `{id}` is the account id returned by Create account. An account your API key did not create, or one already deactivated, returns `404 PARTNER_ACCOUNT_NOT_FOUND`. ## Billing * The number is billed on the account's subscription, which you pay. Allo draws on your [prepaid credit](/en/v2/api-reference/partner/get-credit) first, then charges your card on file for the rest. Allo never charges your customer. * Allo charges the rest of the account's current billing period now, with the subscription's discount applied. The number then renews with the subscription. * If the account already pays for a number slot that no number uses, the new number takes that slot and nothing is charged. The response then has `charged: false`. * Allo checks that a number is available before charging anything. If none matches the country and prefix, the request fails with `409 NO_NUMBER_AVAILABLE` and nothing is charged. A country that needs the account's regulatory verification first fails with `409 REGULATORY_VERIFICATION_REQUIRED`, also before any charge. * If your prepaid credit does not cover the charge and you have no card on file, the request fails with `402 PARTNER_CREDIT_INSUFFICIENT` and nothing is created. Top up your credit or add a card, then retry with a new `Idempotency-Key`. * A declined card fails with `402 PARTNER_BILLING_FAILED`, and nothing is created. * If the number cannot be set up after the charge, Allo takes the charge back off the subscription and credits the unused period to your balance. ## Retries Send an `Idempotency-Key` header (8 to 100 letters, digits, `-` or `_`, for example a UUID) and reuse it when you retry the same request. Retrying with the same key does not charge you twice. A key in another format fails with `INVALID_IDEMPOTENCY_KEY`. If you are not sure an earlier attempt went through, check the account's `phone_numbers` with [Get account](/en/v2/api-reference/partner/get-account) before you retry. ## Errors | Code | What it means | | - | - | | `PARTNER_ACCOUNT_BUSY` | Another number or member is being added to this account right now. Always `retryable: true`: retry in a few seconds. | | `IDEMPOTENCY_KEY_ALREADY_USED` | An earlier attempt already used this `Idempotency-Key`. Check the account's numbers with [Get account](/en/v2/api-reference/partner/get-account) before you retry with a new key. | | `PARTNER_ACCOUNT_DEACTIVATING` | The account is being deactivated at the end of its billing period, so it takes no more numbers. | | `PARTNER_ACCOUNT_SUBSCRIPTION_CONFLICT` | The account's subscription cannot be billed right now. When `retryable` is `true`, retry in a few minutes. Otherwise write to [partnership@themobilefirst.co](mailto:partnership@themobilefirst.co). | | `PARTNER_SUBSCRIPTION_NOT_BILLABLE` | The account has no subscription Allo can bill (`402`). | | `PARTNER_BILLING_UNAVAILABLE` | Billing is temporarily unavailable (`500`). Retry with the same `Idempotency-Key`, which resumes the same charge. | | `PARTNER_NUMBER_SETUP_FAILED` | The number could not be set up (`500`), and the charge was taken back. Do not retry: write to [partnership@themobilefirst.co](mailto:partnership@themobilefirst.co). | | `PARTNER_NUMBER_KEPT` | The number was assigned but its setup did not complete (`500`). It stays on the account and on its billing. Do not retry, since a retry would add another number: write to [partnership@themobilefirst.co](mailto:partnership@themobilefirst.co) with the number. | ## Response * `phone_number` is the new number, in E.164 format. It also appears in the account's `phone_numbers` on [Get account](/en/v2/api-reference/partner/get-account). * `country` is the country as Allo names it: `GB` comes back as `UK`. * `charged` is `true` when a new slot was charged, `false` when the number took a slot the account already paid for. ## OpenAPI ````yaml POST /v2/api/partner/accounts/{id}/numbers openapi: 3.0.3 info: title: Allo API description: >- Allo API provides programmatic access to your Allo account, allowing you to manage webhooks, retrieve calls and contacts, and send SMS messages. All requests to `/v1/api/**` endpoints automatically go through quota checking and scope validation. version: 1.0.0 contact: name: Allo Support servers: - url: https://api.withallo.com description: Production server security: [] tags: - name: Summary Templates description: >- Manage call summary templates that control how AI-generated call summaries are structured for your team. - name: Webhooks description: >- Manage webhook endpoints to receive real-time notifications about events in your Allo account. Each endpoint subscribes to one or more event topics and is verified with a signing secret. - name: Calls description: >- Retrieve and search call records with filtering and pagination. Filter calls by your Allo phone number. - name: Contacts description: >- Search and retrieve contact information with sorting and pagination. Includes engagement level tracking. - name: SMS description: Send SMS messages to phone numbers using your Allo numbers. - name: Phone Numbers description: Retrieve information about your Allo phone numbers. - name: Analytics description: Pre-computed call metrics, team performance, and outbound dial funnel - name: CRM description: Manage people, companies, and deals in your CRM. - name: Notes description: >- Internal team notes on conversations and CRM people, with @mention support. Notes are never visible to the contact. - name: Threads description: >- Team discussion threads attached to a conversation item (call, SMS, or conversation note). One thread per item. - name: AI Receptionist description: >- Read and write the AI receptionist configuration of a phone line: business details, voice, prompt, capabilities, business hours, transfer rules, scheduling calendars and knowledge sources. paths: /v2/api/partner/accounts/{id}/numbers: post: tags: - Partner summary: Add number description: >- Adds a phone number to one of your accounts. The number is billed on the account's subscription, which you pay: Allo draws on your prepaid credit first, then charges your card on file for the rest. When the account already pays for a number slot that no number uses, the new number takes that slot and nothing is charged (`charged: false`). Allo checks that a number is available before charging anything. Requires the `PARTNER` scope. operationId: addPartnerAccountNumber parameters: - name: id in: path required: true schema: type: string description: The account id returned by Create account (`usr-*`). - name: Idempotency-Key in: header required: false schema: type: string pattern: ^[A-Za-z0-9_-]{8,100}$ description: >- Optional. 8 to 100 letters, digits, `-` or `_`, for example a UUID. Retrying with the same key does not charge you twice. example: 550e8400-e29b-41d4-a716-446655440000 requestBody: required: true content: application/json: schema: type: object required: - country properties: country: type: string description: ISO country code. example: FR prefix: type: string nullable: true example: '7' description: >- Optional. Digits the number should start with, after the country code, for example `+337` or `7`. esim: type: boolean nullable: true description: >- Optional, default `false`. Set to `true` to get a French mobile number that can carry an eSIM, which you can then order with `POST /v2/api/partner/accounts/{account_id}/esims`. eSIM numbers are only available with `country` set to `FR`, otherwise the request fails with `ESIM_NOT_AVAILABLE_IN_COUNTRY`. example: true example: country: FR prefix: '7' esim: true responses: '201': description: Number added content: application/json: schema: type: object properties: data: type: object properties: phone_number: type: string description: The number added to the account, in E.164 format. example: '+33745805222' country: type: string description: >- The number's country, as Allo names it (`GB` is returned as `UK`). example: FR charged: type: boolean description: >- `false` when the number took a slot the account already paid for, `true` when a new slot was charged. example: true example: data: phone_number: '+33745805222' country: FR charged: true '400': description: >- Validation error: MISSING_FIELD (`country`), INVALID_NUMBER_PREFERENCE (unknown country), ESIM_NOT_AVAILABLE_IN_COUNTRY or INVALID_IDEMPOTENCY_KEY. content: application/json: schema: type: object properties: error: type: object '401': $ref: '#/components/responses/ApiUnauthorized' '402': description: >- Billing error, nothing is created. PARTNER_CREDIT_INSUFFICIENT: your prepaid credit does not cover the charge and your billing account has no card on file. PARTNER_BILLING_FAILED: your card was declined. PARTNER_SUBSCRIPTION_NOT_BILLABLE: the account has no subscription Allo can bill. content: application/json: schema: type: object properties: error: type: object '403': description: The API key lacks the PARTNER scope. content: application/json: schema: type: object properties: error: type: object '404': description: >- No account with this id was provisioned by your API key, or the account is deactivated (PARTNER_ACCOUNT_NOT_FOUND). content: application/json: schema: type: object properties: error: type: object '409': description: >- Nothing is charged for NO_NUMBER_AVAILABLE (no number matches the country and prefix) or REGULATORY_VERIFICATION_REQUIRED (the country needs the account's regulatory verification first). Also IDEMPOTENCY_KEY_ALREADY_USED (an earlier attempt used this key), PARTNER_ACCOUNT_BUSY (another number or member is being added to the account, `retryable: true`), PARTNER_ACCOUNT_DEACTIVATING (the account is being deactivated) or PARTNER_ACCOUNT_SUBSCRIPTION_CONFLICT (the account's subscription cannot be billed right now; retry when `retryable` is `true`). content: application/json: schema: type: object properties: error: type: object '429': $ref: '#/components/responses/ApiRateLimited' '500': description: >- PARTNER_BILLING_UNAVAILABLE: billing is temporarily unavailable, retry with the same Idempotency-Key. PARTNER_NUMBER_SETUP_FAILED: the number could not be set up, and Allo took the charge back. PARTNER_NUMBER_KEPT: the number was assigned but its setup did not complete, and it stays on the account and its billing. Do not retry these two: write to partnership@themobilefirst.co. content: application/json: schema: type: object properties: error: type: object security: - ApiKeyAuth: [] components: responses: ApiUnauthorized: description: Invalid or missing API key content: application/json: schema: $ref: '#/components/schemas/ApiError' ApiRateLimited: description: Rate limit exceeded content: application/json: schema: $ref: '#/components/schemas/ApiError' schemas: ApiError: type: object properties: error: type: object properties: type: type: string code: type: string message: type: string retryable: type: boolean request_id: type: string retry_after_seconds: type: integer nullable: true securitySchemes: ApiKeyAuth: type: apiKey in: header name: Authorization ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.