Get eSIM
curl --request GET \
--url https://api.withallo.com/v2/api/partner/esims/{id} \
--header 'Authorization: <api-key>'import requests
url = "https://api.withallo.com/v2/api/partner/esims/{id}"
headers = {"Authorization": "<api-key>"}
response = requests.get(url, headers=headers)
print(response.text)const options = {method: 'GET', headers: {Authorization: '<api-key>'}};
fetch('https://api.withallo.com/v2/api/partner/esims/{id}', 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/esims/{id}",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "GET",
CURLOPT_HTTPHEADER => [
"Authorization: <api-key>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"net/http"
"io"
)
func main() {
url := "https://api.withallo.com/v2/api/partner/esims/{id}"
req, _ := http.NewRequest("GET", url, nil)
req.Header.Add("Authorization", "<api-key>")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.get("https://api.withallo.com/v2/api/partner/esims/{id}")
.header("Authorization", "<api-key>")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.withallo.com/v2/api/partner/esims/{id}")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Get.new(url)
request["Authorization"] = '<api-key>'
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": "ACTIVE",
"failure_code": null,
"data": {
"used_mb": 3172,
"allowance_mb": 25600,
"remaining_mb": 22428,
"cycle_started_at": "2026-10-31T23:00:00",
"cycle_ends_at": "2026-11-30T23:00:00"
},
"created_at": "2026-10-14T10:05:00"
}
}{
"error": {
"type": "<string>",
"code": "<string>",
"message": "<string>",
"retryable": true,
"request_id": "<string>",
"retry_after_seconds": 123
}
}{
"error": {}
}{
"error": {}
}{
"error": {
"type": "<string>",
"code": "<string>",
"message": "<string>",
"retryable": true,
"request_id": "<string>",
"retry_after_seconds": 123
}
}eSIM
Get eSIM
Returns the status of an eSIM you ordered, its current tier and, once it is ACTIVE, its mobile data use this month. Use it to poll for readiness if you do not receive webhooks. Requires the PARTNER scope.
GET
/
v2
/
api
/
partner
/
esims
/
{id}
Get eSIM
curl --request GET \
--url https://api.withallo.com/v2/api/partner/esims/{id} \
--header 'Authorization: <api-key>'import requests
url = "https://api.withallo.com/v2/api/partner/esims/{id}"
headers = {"Authorization": "<api-key>"}
response = requests.get(url, headers=headers)
print(response.text)const options = {method: 'GET', headers: {Authorization: '<api-key>'}};
fetch('https://api.withallo.com/v2/api/partner/esims/{id}', 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/esims/{id}",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "GET",
CURLOPT_HTTPHEADER => [
"Authorization: <api-key>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"net/http"
"io"
)
func main() {
url := "https://api.withallo.com/v2/api/partner/esims/{id}"
req, _ := http.NewRequest("GET", url, nil)
req.Header.Add("Authorization", "<api-key>")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.get("https://api.withallo.com/v2/api/partner/esims/{id}")
.header("Authorization", "<api-key>")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.withallo.com/v2/api/partner/esims/{id}")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Get.new(url)
request["Authorization"] = '<api-key>'
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": "ACTIVE",
"failure_code": null,
"data": {
"used_mb": 3172,
"allowance_mb": 25600,
"remaining_mb": 22428,
"cycle_started_at": "2026-10-31T23:00:00",
"cycle_ends_at": "2026-11-30T23:00:00"
},
"created_at": "2026-10-14T10:05:00"
}
}{
"error": {
"type": "<string>",
"code": "<string>",
"message": "<string>",
"retryable": true,
"request_id": "<string>",
"retry_after_seconds": 123
}
}{
"error": {}
}{
"error": {}
}{
"error": {
"type": "<string>",
"code": "<string>",
"message": "<string>",
"retryable": true,
"request_id": "<string>",
"retry_after_seconds": 123
}
}Required scope:
PARTNERpartner.esim.ready and partner.esim.failed webhooks tell you when the status changes. Without a webhook endpoint, poll this endpoint instead, within the rate limit of 20 read requests per second per key.
status | What it means |
|---|---|
PROVISIONING | The eSIM is ordered and not ready yet. This usually takes 5 to 15 minutes. |
ACTIVE | The eSIM is ready. Calls to the number ring the eSIM. Get the activation code to deliver it to your client. |
FAILED | The order did not complete. failure_code gives the reason. |
REVOKED | The eSIM was revoked, or replaced by a later eSIM on the same number. It no longer works on its phone, and calls to the number ring the Allo apps. |
failure_code is null unless status is FAILED. You can only read eSIMs ordered on accounts your own API key created. Any other id fails with PARTNER_ESIM_NOT_FOUND.
Tier
tieris the eSIM’s current tier. It changes when an upgrade from Change eSIM tier is paid, or when a scheduled downgrade applies. Until then, it is the tier you ordered.scheduled_tieris the tier a scheduled downgrade will switch the eSIM to, andscheduled_tier_atis when, at the end of the period already paid. Both arenullwhen no downgrade is scheduled.
Data use
data gives the eSIM’s mobile data use for the current month. It is null unless status is ACTIVE.
| Field | What it means |
|---|---|
used_mb | Mobile data used this month, in MB. null when the network has not reported it yet. |
allowance_mb | Mobile data the eSIM can use this month, in MB: the tier’s data plus the top-ups bought this month. |
remaining_mb | allowance_mb minus used_mb, in MB, never below 0. null when used_mb is null. |
cycle_started_at | Start of the current month, in UTC. |
cycle_ends_at | End of the current month, in UTC. The next month starts at this time. |
- The cycle is the calendar month in Paris time. The timestamps are in UTC, so in November 2026 the cycle runs from
2026-10-31T23:00:00to2026-11-30T23:00:00. - Allo reads the use live from the network on each call. It can lag real use by a few minutes.
- When the eSIM reaches its allowance, mobile data stops until the next month or until you buy a top-up. Calls and SMS keep working. The line is never billed for data beyond the allowance.
- Allo sends
partner.esim.data_lowwhen the eSIM has used 80% of its allowance, andpartner.esim.data_exhaustedwhen it has used all of it. You do not need to poll this endpoint to watch the data.
Was this page helpful?