eSIMs

An eSIM is one unit of an order. It is identified by its ICCID. The eSIM object holds what your customer needs to install it, and how much data is used and left.

Method	Path	What it does
GET	/v1/esims	List your eSIMs.
GET	/v1/esims/{iccid}	Get one eSIM in full.

Top-ups have their own page.

eSIM status

Status	Meaning
ready	Issued and not used yet. Validity has not started.
active	The eSIM has been used for the first time. The plan is running.
depleted	All the data has been used. Unlimited plans never reach this status. A top-up makes the eSIM active again.
expired	The plan’s validity has ended. An expired eSIM cannot be topped up.
cancelled	The eSIM was cancelled in the Business portal or by eSIMify support. Its install details are no longer returned.

Three changes of status send a webhook: ready to active sends esim.activated, the change to depleted sends esim.usage_100, and the change to expired sends esim.expired. A change to cancelled, and the return to active after a top-up, send none. esim.usage_80 is not a change of status.

In live, status and usage come from the mobile network and reach eSIMify with a delay. See eSIM events in live.

List eSIMs

GET /v1/esims

Returns your eSIMs as summaries, newest first. A summary has every field of the Esim object except activation. Fetch one eSIM to get that. Units of an order that were never issued are not listed.

Parameters

Name	In	Type	Required	Description
status	query	string	No	One eSIM status: ready, active, depleted, expired or cancelled.
customer_ref	query	string	No	eSIMs whose order has exactly this customer_ref.
limit	query	integer	No	1 to 100. Default 25.
cursor	query	string	No	The next_cursor of the previous page.

curl

curl "$ESIMIFY_API_URL/v1/esims?status=active&limit=10" \
  -H "Authorization: Bearer $ESIMIFY_API_KEY"

Node

const res = await fetch(`${process.env.ESIMIFY_API_URL}/v1/esims?status=active&limit=10`, {
  headers: { Authorization: `Bearer ${process.env.ESIMIFY_API_KEY}` },
});
const esims = await res.json();

PHP

<?php
$ch = curl_init(getenv('ESIMIFY_API_URL') . '/v1/esims?status=active&limit=10');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_TIMEOUT => 30,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . getenv('ESIMIFY_API_KEY'),
    ],
]);
$esims = json_decode(curl_exec($ch), true);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);

Python

import os
import requests

res = requests.get(
    os.environ["ESIMIFY_API_URL"] + "/v1/esims",
    headers={"Authorization": "Bearer " + os.environ["ESIMIFY_API_KEY"]},
    params={"status": "active", "limit": "10"},
    timeout=30,
)
esims = res.json()

Response

200 OK with a list of eSIM summaries.

{
  "data": [
    {
      "iccid": "8999999000000012345",
      "status": "active",
      "mode": "test",
      "order_id": "ord_test_3f9a1c2b7d4e",
      "customer_ref": "booking-84512",
      "package": {
        "id": "pkg_10482",
        "name": "Thailand 1 GB 7 days"
      },
      "qr_code_url": "https://api.example.com/partner/api/v1/qr/ODk5OTk5OTAwMDAwMDAxMjM0NQ.3f9a1c2b5e8d7c6b4a39281706f5e4d3c2b1a098.png",
      "install_links": {
        "ios": "https://esimsetup.apple.com/esim_qrcode_provisioning?carddata=LPA%3A1%24sandbox.esimify.in%24TEST-A1B2C3D4E5F6",
        "android": "https://esimsetup.android.com/esim_qrcode_provisioning?carddata=LPA%3A1%24sandbox.esimify.in%24TEST-A1B2C3D4E5F6"
      },
      "data": {
        "unlimited": false,
        "total_mb": 1024,
        "used_mb": 310,
        "remaining_mb": 714
      },
      "validity_days": 7,
      "activated_at": "2026-10-02T11:02:40Z",
      "expires_at": "2026-10-09T11:02:40Z",
      "created": "2026-10-02T09:14:07Z"
    }
  ],
  "has_more": false,
  "next_cursor": null
}

Errors

Status	Code	When
400	invalid_request	A query parameter is not valid, for example an unknown status. param names it.

Any endpoint can also return the common errors.

Get an eSIM

GET /v1/esims/{iccid}

Returns one eSIM in full, with the activation details.

Parameters

Name	In	Type	Required	Description
iccid	path	string	Yes	The ICCID of the eSIM, from the order’s esims list. Digits only.

curl

curl "$ESIMIFY_API_URL/v1/esims/8999999000000012345" \
  -H "Authorization: Bearer $ESIMIFY_API_KEY"

Node

const res = await fetch(`${process.env.ESIMIFY_API_URL}/v1/esims/8999999000000012345`, {
  headers: { Authorization: `Bearer ${process.env.ESIMIFY_API_KEY}` },
});
const esim = await res.json();

PHP

<?php
$ch = curl_init(getenv('ESIMIFY_API_URL') . '/v1/esims/8999999000000012345');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_TIMEOUT => 30,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . getenv('ESIMIFY_API_KEY'),
    ],
]);
$esim = json_decode(curl_exec($ch), true);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);

Python

import os
import requests

res = requests.get(
    os.environ["ESIMIFY_API_URL"] + "/v1/esims/8999999000000012345",
    headers={"Authorization": "Bearer " + os.environ["ESIMIFY_API_KEY"]},
    timeout=30,
)
esim = res.json()

Response

200 OK with an Esim.

{
  "iccid": "8999999000000012345",
  "status": "ready",
  "mode": "test",
  "order_id": "ord_test_3f9a1c2b7d4e",
  "customer_ref": "booking-84512",
  "package": {
    "id": "pkg_10482",
    "name": "Thailand 1 GB 7 days"
  },
  "qr_code_url": "https://api.example.com/partner/api/v1/qr/ODk5OTk5OTAwMDAwMDAxMjM0NQ.3f9a1c2b5e8d7c6b4a39281706f5e4d3c2b1a098.png",
  "activation": {
    "lpa": "LPA:1$sandbox.esimify.in$TEST-A1B2C3D4E5F6",
    "smdp_address": "sandbox.esimify.in",
    "activation_code": "TEST-A1B2C3D4E5F6"
  },
  "install_links": {
    "ios": "https://esimsetup.apple.com/esim_qrcode_provisioning?carddata=LPA%3A1%24sandbox.esimify.in%24TEST-A1B2C3D4E5F6",
    "android": "https://esimsetup.android.com/esim_qrcode_provisioning?carddata=LPA%3A1%24sandbox.esimify.in%24TEST-A1B2C3D4E5F6"
  },
  "data": {
    "unlimited": false,
    "total_mb": 1024,
    "used_mb": 0,
    "remaining_mb": 1024
  },
  "validity_days": 7,
  "activated_at": null,
  "expires_at": null,
  "created": "2026-10-02T09:14:07Z"
}

• qr_code_url is a PNG of the activation.lpa string. See the QR code image.
• install_links open the phone’s own eSIM setup screen. The activation string inside them is percent-encoded. Use each link as returned and do not encode it again. See Delivering eSIMs.
• activated_at and expires_at are null until the eSIM is activated. Validity starts on first use, so expires_at is activated_at plus validity_days.
• For an unlimited plan, data.unlimited is true, and data.total_mb and data.remaining_mb are null. data.used_mb is always a number.
• A completed top-up shows at once: data.total_mb, data.remaining_mb, validity_days and expires_at grow.
• For a live eSIM this call asks the mobile network for fresh usage, at most once a minute for each eSIM. Usage still reaches us with a delay, so do not promise your customer an exact figure.
• For a cancelled eSIM, and in the rare case the install details are not stored yet, qr_code_url, both install_links and the three activation fields are null.

Errors

Status	Code	When
404	esim_not_found	No eSIM has this ICCID for your account in this mode, or the value is not an ICCID. A live key cannot see sandbox eSIMs, and a test key cannot see live ones.

Any endpoint can also return the common errors.

The QR code image

qr_code_url points at GET /v1/qr/{token}.png under your base URL, so it looks like https://<api-host>/partner/api/v1/qr/<token>.png. It is the one address in this API that needs no API key, so you can put it straight into an <img> tag or an email. The token in the address is signed by eSIMify.

• The response is a PNG image, sent with Cache-Control: private, max-age=3600.
• An address with a token that is not valid answers 404.
• The address does not expire and cannot be revoked. It stops working, with 404, only if the eSIM is cancelled.
• Up to 240 requests a minute are allowed from one IP address. Beyond that the answer is 429 with Retry-After. Link to the image from the customer’s device, or keep a copy of it. Do not fetch it in bulk from one server.
• Anyone who has the address can see the QR code and install the eSIM. Share it only with the customer the eSIM is for.
• Always take the address from qr_code_url. Do not build it yourself.