openapi: 3.1.0 info: title: ZIM API version: '3.0' summary: ZIM eSIM API - Documentation servers: - url: 'https://zim.api.zimconnections.com' description: Production - url: 'https://zim.api.dev.zimconnections.com' description: Sandbox paths: '/esims': get: summary: Retrieve all eSIMs description: Returns a list of all eSIMs associated with the account tags: [] responses: 200: description: eSIMs fetched successfully content: application/json: schema: type: array items: $ref: '#/components/schemas/Esim' example: - id: esim_igFqGZhkRTHb0UNiRuAAA iccid: 8948010000000012345 matchingID: 64DF7EFC13EBEB1AA90F126A509BBDBD smdpPlus: smdpp.zimconnections.com msisdn: 447482482482 status: ONLINE qrCodeLink: 'images.zimconnections.com/...' - id: esim_igFqGZhkRTHb0UNiRuBBB iccid: 8948010000000012346 matchingID: 64DF7EFC13EBEB1AA90F126A509BBDBE smdpPlus: smdpp.zimconnections.com msisdn: 447482482483 status: OFFLINE qrCodeLink: 'images.zimconnections.com/...' '/esims/:esimID': get: summary: Retrieve an eSIM description: Returns an eSIM object from its ID parameters: - schema: type: string in: query name: esimID description: ID of the eSIM responses: 200: description: eSIM fetched successfully content: application/json: schema: $ref: '#/components/schemas/Esim' examples: - id: esim_igFqGZhkRTHb0UNiRuAAA iccid: 8948010000000012345 matchingID: 64DF7EFC13EBEB1AA90F126A509BBDBD smdpPlus: smdpp.zimconnections.com msisdn: 447482482482 status: ONLINE qrCodeLink: 'images.zimconnections.com/...' '/subscriptions/': get: summary: Retrieve all Subscriptions description: Returns a list of all Subscriptions associated with the account tags: [] responses: 200: description: Subscriptions fetched successfully content: application/json: schema: type: array items: $ref: '#/components/schemas/Subscription' example: - id: sub_igFqGZhkRTHb0UNiRuAAA esimID: esim_igFqGZhkRTHb0UNiRuAAA status: ACTIVE plan: id: plan_igFqGZhkRTHb0UNiRuAAA dataValue: 10 dataUnit: GB - id: sub_igFqGZhkRTHb0UNiRuBBB esimID: esim_igFqGZhkRTHb0UNiRuBBB status: DEPLETED plan: id: plan_igFqGZhkRTHb0UNiRuBBB dataValue: 5 dataUnit: GB '/subscriptions/:subscriptionID': get: summary: Retrieve a Subscription description: Returns an Subscription object from its ID parameters: - schema: type: string in: query name: subscriptionID description: ID of the Subscription responses: 200: description: eSIM fetched successfully content: application/json: schema: $ref: '#/components/schemas/Esim' examples: - id: sub_igFqGZhkRTHb0UNiRuAAA esimID: esim_igFqGZhkRTHb0UNiRuAAA status: ACTIVE plan: id: plan_igFqGZhkRTHb0UNiRuAAA dataValue: 10 dataUnit: GB '/subscriptions/:subscriptionID/activity/latest': get: summary: Latest Subscription's consumption report description: > Retrieve the latest consumption report for a Subscription * Note: Consumption reports are updated automatically every hour. parameters: - schema: type: string in: query name: subscriptionID description: ID of the Subscription responses: 200: description: Consumption report fetched successfully content: application/json: schema: type: object properties: currentBalanceBytes: type: number description: The current balance in bytes for the Subscription spentBalanceBytes: type: number description: The spent balance in bytes for the Subscription initialBalanceBytes: type: number description: The initial balance in bytes for the Subscription lastUpdatedAt: type: number description: The report's last update Unix epoch timestamp example: - currentBalanceBytes: 94371840 initialBalanceBytes: 104857600 spentBalanceBytes: 10485760 lastUpdatedAt: 1757510292 '/destinations/:iso3': get: summary: Get Destination coverage description: Returns information regarding the coverage offered for a specific Destination tags: [] responses: 200: description: Destination coverage fetched successfully content: application/json: schema: type: object properties: name: type: string isoAlpha3: type: string scopes: type: object properties: local: type: boolean regional: type: boolean global: type: boolean examples: - name: France isoAlpha3: FRA scopes: local: true regional: true global: true operationId: 'get-destinations-:iso3' parameters: - schema: type: string in: query name: iso3 description: iso3 for Destination /plans/search: post: summary: Search for Plans tags: [] responses: 200: description: Success content: application/json: schema: type: array items: $ref: '#/components/schemas/Plan' operationId: post-plans-search /destinations/supported_destinations: get: summary: Get supported Destinations tags: [] responses: 200: description: Success content: application/json: schema: type: array items: $ref: '#/components/schemas/Destination' operationId: get-destinations-supported_destinations /orders/with-wallet: post: summary: Create Order with wallet tags: [] responses: 200: description: Order creation succeeded content: application/json: schema: type: object properties: id: type: string accountID: type: string planID: type: string userID: type: string createdAt: type: date status: type: string 'type': type: string examples: - id: "ordr_GMAVA4ISiqfWSG0ArGOzB" accountID: "acct_ozxEbkTyvLPhhoglcALXE" userID: "user_yf95A86RIkVxau2gzBsjV" createdAt: "2026-03-12T14:39:23.149Z" status: "PROCESSING" type: "ONE_OFF" operationId: post-orders-with-wallet requestBody: content: application/json: schema: $ref: '#/components/schemas/OrderWithWalletRequest' components: schemas: Destination: title: Destination type: object properties: name: type: string example: 'United Kingdom' isoAlpha3: type: string example: 'GBR' Region: title: Region type: object properties: name: type: string abbreviation: type: string Plan: title: Plan type: object properties: id: type: string example: 'plan_guaGulGcrqgTYboPvetgu' destination: $ref: '#/components/schemas/Destination' region: $ref: '#/components/schemas/Region' dataUnit: type: string enum: - MB - GB description: > Possible values: * `MB` - MegaByte representation * `GB` - GigaByte representation example: 'GB' dataValue: type: number example: 10 description: > 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: type: string example: 'MINUTES' enum: - MINUTES - HOURS description: > Details: * `MINUTES` - Minutes representation * `HOURS` - Hours representation callValue: type: number example: 100 description: > 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: type: string example: 'SMS' smsValue: type: number example: 100 description: > 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: type: string example: 'DAYS' durationValue: type: number example: 14 features: type: array items: $ref: '#/components/schemas/Feature' prices: type: array items: $ref: '#/components/schemas/Price' Price: title: Price type: object properties: currencyISO: type: string example: 'USD' value: type: number example: 490 description: > The unit amount in cents (if supported), represented as a signed integer minorExponentUnits: type: number example: 2 description: > 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 `minorExponentUnits` of 2 would be $4.90 * A `JPY` price `value` of 775 with a `minorExponentUnits` of 0 would be ¥775 Feature: title: Feature type: object properties: name: type: string enum: - HOTSPOT - TOP_UP - 3G - 4G - 5G description: > 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 example: 'HOTSPOT' category: type: string enum: - UTILITY - BILLING - NETWORK example: 'UTILITY' Esim: title: Esim type: object properties: id: type: string description: The eSIM's ID example: 'esim_kNsYsgLWJCesLTLsjoRGp' iccid: type: string description: The eSIM's ICCID example: '8937103488884969991' matchingID: type: string description: The eSIM's matching ID example: '2DAC33FBEB7D5A0C2F34659AF7A7842F5' smdpPlus: type: string description: The eSIM's associated SMDP+ server domain example: 'smdpp.zimconnections.com' msisdn: type: string description: The eSIM's MSISDN example: '4474824824444' status: type: string example: 'INSTALLED' enum: - PROCESSING - RELEASED - DOWNLOADED - INSTALLED - UNINSTALLED - EXPIRED - ENABLED - DISABLED - ONLINE - OFFLINE - UNAVAILABLE description: > 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 qrCodeLink: type: string example: 'https://[...]/[...].png' description: QR code image URL for quick eSIM install Subscription: title: Subscription type: object properties: id: type: string example: 'subs_BiPtvfzYKwcyNMNvTGmLO' description: The Subscription's ID esimID: type: string example: 'esim_kNsYsgLWJCesLTLsjoRGp' description: The associated eSIM ID plan: $ref: '#/components/schemas/Plan' description: The associated Plan object status: type: string example: 'ACTIVE' enum: - PROCESSING - PENDING - ACTIVE - EXPIRED - CANCELLED - DEPLETED description: > 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 * `CANCELLED` - The Subscription has been cancelled by the User * `DEPLETED` - The allocation of the Subscription has been fully consumed by the User OrderWithWalletRequest: title: OrderWithWalletRequest type: object properties: planID: type: string example: 'plan_guaGulGcrqgTYboPvetgE' description: The Plan ID which is linked to the Order accountID: type: string example: 'acct_ozxEbkTyvLPhhoglcALXE' description: The Account ID linked to this Order. Allows to generate orders `OnBehalf` of another Account. If omitted this will default to the Account associated with the User making the query. currencyISO: type: string example: 'USD' description: The currency ISO for the Order. If omitted, this will default to the preferred currency for the Account. notifyRecipient: type: boolean example: true description: If `true`, a notification, push / sms or email will be sent to the end User based on the Account preferences. quantity: type: number example: 1 description: The quantity of Plans to purchase for this Order. userNanoIDs: type: array example: ['user_ozxEbkTyvLPhhoglcALXR'] description: A list of Users ID for which the Order is being generated. items: type: string securitySchemes: oauth2: type: oauth2 flows: clientCredentials: tokenUrl: 'https://auth.zimconnections.com/oauth2/token' refreshUrl: '' scopes: account/write: 'A grant read write to all your data' security: - oauth2: - account/write