---
title: "Add number"
method: POST
path: "/v2/api/partner/accounts/{id}/numbers"
tags: ["Partner"]
---

# Add number

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

## Request

- Base URL: `https://api.withallo.com`
- URL: `https://api.withallo.com/v2/api/partner/accounts/{id}/numbers`
- Auth: API key in header `Authorization`

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.

## Path parameters

- `id` string, required

## Headers

- `Idempotency-Key` string

## Request body

- object
  - `country` string, required: ISO country code.
  - `prefix` string, nullable: Optional. Digits the number should start with, after the country code, for example `+337` or `7`.
  - `esim` boolean, nullable: 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`.

## Response `201`

Number added

- object
  - `data` object
    - `phone_number` string: The number added to the account, in E.164 format.
    - `country` string: The number's country, as Allo names it (`GB` is returned as `UK`).
    - `charged` boolean: `false` when the number took a slot the account already paid for, `true` when a new slot was charged.

## Other responses

- `400`: Validation error: MISSING_FIELD (`country`), INVALID_NUMBER_PREFERENCE (unknown country), ESIM_NOT_AVAILABLE_IN_COUNTRY or INVALID_IDEMPOTENCY_KEY.
- `401`: Invalid or missing API key
- `402`: 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.
- `403`: The API key lacks the PARTNER scope.
- `404`: No account with this id was provisioned by your API key, or the account is deactivated (PARTNER_ACCOUNT_NOT_FOUND).
- `409`: 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`).
- `429`: Rate limit exceeded
- `500`: 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.

## Changes

- **2026-11-03** `46c77103dd14`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/withallo/apis/allo-api/changes/v2/api/partner/accounts/:id/numbers/post.md)

---

[API](https://skmtc.dev/withallo/apis/allo-api.md) - [All operations](https://skmtc.dev/withallo/apis/allo-api/llms.txt) - [OpenAPI document](https://skmtc.dev/withallo/apis/allo-api/revisions/46c77103dd14?raw)