Sign inGet Started
Aan de slag
Gidsen
API Reference
SDK's
CLI
Kennisbank
Changelog

List eSIMs

GET
/v1/esim/sims
bird esim list
Reactie200
{
  "data": [
    {
      "subscriber_id": "esub_01krdgeqcxet5s7t44vh8rt9mg",
      "id": "esm_01krdgeqcxet5s7t44vh8rt9mg",
      "status": "provisioning",
      "mode": "live",
      "iccid": "8944500212345678912",
      "phone_number": "+31612345678"
    }
  ],
  "next_cursor": "eyJ2IjoxLCJzIjoiXCIyMDI2LTA1LTI1VDE0OjAzOjEwWlwiIiwiaSI6IjAxOTJmM2IxLTRjN2UtN2EyYi05ZDYxLThmM2E1YzJlN2I0MCJ9",
  "prev_cursor": null,
  "refresh_cursor": "eyJ2IjoxLCJzIjoiXCIyMDI2LTA1LTI1VDE2OjQyOjAxWlwiIiwiaSI6IjAxOTJmM2IxLTllMDQtN2NkMy1iODE3LTJhNmY0ZDFjOGUwOSJ9"
}

Returns your workspace's eSIMs as a cursor-paginated list, newest first. Filter by lifecycle status, exact iccid, tag, or creation time; pass the response's next_cursor back as starting_after to fetch the next page.

To find an eSIM you cannot name by its full ICCID, search on iccid_prefix, display_name, or phone_number. Each searches a different identifier and each combines with the filters above, narrowing the list rather than widening it. Searching never reaches outside the workspace the request is scoped to, so an eSIM belonging to another workspace is absent from the results rather than reported as forbidden.

Queryparameters

limitinteger

Maximum number of items to return per page.

starting_afterstring

Cursor from the next_cursor field of a previous list response. Returns items immediately after the cursor position in the current sort order.

ending_beforestring

Cursor from the prev_cursor or refresh_cursor field of a previous list response. Returns items immediately before the cursor position in the current sort order. prev_cursor returns the preceding page. refresh_cursor anchors at the first row of that response, which on a newest-first sort is how to fetch the items that have appeared since.

subscriber_idstring

Return eSIMs assigned to this subscriber.

created_afterstring

Limits the response to resources created at or after this timestamp. Combine it with created_before to select a time window. Use an RFC 3339 timestamp with a timezone offset.

created_beforestring

Limits the response to resources created before this timestamp. Combine it with created_after to select a time window. Use an RFC 3339 timestamp with a timezone offset.

statusarray

Keep only eSIMs whose current status matches; repeat the parameter to match any of several.

iccidstring

Filter by ICCID (exact match).

modestring

Keep only eSIMs created in this mode. Without it, both live and test eSIMs are returned.

Possible values: live, test

tagarray

Filter by tag. Accepts name to match any eSIM carrying that tag name, or name:value to match a specific tag pair (e.g. trip:summer). A trailing colon (name:) matches the name alone, the same as name. A term with an empty name is rejected. Repeat the parameter to AND-combine several tag filters.

iccid_prefixstring

Keep only eSIMs whose ICCID starts with these digits. Use it when you hold only the first part of an ICCID. Pass iccid instead when you hold the whole number.

display_namestring

Keep only eSIMs whose display_name contains this text, ignoring case. An eSIM you have not named has no display_name, so it never matches.

phone_numberstring

Keep only eSIMs whose mobile network has reported this phone number, matched as a whole number rather than as a fragment. Give it in international form, with or without the leading +: +31612345678 and 31612345678 select the same eSIMs. An eSIM matches on any number its mobile network has ever reported for the profile, so a number that has since moved on still finds the eSIM that held it. An eSIM whose number no network has reported yet never matches.

Response Payload

data
array of object
verplicht

eSIMs, newest first, in compact form; fetch one by id for the full aggregate.

Onderliggende attributen tonen
data.subscriber_id
nullable string
verplicht

The assigned service user, or null when the eSIM has no person assignment.

data.id
string
verplicht
data.status
string
verplicht
data.mode
string
verplicht
data.iccid
nullable string
verplicht

ICCID of the eSIM profile, or null while none is allocated.

data.phone_number
nullable string
verplicht

Phone number attached to this eSIM, in E.164 format, as the supplier reports it. Null while none is on record.

data.display_name
nullable string
verplicht

Free-text label for your own reference.

data.created_at
string
verplicht
next_cursor
nullable string
verplicht

Cursor for the next page. Pass back as starting_after to advance forward. null when no next page exists.

prev_cursor
nullable string
verplicht

Cursor for the previous page. Pass back as ending_before to step backward. null when no previous page exists.

refresh_cursor
nullable string
verplicht

Refresh anchor, the first row of this response. Pass back as ending_before to fetch what precedes it in the current sort order. On a newest-first sort those are the items that have appeared since; on any other sort they are the items that sort earlier, so refreshing such a list means re-fetching it instead. Non-null whenever data is non-empty; null only on an empty page. Distinct from prev_cursor.

Gerelateerde bronnen

Ga verder met de documentatie, handleidingen en voorbeelden voor dit onderwerp.

Ontvang een implementatieoverzicht