Get an eSIM

GET/v1/esims/{iccid}esims:read

Returns one eSIM: everything needed to install it, plus how much data is left.

Path parameters

Name	Notes
`iccid`	The ICCID of the eSIM

curl https://partner-api.esimfo.com/v1/esims/89852350326100409575 \
  -H 'Authorization: Bearer esf_live_at_...'

Response `200`

Field	Type	Notes
`id`	string	eSIM id
`iccid`	string \| null	`null` until provisioning succeeds
`lpa_code`	string \| null	Full activation string, `LPA:1$<smdp>$<matching_id>`
`qr_code_url`	string \| null	Hosted QR image — scanning it installs the profile
`smdp_address`	string \| null	SM-DP+ server, for manual entry
`matching_id`	string \| null	Activation code, for manual entry
`status`	enum	See below
`data_total_mb`	integer \| null	`null` on unlimited packages
`data_used_mb`	integer \| null	Consumed so far
`data_remaining_mb`	integer \| null	As reported by the network. `null` before the first sync and on unlimited packages
`expires_at`	string \| null	ISO 8601 UTC. `null` until activation starts the clock
`failure_reason`	string \| null	Why provisioning failed, when it did

{
  "id": "esm_9a3f1c",
  "iccid": "89852350326100409575",
  "lpa_code": "LPA:1$rsp.truphone.com$QR-G-5C-1LK-1V0FS",
  "qr_code_url": "https://cdn.esimfo.com/qr/esm_9a3f1c.png",
  "smdp_address": "rsp.truphone.com",
  "matching_id": "QR-G-5C-1LK-1V0FS",
  "status": "ACTIVE",
  "data_total_mb": 3072,
  "data_used_mb": 512,
  "data_remaining_mb": 2560,
  "expires_at": "2026-09-21T00:00:00.000Z",
  "failure_reason": null
}

eSIM status

Status	Meaning
`PENDING`	Not yet provisioned — no ICCID yet
`PROVISIONED`	Ready to install, not yet used
`ACTIVE`	Installed and consuming data
`DEPLETED`	Data used up. Can be topped up
`EXPIRED`	Past its validity window
`CANCELLED`	Cancelled
`FAILED`	Could not be produced. `failure_reason` says why; the amount was refunded
`REFUNDED`	Refunded by eSIMfo support; the amount was credited back to your balance

Notes

data_remaining_mb comes from the network, not from subtraction. It is what the provider reports as left on the line, and data_used_mb is derived from it — so the three fields agree by construction. It is null on unlimited packages and before the first usage sync.

expires_at is null before activation. Validity is counted from first use, not from purchase, so an unactivated eSIM has no expiry date yet. Do not render “expires —” as an error state.

Usage here is not real time. This endpoint answers from our records, which are refreshed periodically. For a fresh reading at request time, call Get remaining usage. Either way, subscribe to esim.depleted rather than polling for the moment data runs out.

Errors

Status	Code	Cause
404	`not_found`	No such ICCID, or it belongs to another account
403	`insufficient_scope`	Key lacks `esims:read`