Allo

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

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

CodeWhat it means
PARTNER_ACCOUNT_BUSYAnother number or member is being added to this account right now. Always retryable: true: retry in a few seconds.
IDEMPOTENCY_KEY_ALREADY_USEDAn earlier attempt already used this Idempotency-Key. Check the account's numbers with Get account before you retry with a new key.
PARTNER_ACCOUNT_DEACTIVATINGThe account is being deactivated at the end of its billing period, so it takes no more numbers.
PARTNER_ACCOUNT_SUBSCRIPTION_CONFLICTThe account's subscription cannot be billed right now. When retryable is true, retry in a few minutes. Otherwise write to [email protected].
PARTNER_SUBSCRIPTION_NOT_BILLABLEThe account has no subscription Allo can bill (402).
PARTNER_BILLING_UNAVAILABLEBilling is temporarily unavailable (500). Retry with the same Idempotency-Key, which resumes the same charge.
PARTNER_NUMBER_SETUP_FAILEDThe number could not be set up (500), and the charge was taken back. Do not retry: write to [email protected].
PARTNER_NUMBER_KEPTThe 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 [email protected] 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.
  • 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.

Authorization

Authorizationstring · headerrequired

Api-Key ak_live_…

Path parameters

idstringrequired

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

Headers

Idempotency-Keystring

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

Body

countrystringrequired

ISO country code.

prefixstring | null

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

esimboolean | 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.

Responses

201Number added
dataobject
3 fields
phone_numberstring

The number added to the account, in E.164 format.

countrystring

The number's country, as Allo names it (GB is returned as UK).

chargedboolean

false when the number took a slot the account already paid for, true when a new slot was charged.

400Validation error: MISSING_FIELD (country), INVALID_NUMBER_PREFERENCE (unknown country), ESIM_NOT_AVAILABLE_IN_COUNTRY or INVALID_IDEMPOTENCY_KEY.
errorobject
401
402Billing 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.
errorobject
403The API key lacks the PARTNER scope.
errorobject
404No account with this id was provisioned by your API key, or the account is deactivated (PARTNER_ACCOUNT_NOT_FOUND).
errorobject
409Nothing 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).
errorobject
429
500PARTNER_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 [email protected].
errorobject