Allo

Order eSIM

Orders an eSIM for one of the account's numbers. The setup fee and the first period of the tier are charged on the subscription you pay for the account: Allo…

POST/v2/api/partner/accounts/{account_id}/esims

Orders an eSIM for one of the account's numbers and charges it to your prepaid credit first, then to your card on file. The response returns the eSIM with status PROVISIONING. The eSIM is usually ready 5 to 15 minutes later, and Allo then sends you the partner.esim.ready webhook.

Request

  • phone_number is required. It must be one of the account's numbers, or one of its members' numbers, created with number_preference.esim set to true (see Create account, Add number and Add member). Any other number fails with PARTNER_ESIM_NUMBER_NOT_FOUND or ESIM_NOT_ELIGIBLE.
  • tier is required: a code from Get eSIM offer, for example ESIM_20GB. An unknown code fails with INVALID_ESIM_TIER.
  • holder_id is optional: the Allo user the eSIM is registered to. Leave it out to make the account itself the holder. For a member's number, send the member's id from Add member or List members. This includes a number the member took over with phone_number.
  • identity is required: the business the line is registered to. corporate_name, postal_address, postal_code (5 digits) and city are required. first_name, last_name, company_name, siret, naf and email are optional. A missing required field fails with ESIM_IDENTITY_INCOMPLETE.

Billing

  • The setup fee and the first period of the tier are charged on the subscription you pay for the account, with your partner discount applied. Allo draws on your prepaid credit first, then charges your card on file for the rest. Allo never charges your client.
  • If your prepaid credit does not cover the order and you have no card on file, the request fails with 402 PARTNER_CREDIT_INSUFFICIENT. Top up your credit or add a card, then retry with a new Idempotency-Key.
  • A card that requires 3D Secure is refused with 402 ESIM_PAYMENT_FAILED. A declined card fails the same way. Nothing is left pending: update your card in the partner portal, then retry.
  • A number whose eSIM was revoked can get a new eSIM. The new order charges the setup fee again. If you order it right after the revocation, it stays PROVISIONING until the mobile network has confirmed the revocation.
  • If the subscription you pay for the account cannot take an eSIM right now, the request fails with ESIM_SUBSCRIPTION_CONFLICT. When the error is retryable: true, retry in a few minutes.

Retries

Send an Idempotency-Key header (8 to 100 letters, digits, - or _, for example a UUID) and reuse it when you retry the same order. Retrying with the same key does not charge you twice. A key in another format fails with INVALID_IDEMPOTENCY_KEY.

Errors specific to this number

CodeWhat it means
ESIM_ALREADY_EXISTSThe number already has an eSIM that is not revoked. Read it with Get eSIM, or revoke it to order a new one.
ESIM_ORDER_IN_PROGRESSAn order for this number is still provisioning. Wait for partner.esim.ready or partner.esim.failed.
ESIM_ORDER_NEEDS_SUPPORTA previous order was charged but did not complete, and Allo support is handling it. Write to [email protected] before ordering again.
PARTNER_ESIM_HOLDER_NOT_FOUNDholder_id cannot hold an eSIM for this number. Leave it out to use the account.

Authorization

Authorizationstring · headerrequired

Api-Key ak_live_…

Path parameters

account_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

phone_numberstringrequired

One of the account's numbers that can carry an eSIM: created, added or given to a member with number_preference.esim set to true.

tierstringrequired

A tier code from Get eSIM offer.

holder_idstring | null

Optional. The Allo user the eSIM is registered to: the account itself by default, or the id of a member returned by Add member for the member's own number, including a number the member took over with phone_number.

identityobjectrequired

The business the line is registered to.

10 fields
corporate_namestringrequired
postal_addressstringrequired
postal_codestringrequired

5 digits.

citystringrequired
first_namestring | null
last_namestring | null
company_namestring | null
siretstring | null
nafstring | null
emailstring | null

Responses

201eSIM ordered
dataobject
11 fields
idstring

The eSIM id (eso-*).

account_idstring

The account the eSIM was ordered for.

partner_client_refstring | null

Your own reference, set when the account was created.

phone_numberstring

The number the eSIM carries.

tierstring

The tier code that was ordered.

scheduled_tierstring | null

The tier a scheduled downgrade will switch the eSIM to. Always null on a new order.

scheduled_tier_atstring<date-time> | null

When the scheduled downgrade applies. Always null on a new order.

statusenum<string>

PROVISIONING: ordered, not ready yet. ACTIVE: ready, calls to the number ring the eSIM. FAILED: the order did not complete, see failure_code. REVOKED: the eSIM was revoked, or replaced by a later eSIM on the same number, and no longer works.

PROVISIONINGACTIVEFAILEDREVOKED

failure_codestring | null

Why the order failed. Set only when status is FAILED.

dataobject | null

Mobile data use this month. Always null here, since a new eSIM is not ACTIVE yet: read it with Get eSIM once the eSIM is ready.

created_atstring<date-time>

When the eSIM was ordered.

400Validation error: MISSING_FIELD, INVALID_ESIM_TIER, ESIM_IDENTITY_INCOMPLETE or INVALID_IDEMPOTENCY_KEY.
errorobject
401
402Billing error, nothing is left pending. PARTNER_CREDIT_INSUFFICIENT: your prepaid credit does not cover the order and your billing account has no card on file. ESIM_PAYMENT_FAILED: your card was declined or requires 3D Secure.
errorobject
403The API key lacks the PARTNER scope.
errorobject
404The account was not provisioned by your API key (PARTNER_ACCOUNT_NOT_FOUND), the number does not belong to the account (PARTNER_ESIM_NUMBER_NOT_FOUND), or holder_id cannot hold an eSIM for this number (PARTNER_ESIM_HOLDER_NOT_FOUND).
errorobject
409The number cannot carry an eSIM (ESIM_NOT_ELIGIBLE), already has an eSIM that is not revoked (ESIM_ALREADY_EXISTS), has an order in progress (ESIM_ORDER_IN_PROGRESS) or one handled by Allo support (ESIM_ORDER_NEEDS_SUPPORT), or the subscription you pay for the account cannot take an eSIM right now (ESIM_SUBSCRIPTION_CONFLICT).
errorobject
429
500eSIMs cannot be ordered for this account right now (ESIM_UNAVAILABLE).
errorobject