esims

List eSIMs

Returns your workspace's eSIMs as a cursor-paginated list, newest first. Filter by lifecycle status, recurring subscription (renewal), 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.

get/v1/esim/sims

Request

  • Base URL: https://us1.platform.bird.com
  • URL: https://us1.platform.bird.com/v1/esim/sims
  • Auth: one of:
    • HTTP bearer
    • API key in cookie bird_session

Query parameters

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
Example:esub_01krdgeqcxet5s7t44vh8rt9mg

Return eSIMs assigned to this subscriber.

created_afterstring date-time
Example:2026-05-01T00:00:00Z

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 date-time
Example:2026-06-01T00:00:00Z

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.

statusEsimStatus[]

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

iccidstring

Filter by ICCID (exact match).

mode'live' | 'test'

Whether a purchase or eSIM is live or simulated. The mode is fixed when the order is created; the resulting eSIM retains it.

  • live: purchases service for use on a device and charges the wallet.
  • test: simulates a purchase without a charge or usable mobile service.

List responses can include both modes. Filter by mode when separating test activity from live purchases.

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

renewalEsimRenewalState[]

Keep only eSIMs whose recurring subscription that has not ended is in this status, or that have none (none); repeat the parameter to match any of several.

tagstring[]

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
Example:89445002

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
Example:field team

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
Example:+31612345678

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.

Headers

X-Workspace-Idstring

Workspace context for the request. Required for dashboard authentication and master keys. Workspace keys and access tokens already identify their workspace; send that workspace or omit the header. A different one is rejected.

X-Organization-Idstring

Organization context for the request. Required for dashboard authentication. An API key or access token carries its own organization, so send either that organization or no header at all; a different one is rejected.

Response

Paginated list of eSIMs.

next_cursorstring nullable required

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

prev_cursorstring nullable required

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

refresh_cursorstring nullable required

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.

Example response

{
  "data": [
    {
      "subscriber_id": "esub_01krdgeqcxet5s7t44vh8rt9mg",
      "id": "esm_01krdgeqcxet5s7t44vh8rt9mg",
      "iccid": "8944500212345678912",
      "phone_number": "+31612345678",
      "renewal": {
        "subscription_id": "ers_01krdgeqcxet5s7t44vh8rt9mg"
      }
    }
  ],
  "next_cursor": "eyJ2IjoxLCJzIjoiXCIyMDI2LTA1LTI1VDE0OjAzOjEwWlwiIiwiaSI6IjAxOTJmM2IxLTRjN2UtN2EyYi05ZDYxLThmM2E1YzJlN2I0MCJ9",
  "refresh_cursor": "eyJ2IjoxLCJzIjoiXCIyMDI2LTA1LTI1VDE2OjQyOjAxWlwiIiwiaSI6IjAxOTJmM2IxLTllMDQtN2NkMy1iODE3LTJhNmY0ZDFjOGUwOSJ9"
}

Changes

No recorded changes to this operation across all 2 revisions of this API.