SIM card inventory — list and view SIMs, bulk-provision links, retrieve eSIM installation details, and refresh SIM data from upstream systems.
List SIMs
Paginated list of SIMs in your organisation.
Filters combine with AND semantics. compatibility_zones is
repeatable (OR within the filter). search does a case-insensitive
substring match across identifier fields. for_plan_id is a
convenience filter — resolves the plan's compatibility zones and
AND's them with whatever else is set; if compatibility_zones is
also provided, the plan-derived set takes precedence (the service
overwrites the kwarg).
query Parameters
pagePage number (1-based).
Page number (1-based).
page_sizeItems per page.
Items per page.
sort_byField to sort by. Omit for default ordering (most recently updated first).
Field to sort by. Omit for default ordering (most recently updated first).
sort_orderSort direction.
Sort direction.
statusFilter by SIM lifecycle status.
Filter by SIM lifecycle status.
sim_typeFilter by SIM form factor (physical or eSIM).
Filter by SIM form factor (physical or eSIM).
compatibility_zonesFilter by compatibility zone. Repeatable.
Filter by compatibility zone. Repeatable.
searchFree-text match against id, ICCID, MSISDN, IMSI, IMEI, or EID.
Free-text match against id, ICCID, MSISDN, IMSI, IMEI, or EID.
for_plan_idReturn only SIMs compatible with the given plan. Resolves the plan's compatibility zones and applies them as a filter.
Return only SIMs compatible with the given plan. Resolves the plan's compatibility zones and applies them as a filter.
List SIMs › Responses
Successful Response
Items on the current page.
totalTotal number of items across all pages.
pageCurrent page number (1-based).
page_sizeItems per page used to compute this response.
pagesTotal number of pages at the current page_size.
Provision links for multiple SIMs in bulk
Provision a link for each SIM in the request, asynchronously.
Each item generates a Link named {name_prefix}_{counter}, optionally
activating the same plan_ids on it. The work runs in the background:
this endpoint returns 202 with a BulkTaskResponse immediately;
customers poll GET /tasks/{task_id} to track per-item progress and
GET /tasks/{task_id}/items for per-SIM outcomes (success / failure
reason).
Per-item failures (e.g. a SIM already linked) don't fail the whole task — they're recorded against the offending item only and the task keeps processing the rest.
Provision links for multiple SIMs in bulk › Request Body
name_prefixPrefix for each provisioned link's name; the per-item suffix is _{counter}.
sim_idsSIMs to provision. Must be non-empty; duplicates are rejected.
Plans to activate on every new link. Omit to leave each link pre-active.
counter_startFirst value used for the _{counter} suffix; subsequent items get +1 each.
Provision links for multiple SIMs in bulk › Responses
Bulk task queued. Poll GET /tasks/{task_id} for progress.
idInternal bulk-task identifier.
typeType of bulk operation.
statusStatus of a bulk task.
total_itemsTotal number of items the task was created with.
completed_itemsItems processed successfully.
failed_itemsItems that the worker could not process.
pending_itemsItems still waiting to be processed (total - completed - failed).
created_atUTC timestamp when the task was created.
updated_atUTC timestamp of the last update.
Get a SIM
Fetch a single SIM by id within the caller's organisation.
path Parameters
sim_idGet a SIM › Responses
Successful Response
idInternal SIM identifier.
iccidICCID — the SIM's printed serial number.
statusDomain-level SIM status.
sim_typeSIM form factor type.
is_attachedWhether the upstream system reports the SIM as currently attached. Distinct from link: this reflects upstream-reported attach state, while link reflects our local binding.
created_atUTC timestamp when the SIM was first synced into our system.
updated_atUTC timestamp of the last update from sync.
MSISDN (phone number) assigned to the SIM, if any.
IMSI on the SIM profile.
IMEI of the device the SIM was last seen in, if known.
eUICC identifier — only present for eSIMs.
compatibility_zonesCompatibility zones this SIM can operate in.
eSIM profile state. Null for physical SIMs.
The Link this SIM is bound to in our system. Null if not bound.
Get the eSIM installation view for a SIM
Build the eSIM installation view for a SIM.
Returns the raw LPA activation_code, an inline QR SVG, and
Android / iOS deeplinks that prefill the system eSIM installer.
Physical SIMs (no activation code) return all-null — not an error,
just nothing to install.
path Parameters
sim_idGet the eSIM installation view for a SIM › Responses
Successful Response
Raw LPA activation string for the eSIM. Null for physical SIMs.
Android deeplink that opens the system eSIM installer prefilled with this code.
iOS deeplink that opens the system eSIM installer prefilled with this code.
Inline SVG markup of the LPA QR code, ready to embed in HTML.
Refresh a SIM from its upstream system
Pull fresh state for a single SIM from upstream and return it.
Background workers periodically sync all SIMs; this endpoint lets customers force-refresh one on demand. If upstream returns no data, the existing locally-stored SIM is returned unchanged — same semantics as the worker path.
path Parameters
sim_idRefresh a SIM from its upstream system › Responses
Successful Response
idInternal SIM identifier.
iccidICCID — the SIM's printed serial number.
statusDomain-level SIM status.
sim_typeSIM form factor type.
is_attachedWhether the upstream system reports the SIM as currently attached. Distinct from link: this reflects upstream-reported attach state, while link reflects our local binding.
created_atUTC timestamp when the SIM was first synced into our system.
updated_atUTC timestamp of the last update from sync.
MSISDN (phone number) assigned to the SIM, if any.
IMSI on the SIM profile.
IMEI of the device the SIM was last seen in, if known.
eUICC identifier — only present for eSIMs.
compatibility_zonesCompatibility zones this SIM can operate in.
eSIM profile state. Null for physical SIMs.
The Link this SIM is bound to in our system. Null if not bound.