Retrieve all eSIMs

Add MCP server to your AI tool

Allow AI tools and LLMs to interact with the API documentation portal through MCP.

MCP server URL

https://bump.sh/zim/doc/esim-api/mcp

Standard setup for AI tools providing an mcp.json file

mcp.json
{
  "eSIM API MCP server": {
    "url": "https://bump.sh/zim/doc/esim-api/mcp"
  }
}

Close
GET /esims

Returns the eSIMs of the authenticated User. Users with an account-wide role (Owner, Admin, Purchaser, Analyst) can list the eSIMs of another User of their Account with userNanoID; those are returned without their subscriptions. This endpoint is not paginated.

Query parameters

  • userNanoID string

    Return the eSIMs of this User of your Account instead of your own

  • iccid string

    Exact-match filter on the eSIM ICCID

Responses

  • 200 application/json

    eSIMs fetched successfully

    Hide response attributes Show response attributes object
    • id string

      The eSIM's ID

    • iccid string

      The eSIM's ICCID

    • matchingId string

      The eSIM's matching ID

    • smdpPlus string

      The eSIM's associated SMDP+ server domain

    • msisdn string

      The eSIM's MSISDN

    • status string

      Statuses:

      • PROCESSING - The eSIM is currently being processed by the network and should soon be available
      • RELEASED - The eSIM has been created and ready to be downloaded and installed by the User
      • DOWNLOADED - The eSIM has been downloaded onto the User's device (this should be an ephemeral status on all modern devices as the installation process automatically starts once the download is complete). An eSIM "stuck" in this status could indicate an issue with the installation process.
      • INSTALLED - The eSIM has been installed onto the User's device
      • UNINSTALLED - The User has removed the eSIM from the device
      • EXPIRED - The eSIM has expired and has been released back to the network
      • ENABLED - The eSIM is installed and enabled in the User's device eSIMs
      • DISABLED - The eSIM is installed and disabled in the User's device eSIMS
      • ONLINE - The eSIM is currently active and connected to the network
      • OFFLINE - The eSIM is currently active but is disconnected from the network
      • UNAVAILABLE - We currently cannot provide information about this eSIM, please contact our support

      Values are PROCESSING, RELEASED, DOWNLOADED, INSTALLED, UNINSTALLED, EXPIRED, ENABLED, DISABLED, ONLINE, OFFLINE, or UNAVAILABLE.

    • userID string

      The User owning the eSIM

    • accountID string
    • providerID string

      The network provider's ID

    • subscriptions array[object]

      The eSIM's Subscriptions (not returned when listing another User's eSIMs)

      Hide subscriptions attributes Show subscriptions attributes object
      • id string

        The Subscription's ID

      • status string

        Statuses:

        • PROCESSING - The Subscription is being processed and should be ready soon
        • PENDING - The Subscription is ready and is pending first use by the User
        • ACTIVE - The Subscription is currently active and used by the User
        • EXPIRED - The Subscription has expired and is no longer valid
        • CANCEL_PENDING - A cancellation was requested and is awaiting confirmation from the network
        • CANCELLED - The Subscription has been cancelled
        • DEPLETED - The allocation of the Subscription has been fully consumed by the User

        Values are PROCESSING, PENDING, ACTIVE, EXPIRED, CANCEL_PENDING, CANCELLED, or DEPLETED.

      • esimID string

        The associated eSIM ID

      • planID string
      • orderID string
      • userID string
      • accountID string
      • expirationDate string(date-time) | null
      • createdAt string(date-time)
      • plan object

        The associated Plan object (without prices)

        Hide plan attributes Show plan attributes object
        • id string
        • name string
        • scope string
          • LOCAL - single Destination * REGIONAL - a Region (several Destinations) * GLOBAL - worldwide coverage

          Values are LOCAL, REGIONAL, or GLOBAL.

        • category string

          Values are REGULAR, UNLIMITED, or MIXED.

        • type string
          • DATA - Data-only Plans * VOICE_AND_DATA - Plans including voice (and SMS) in addition to data

          Values are DATA or VOICE_AND_DATA.

        • isRecurring boolean

          true for recurring plans such as UK domestic plans

        • recurringInterval string | null

          Billing interval of recurring plans (MONTHLY for UK domestic plans), null for one-off plans

          Values are DAILY, WEEKLY, MONTHLY, YEARLY, or null.

        • destination object
          Hide destination attributes Show destination attributes object
          • name string
          • isoAlpha3 string
          • regions array[object]
            Hide regions attributes Show regions attributes object
            • name string
            • abbreviation string
          • scopes object

            Returned by GET /destinations/{iso3} only

            Hide scopes attributes Show scopes attributes object
            • local boolean
            • regional boolean
            • global boolean
        • region object
          Hide region attributes Show region attributes object
          • name string
          • abbreviation string
        • dataUnit string

          Possible values:

          • MB - MegaByte representation
          • GB - GigaByte representation

          Values are MB or GB.

        • dataValue number

          Details:

          • If dataValue >= 0 then the plan is capped to that amount of consumable data
          • If dataValue == -1 then the plan is unlimited and does not have a cap on consumable data
        • callUnit string

          Details:

          • MINUTES - Minutes representation
          • HOURS - Hours representation

          Values are MINUTES or HOURS.

        • callValue number

          Details:

          • If callValue >= 0 then the plan is capped to that amount of consumable call time
          • If callValue == -1 then the plan is unlimited and does not have a cap on call time
        • smsUnit string
        • smsValue number

          Details:

          • If smsValue >= 0 then the plan is capped to that amount of consumable SMS sent
          • If smsValue == -1 then the plan is unlimited and does not have a cap on SMS sent
        • durationUnit string
        • durationValue number
        • features array[object]
          Hide features attributes Show features attributes object
          • name string

            Possible values:

            • HOTSPOT - The plan does support the hotspot function
            • TOP_UP - The plan does support top up operations
            • 3G - The plan and its associated network supports speeds up to 3G
            • 4G - The plan and its associated network supports speeds up to 4G
            • 5G - The plan and its associated network supports speeds up to 5G

            Values are HOTSPOT, TOP_UP, 3G, 4G, or 5G.

          • category string

            Values are UTILITY, BILLING, or NETWORK.

        • prices array[object]
          Hide prices attributes Show prices attributes object
          • currencyISO string
          • value number

            The unit amount in minor units (e.g. cents, if supported), represented as a signed integer

          • minorUnitsExponent number

            Indicates the number of decimals in the price for currencies supporting this format or 0 for zero-decimal currencies such as JPY. Examples:

            • A USD price value of 490 with a minorUnitsExponent of 2 would be $4.90
            • A JPY price value of 775 with a minorUnitsExponent of 0 would be ¥775
          • discountedFrom number

            Present when a valid discountCode was applied — the price before discount, in minor units

        • createdAt string(date-time)
      • activity object | null
        Hide activity attributes Show activity attributes object | null
        • currentBalanceBytes number

          The current balance in bytes for the Subscription

        • spentBalanceBytes number

          The spent balance in bytes for the Subscription

        • initialBalanceBytes number

          The initial balance in bytes for the Subscription

        • lastUpdatedAt string(date-time)

          The report's last update

      • cancelAtPeriodEnd boolean

        true when the Subscription is scheduled to be cancelled at cancelEffectiveDate

      • cancelEffectiveDate string(date-time)

        Date a scheduled cancellation takes effect

  • 401 application/json

    Missing or invalid access token or X-App-Identifier

    Hide response attributes Show response attributes object
  • 403 application/json

    Your role is not allowed to perform this operation

    Hide response attributes Show response attributes object
GET /esims
curl \
 --request GET 'https://zim.api.dev.zimconnections.com/esims' \
 --header "Authorization: Bearer $ACCESS_TOKEN" \
 --header "X-App-Identifier: $API_KEY"
Response examples (200)
[
  {
    "id": "esim_igFqGZhkRTHb0UNiRuAAA",
    "iccid": "8948010000000012345",
    "matchingId": "64DF7EFC13EBEB1AA90F126A509BBDBD",
    "smdpPlus": "smdpp.zimconnections.com",
    "msisdn": "447482482482",
    "status": "ONLINE",
    "qrCodeLink": "https://images.zimconnections.com/...",
    "userID": "user_yf95A86RIkVxau2gzBsjV",
    "accountID": "acct_ozxEbkTyvLPhhoglcALXE",
    "providerID": "prov_W0aBcDeFgHiJkLmNoPqRs"
  }
]
Response examples (401)
{
  "statusCode": 401,
  "message": "Unauthorized"
}
Response examples (403)
{
  "statusCode": 403,
  "message": "Forbidden resource",
  "error": "Forbidden"
}