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

`POST /v2/api/partner/accounts/{id}/numbers`

<Note>
**Required scope:** `PARTNER`
</Note>

Adds a phone number to one of your accounts. The response returns the new number and whether it was charged. Call [Get number price](/docs/white-label/get-number-price) first to see the amount.

## Request

The body is a number preference, the same as `number_preference` on [Create account](/docs/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](/docs/white-label/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](/docs/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](/docs/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](/docs/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](/docs/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.
