Order eSIM
curl --request POST \
--url https://api.withallo.com/v2/api/partner/accounts/{account_id}/esims \
--header 'Authorization: <api-key>' \
--header 'Content-Type: application/json' \
--data '
{
"phone_number": "+33745805999",
"tier": "ESIM_20GB",
"identity": {
"corporate_name": "Plomberie Martin",
"postal_address": "12 rue de la Paix",
"postal_code": "75001",
"city": "Paris",
"first_name": "Jean",
"last_name": "Martin",
"email": "[email protected]"
}
}
'import requests
url = "https://api.withallo.com/v2/api/partner/accounts/{account_id}/esims"
payload = {
"phone_number": "+33745805999",
"tier": "ESIM_20GB",
"identity": {
"corporate_name": "Plomberie Martin",
"postal_address": "12 rue de la Paix",
"postal_code": "75001",
"city": "Paris",
"first_name": "Jean",
"last_name": "Martin",
"email": "[email protected]"
}
}
headers = {
"Authorization": "<api-key>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: '<api-key>', 'Content-Type': 'application/json'},
body: JSON.stringify({
phone_number: '+33745805999',
tier: 'ESIM_20GB',
identity: {
corporate_name: 'Plomberie Martin',
postal_address: '12 rue de la Paix',
postal_code: '75001',
city: 'Paris',
first_name: 'Jean',
last_name: 'Martin',
email: '[email protected]'
}
})
};
fetch('https://api.withallo.com/v2/api/partner/accounts/{account_id}/esims', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.withallo.com/v2/api/partner/accounts/{account_id}/esims",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'phone_number' => '+33745805999',
'tier' => 'ESIM_20GB',
'identity' => [
'corporate_name' => 'Plomberie Martin',
'postal_address' => '12 rue de la Paix',
'postal_code' => '75001',
'city' => 'Paris',
'first_name' => 'Jean',
'last_name' => 'Martin',
'email' => '[email protected]'
]
]),
CURLOPT_HTTPHEADER => [
"Authorization: <api-key>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.withallo.com/v2/api/partner/accounts/{account_id}/esims"
payload := strings.NewReader("{\n \"phone_number\": \"+33745805999\",\n \"tier\": \"ESIM_20GB\",\n \"identity\": {\n \"corporate_name\": \"Plomberie Martin\",\n \"postal_address\": \"12 rue de la Paix\",\n \"postal_code\": \"75001\",\n \"city\": \"Paris\",\n \"first_name\": \"Jean\",\n \"last_name\": \"Martin\",\n \"email\": \"[email protected]\"\n }\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "<api-key>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.withallo.com/v2/api/partner/accounts/{account_id}/esims")
.header("Authorization", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"phone_number\": \"+33745805999\",\n \"tier\": \"ESIM_20GB\",\n \"identity\": {\n \"corporate_name\": \"Plomberie Martin\",\n \"postal_address\": \"12 rue de la Paix\",\n \"postal_code\": \"75001\",\n \"city\": \"Paris\",\n \"first_name\": \"Jean\",\n \"last_name\": \"Martin\",\n \"email\": \"[email protected]\"\n }\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.withallo.com/v2/api/partner/accounts/{account_id}/esims")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"phone_number\": \"+33745805999\",\n \"tier\": \"ESIM_20GB\",\n \"identity\": {\n \"corporate_name\": \"Plomberie Martin\",\n \"postal_address\": \"12 rue de la Paix\",\n \"postal_code\": \"75001\",\n \"city\": \"Paris\",\n \"first_name\": \"Jean\",\n \"last_name\": \"Martin\",\n \"email\": \"[email protected]\"\n }\n}"
response = http.request(request)
puts response.read_body{
"data": {
"id": "eso-2F6A1C9D4B7E8A0F3D5C6B9A1E2F4D7C8B0A3E61",
"account_id": "usr-575966AF3661061265263C58882BC409D2A427B8",
"partner_client_ref": "crm-12345",
"phone_number": "+33745805999",
"tier": "ESIM_20GB",
"scheduled_tier": null,
"scheduled_tier_at": null,
"status": "PROVISIONING",
"failure_code": null,
"data": null,
"created_at": "2026-10-14T10:05:00"
}
}{
"error": {}
}{
"error": {
"type": "<string>",
"code": "<string>",
"message": "<string>",
"retryable": true,
"request_id": "<string>",
"retry_after_seconds": 123
}
}{
"error": {}
}{
"error": {}
}{
"error": {}
}{
"error": {}
}{
"error": {
"type": "<string>",
"code": "<string>",
"message": "<string>",
"retryable": true,
"request_id": "<string>",
"retry_after_seconds": 123
}
}{
"error": {}
}eSIM
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 draws on your prepaid credit first, then charges your card on file for the rest. The eSIM is returned with status PROVISIONING and is usually ready 5 to 15 minutes later: Allo then sends the partner.esim.ready webhook. A number whose eSIM was revoked can get a new eSIM: the order charges the setup fee again. A card that requires 3D Secure is refused with ESIM_PAYMENT_FAILED. Requires the PARTNER scope.
POST
/
v2
/
api
/
partner
/
accounts
/
{account_id}
/
esims
Order eSIM
curl --request POST \
--url https://api.withallo.com/v2/api/partner/accounts/{account_id}/esims \
--header 'Authorization: <api-key>' \
--header 'Content-Type: application/json' \
--data '
{
"phone_number": "+33745805999",
"tier": "ESIM_20GB",
"identity": {
"corporate_name": "Plomberie Martin",
"postal_address": "12 rue de la Paix",
"postal_code": "75001",
"city": "Paris",
"first_name": "Jean",
"last_name": "Martin",
"email": "[email protected]"
}
}
'import requests
url = "https://api.withallo.com/v2/api/partner/accounts/{account_id}/esims"
payload = {
"phone_number": "+33745805999",
"tier": "ESIM_20GB",
"identity": {
"corporate_name": "Plomberie Martin",
"postal_address": "12 rue de la Paix",
"postal_code": "75001",
"city": "Paris",
"first_name": "Jean",
"last_name": "Martin",
"email": "[email protected]"
}
}
headers = {
"Authorization": "<api-key>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: '<api-key>', 'Content-Type': 'application/json'},
body: JSON.stringify({
phone_number: '+33745805999',
tier: 'ESIM_20GB',
identity: {
corporate_name: 'Plomberie Martin',
postal_address: '12 rue de la Paix',
postal_code: '75001',
city: 'Paris',
first_name: 'Jean',
last_name: 'Martin',
email: '[email protected]'
}
})
};
fetch('https://api.withallo.com/v2/api/partner/accounts/{account_id}/esims', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.withallo.com/v2/api/partner/accounts/{account_id}/esims",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'phone_number' => '+33745805999',
'tier' => 'ESIM_20GB',
'identity' => [
'corporate_name' => 'Plomberie Martin',
'postal_address' => '12 rue de la Paix',
'postal_code' => '75001',
'city' => 'Paris',
'first_name' => 'Jean',
'last_name' => 'Martin',
'email' => '[email protected]'
]
]),
CURLOPT_HTTPHEADER => [
"Authorization: <api-key>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.withallo.com/v2/api/partner/accounts/{account_id}/esims"
payload := strings.NewReader("{\n \"phone_number\": \"+33745805999\",\n \"tier\": \"ESIM_20GB\",\n \"identity\": {\n \"corporate_name\": \"Plomberie Martin\",\n \"postal_address\": \"12 rue de la Paix\",\n \"postal_code\": \"75001\",\n \"city\": \"Paris\",\n \"first_name\": \"Jean\",\n \"last_name\": \"Martin\",\n \"email\": \"[email protected]\"\n }\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "<api-key>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.withallo.com/v2/api/partner/accounts/{account_id}/esims")
.header("Authorization", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"phone_number\": \"+33745805999\",\n \"tier\": \"ESIM_20GB\",\n \"identity\": {\n \"corporate_name\": \"Plomberie Martin\",\n \"postal_address\": \"12 rue de la Paix\",\n \"postal_code\": \"75001\",\n \"city\": \"Paris\",\n \"first_name\": \"Jean\",\n \"last_name\": \"Martin\",\n \"email\": \"[email protected]\"\n }\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.withallo.com/v2/api/partner/accounts/{account_id}/esims")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"phone_number\": \"+33745805999\",\n \"tier\": \"ESIM_20GB\",\n \"identity\": {\n \"corporate_name\": \"Plomberie Martin\",\n \"postal_address\": \"12 rue de la Paix\",\n \"postal_code\": \"75001\",\n \"city\": \"Paris\",\n \"first_name\": \"Jean\",\n \"last_name\": \"Martin\",\n \"email\": \"[email protected]\"\n }\n}"
response = http.request(request)
puts response.read_body{
"data": {
"id": "eso-2F6A1C9D4B7E8A0F3D5C6B9A1E2F4D7C8B0A3E61",
"account_id": "usr-575966AF3661061265263C58882BC409D2A427B8",
"partner_client_ref": "crm-12345",
"phone_number": "+33745805999",
"tier": "ESIM_20GB",
"scheduled_tier": null,
"scheduled_tier_at": null,
"status": "PROVISIONING",
"failure_code": null,
"data": null,
"created_at": "2026-10-14T10:05:00"
}
}{
"error": {}
}{
"error": {
"type": "<string>",
"code": "<string>",
"message": "<string>",
"retryable": true,
"request_id": "<string>",
"retry_after_seconds": 123
}
}{
"error": {}
}{
"error": {}
}{
"error": {}
}{
"error": {}
}{
"error": {
"type": "<string>",
"code": "<string>",
"message": "<string>",
"retryable": true,
"request_id": "<string>",
"retry_after_seconds": 123
}
}{
"error": {}
}Required scope:
PARTNERPROVISIONING. The eSIM is usually ready 5 to 15 minutes later, and Allo then sends you the partner.esim.ready webhook.
Request
phone_numberis required. It must be one of the account’s numbers, or one of its members’ numbers, created withnumber_preference.esimset totrue(see Create account, Add number and Add member). Any other number fails withPARTNER_ESIM_NUMBER_NOT_FOUNDorESIM_NOT_ELIGIBLE.tieris required: acodefrom Get eSIM offer, for exampleESIM_20GB. An unknown code fails withINVALID_ESIM_TIER.holder_idis 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’sidfrom Add member or List members. This includes a number the member took over withphone_number.identityis required: the business the line is registered to.corporate_name,postal_address,postal_code(5 digits) andcityare required.first_name,last_name,company_name,siret,nafandemailare optional. A missing required field fails withESIM_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 newIdempotency-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
PROVISIONINGuntil 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 isretryable: true, retry in a few minutes.
Retries
Send anIdempotency-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. |
Headers
Body
application/json
Was this page helpful?