Skip to main content
POST
Add number
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 first to see the amount.

Request

The body is a number preference, the same as number_preference on 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. 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 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 before you retry.

Errors

Response

  • phone_number is the new number, in E.164 format. It also appears in the account’s phone_numbers on 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.

Authorizations

Authorization
string
header
required

Headers

Idempotency-Key
string

Optional. 8 to 100 letters, digits, - or _, for example a UUID. Retrying with the same key does not charge you twice.

Pattern: ^[A-Za-z0-9_-]{8,100}$

Path Parameters

id
string
required

The account id returned by Create account (usr-*).

Body

application/json
country
string
required

ISO country code.

Example:

"FR"

prefix
string | null

Optional. Digits the number should start with, after the country code, for example +337 or 7.

Example:

"7"

esim
boolean | null

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

Response

Number added

data
object