{"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\n  * Note: Consumption reports are updated automatically every hour.\n","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: \n  * `MB` - MegaByte representation\n  * `GB` - GigaByte representation\n","example":"GB"},"dataValue":{"type":"number","example":10,"description":"Details: \n  * If `dataValue` \u003e= 0 then the plan is capped to that amount of consumable data  \n  * If `dataValue` == -1 then the plan is unlimited and does not have a cap on consumable data\n"},"callUnit":{"type":"string","example":"MINUTES","enum":["MINUTES","HOURS"],"description":"Details: \n  * `MINUTES` - Minutes representation  \n  * `HOURS` - Hours representation\n"},"callValue":{"type":"number","example":100,"description":"Details: \n  * If `callValue` \u003e= 0 then the plan is capped to that amount of consumable call time  \n  * If `callValue` == -1 then the plan is unlimited and does not have a cap on call time\n"},"smsUnit":{"type":"string","example":"SMS"},"smsValue":{"type":"number","example":100,"description":"Details: \n  * If `smsValue` \u003e= 0 then the plan is capped to that amount of consumable SMS sent  \n  * If `smsValue` == -1 then the plan is unlimited and does not have a cap on SMS sent\n"},"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\n"},"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:\n  * A `USD` price `value` of 490 with a `minorExponentUnits` of 2 would be $4.90\n  * A `JPY` price `value` of 775 with a `minorExponentUnits` of 0 would be ¥775\n"}}},"Feature":{"title":"Feature","type":"object","properties":{"name":{"type":"string","enum":["HOTSPOT","TOP_UP","3G","4G","5G"],"description":"Possible values: \n  * `HOTSPOT` - The plan does support the hotspot function\n  * `TOP_UP` - The plan does support top up operations\n  * `3G` - The plan and its associated network supports speeds up to 3G\n  * `4G` - The plan and its associated network supports speeds up to 4G\n  * `5G` - The plan and its associated network supports speeds up to 5G\n","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:\n  * `PROCESSING` - The eSIM is currently being processed by the network and should soon be available \n  * `RELEASED` - The eSIM has been created and ready to be downloaded and installed by the User \n  * `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.  \n  * `INSTALLED` - The eSIM has been installed onto the User's device \n  * `UNINSTALLED` - The User has removed the eSIM from the device \n  * `EXPIRED` - The eSIM has expired and has been released back to the network \n  * `ENABLED` - The eSIM is installed and enabled in the User's device eSIMs \n  * `DISABLED` - The eSIM is installed and disabled in the User's device eSIMS \n  * `ONLINE` - The eSIM is currently active and connected to the network \n  * `OFFLINE` - The eSIM is currently active but is disconnected from the network \n  * `UNAVAILABLE` - We currently cannot provide information about this eSIM, please contact our support\n"},"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:\n  * `PROCESSING` - The Subscription is being processed and should be ready soon\n  * `PENDING` - The Subscription is ready and is pending first use by the User\n  * `ACTIVE` - The Subscription is currently active and used by the User\n  * `EXPIRED` - The Subscription has expired and is no longer valid\n  * `CANCELLED` - The Subscription has been cancelled by the User\n  * `DEPLETED` - The allocation of the Subscription has been fully consumed by the User\n"}}},"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"]}]}