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
Code
What it means
ESIM_ALREADY_EXISTS
The 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_PROGRESS
An order for this number is still provisioning. Wait for partner.esim.ready or partner.esim.failed.
ESIM_ORDER_NEEDS_SUPPORT
A 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_FOUND
holder_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
401402Billing 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
429500eSIMs cannot be ordered for this account right now (ESIM_UNAVAILABLE).