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",
"status": "PROVISIONING",
"failure_code": 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": {}
}Order eSIM
Orders an eSIM for one of the account’s numbers. The setup fee and the first period of the tier are charged to your payment method on file, on the subscription you pay for the account. 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 card that requires 3D Secure is refused with ESIM_PAYMENT_FAILED. Requires the PARTNER scope.
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",
"status": "PROVISIONING",
"failure_code": 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": {}
}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, created withnumber_preference.esimset totrue(see Create account). 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.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 to your payment method, on the subscription you pay for the account, with your partner discount applied. Allo never charges your client.
- A card that requires 3D Secure is refused with
402 ESIM_PAYMENT_FAILED, as on Create account. A missing or declined payment method fails the same way. Nothing is left pending: update your payment method in the partner portal, then retry. - 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. Read it with Get eSIM. |
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. |
Authorizations
Headers
Optional. 8 to 100 letters, digits, - or _, for example a UUID. Retrying with the same key does not charge you twice.
^[A-Za-z0-9_-]{8,100}$Path Parameters
The account id returned by Create account (usr-*).
Body
One of the account's numbers, created with number_preference.esim set to true.
"+33745805999"
A tier code from Get eSIM offer.
"ESIM_20GB"
The business the line is registered to.
Show child attributes
Show child attributes
Optional. The Allo user the eSIM is registered to. Defaults to the account itself.
null
Response
eSIM ordered
Show child attributes
Show child attributes
Was this page helpful?