Allo

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…

GET/v2/api/partner/esims/{id}

Returns the status of an eSIM you ordered, its tier and its mobile data use this month. The partner.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.

statusWhat it means
PROVISIONINGThe eSIM is ordered and not ready yet. This usually takes 5 to 15 minutes.
ACTIVEThe eSIM is ready. Calls to the number ring the eSIM. Get the activation code to deliver it to your client.
FAILEDThe order did not complete. failure_code gives the reason.
REVOKEDThe 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

  • tier is 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_tier is the tier a scheduled downgrade will switch the eSIM to, and scheduled_tier_at is when, at the end of the period already paid. Both are null when 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.

FieldWhat it means
used_mbMobile data used this month, in MB. null when the network has not reported it yet.
allowance_mbMobile data the eSIM can use this month, in MB: the tier's data plus the top-ups bought this month.
remaining_mballowance_mb minus used_mb, in MB, never below 0. null when used_mb is null.
cycle_started_atStart of the current month, in UTC.
cycle_ends_atEnd 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:00 to 2026-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_low when the eSIM has used 80% of its allowance, and partner.esim.data_exhausted when it has used all of it. You do not need to poll this endpoint to watch the data.

Authorization

Authorizationstring · headerrequired

Api-Key ak_live_…

Path parameters

idstringrequired

The eSIM id returned by Order eSIM (eso-*).

Responses

200eSIM
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 eSIM's current tier code. It changes when an upgrade is paid or a scheduled downgrade applies.

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 for the current cycle, the calendar month in Paris time. null unless status is ACTIVE. Read live from the network on each call: it can lag real use by a few minutes.

5 fields
used_mbinteger<int64> | null

Mobile data used this month, in MB. null when the network has not reported it yet.

allowance_mbinteger<int64>

Mobile data the eSIM can use this month, in MB: the tier's data plus the top-ups bought this month.

remaining_mbinteger<int64> | null

allowance_mb minus used_mb, in MB. null when used_mb is null.

cycle_started_atstring<date-time>

Start of the current cycle, in UTC: midnight on the 1st of the month in Paris time.

cycle_ends_atstring<date-time>

End of the current cycle, in UTC: midnight on the 1st of the next month in Paris time.

created_atstring<date-time>

When the eSIM was ordered.

scheduled_tierstring | null

The tier a scheduled downgrade will switch the eSIM to. null when no downgrade is scheduled.

scheduled_tier_atstring<date-time> | null

When the scheduled downgrade applies: the end of the period already paid. null when no downgrade is scheduled.

401
403The API key lacks the PARTNER scope.
errorobject
404No eSIM with this id was ordered on an account your API key provisioned (PARTNER_ESIM_NOT_FOUND).
errorobject
429