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 x-topics: - title: CDR Data content: > Call Detail Records (CDR) files are made available out-of-band over **SFTP** — there is no HTTP endpoint to retrieve them. **Connection details** * **Host:** `sftp.zimconnections.com` * **Protocol:** SFTP (SSH File Transfer Protocol) * **Username:** the `account_id` attributed to you by your account manager * **Authentication:** public SSH key — share your public key with your account manager so it can be installed on the server. Password authentication is not supported. **Upload cadence** CDR files are automatically uploaded to your SFTP directory **every hour**. 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 delete: summary: Cancel a Subscription description: > Cancels an active Subscription owned by the authenticated User. The Subscription's status is moved to `CANCELLED`. parameters: - schema: type: string in: path name: subscriptionID required: true description: ID of the Subscription to cancel responses: 200: description: Subscription cancelled successfully content: application/json: schema: type: object properties: message: type: string description: Human-readable confirmation message examples: cancelled: summary: Subscription cancelled value: message: 'Plan cancelled successfully' operationId: delete-subscriptions-subscriptionID-cancel '/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 '/plans/{iso3}/local': get: summary: Get local Plans for a Destination description: > Returns the Plans available for a specific Destination, split into `regular` and `unlimited` buckets. * `regular` - Plans capped to a finite amount of data * `unlimited` - Plans with no data cap (`dataValue == -1`) parameters: - schema: type: string in: path name: iso3 required: true description: ISO Alpha-3 code of the Destination - schema: type: string in: query name: discountCode required: false description: Optional discount code applied to the returned Plan prices responses: 200: description: Local Plans fetched successfully content: application/json: schema: type: object properties: regular: type: array items: $ref: '#/components/schemas/Plan' unlimited: type: array items: $ref: '#/components/schemas/Plan' example: regular: - id: plan_guaGulGcrqgTYboPvetgu destination: name: France isoAlpha3: FRA dataUnit: GB dataValue: 10 durationUnit: DAYS durationValue: 14 features: - name: HOTSPOT category: UTILITY - name: 5G category: NETWORK prices: - currencyISO: USD value: 1490 minorExponentUnits: 2 unlimited: - id: plan_uNlimitedABCDEF123456 destination: name: France isoAlpha3: FRA dataUnit: GB dataValue: -1 durationUnit: DAYS durationValue: 7 features: - name: HOTSPOT category: UTILITY - name: 5G category: NETWORK prices: - currencyISO: USD value: 2490 minorExponentUnits: 2 operationId: get-plans-iso3-local '/plans/{iso3}/local/regular': get: summary: Get regular local Plans for a Destination description: > Returns the regular (capped data) local Plans available for a specific Destination. Optionally filtered by `planType`. parameters: - schema: type: string in: path name: iso3 required: true description: ISO Alpha-3 code of the Destination - schema: type: string in: query name: discountCode required: false description: Optional discount code applied to the returned Plan prices - schema: type: string enum: - DATA - VOICE_AND_DATA in: query name: planType required: false description: > Optional filter on the Plan type: * `DATA` - Data-only Plans * `VOICE_AND_DATA` - Plans including voice (and SMS) in addition to data responses: 200: description: Regular local Plans fetched successfully content: application/json: schema: type: array items: $ref: '#/components/schemas/Plan' example: - id: plan_guaGulGcrqgTYboPvetgu destination: name: France isoAlpha3: FRA dataUnit: GB dataValue: 10 durationUnit: DAYS durationValue: 14 features: - name: HOTSPOT category: UTILITY - name: 5G category: NETWORK prices: - currencyISO: USD value: 1490 minorExponentUnits: 2 - id: plan_guaGulGcrqgTYboPveAAB destination: name: France isoAlpha3: FRA dataUnit: GB dataValue: 20 durationUnit: DAYS durationValue: 30 features: - name: HOTSPOT category: UTILITY - name: 5G category: NETWORK prices: - currencyISO: USD value: 2490 minorExponentUnits: 2 operationId: get-plans-iso3-local-regular '/plans/{iso3}/local/unlimited': get: summary: Get unlimited local Plans for a Destination description: > Returns the unlimited (no data cap, `dataValue == -1`) local Plans available for a specific Destination. Optionally filtered by `planType`. parameters: - schema: type: string in: path name: iso3 required: true description: ISO Alpha-3 code of the Destination - schema: type: string in: query name: discountCode required: false description: Optional discount code applied to the returned Plan prices - schema: type: string enum: - DATA - VOICE_AND_DATA in: query name: planType required: false description: > Optional filter on the Plan type: * `DATA` - Data-only Plans * `VOICE_AND_DATA` - Plans including voice (and SMS) in addition to data responses: 200: description: Unlimited local Plans fetched successfully content: application/json: schema: type: array items: $ref: '#/components/schemas/Plan' example: - id: plan_uNlimitedABCDEF123456 destination: name: France isoAlpha3: FRA dataUnit: GB dataValue: -1 durationUnit: DAYS durationValue: 7 features: - name: HOTSPOT category: UTILITY - name: 5G category: NETWORK prices: - currencyISO: USD value: 2490 minorExponentUnits: 2 - id: plan_uNlimitedABCDEF654321 destination: name: France isoAlpha3: FRA dataUnit: GB dataValue: -1 durationUnit: DAYS durationValue: 30 features: - name: HOTSPOT category: UTILITY - name: 5G category: NETWORK prices: - currencyISO: USD value: 4990 minorExponentUnits: 2 operationId: get-plans-iso3-local-unlimited /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: get: summary: Retrieve all Orders description: > Returns a list of all Orders associated with the authenticated User's Account. Reserved to Users with the `Admin`, `Purchaser` or `Owner` role. tags: [] responses: 200: description: Orders fetched successfully content: application/json: schema: type: array items: $ref: '#/components/schemas/Order' example: - id: ordr_GMAVA4ISiqfWSG0ArGOzB status: FULFILLED accountID: acct_ozxEbkTyvLPhhoglcALXE planID: plan_guaGulGcrqgTYboPvetgu userID: user_yf95A86RIkVxau2gzBsjV type: ONE_OFF paymentID: pay_4FzTYboPvetguABCDEFGH paymentReference: pi_3OqAbCxYz12345 notifyRecipient: true createdAt: '2026-05-12T14:39:23.149Z' updatedAt: '2026-05-12T14:41:02.501Z' - id: ordr_QwErTyUiOpAsDfGhJkLZx status: PROCESSING accountID: acct_ozxEbkTyvLPhhoglcALXE planID: plan_guaGulGcrqgTYboPveAAB userID: user_yf95A86RIkVxau2gzBsjV type: TOP_UP notifyRecipient: false createdAt: '2026-05-20T09:12:00.000Z' updatedAt: '2026-05-20T09:12:30.000Z' - id: ordr_FaiL1234567890abcdEFG status: FAILED accountID: acct_ozxEbkTyvLPhhoglcALXE planID: plan_guaGulGcrqgTYboPvetgu userID: user_yf95A86RIkVxau2gzBsjV type: ONE_OFF failureReason: PLAN_NOT_FOUND createdAt: '2026-05-22T11:00:00.000Z' updatedAt: '2026-05-22T11:00:05.000Z' operationId: get-orders '/orders/:orderID': delete: summary: Cancel an Order description: > Cancels an Order owned by the authenticated User. The Order's status is moved to `CANCELLED` and, depending on the original status, the associated payment is refunded or the pending hold released. Orders in the following statuses cannot be cancelled: * `FULFILLED` - the Order has already been delivered * `CANCELLED` - the Order has already been cancelled * `REPLACED` - the Order has been replaced by a newer one parameters: - schema: type: string in: path name: orderID required: true description: ID of the Order to cancel responses: 200: description: Order cancelled successfully content: application/json: schema: type: object description: > Empty object returned on successful cancellation. examples: cancelled: summary: Order cancelled value: {} operationId: delete-orders-orderID-cancel /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 Order: title: Order type: object properties: id: type: string example: 'ordr_GMAVA4ISiqfWSG0ArGOzB' description: The Order's ID status: type: string example: 'FULFILLED' enum: - PENDING_APPROVAL - PENDING_PAYMENT - PROCESSING - FULFILLED - CANCELLED - FAILED - REPLACED - IN_BASKET description: > Statuses: * `PENDING_APPROVAL` - The Order is awaiting approval from an Admin / Purchaser / Owner * `PENDING_PAYMENT` - The Order is awaiting payment from the User * `PROCESSING` - The Order is being processed by the network and should soon be fulfilled * `FULFILLED` - The Order has been fulfilled and the associated Subscription / eSIM is ready * `CANCELLED` - The Order has been cancelled by the User * `FAILED` - The Order has failed — see `failureReason` for details * `REPLACED` - The Order has been superseded by a newer one * `IN_BASKET` - The Order is currently sitting in the User's basket accountID: type: string example: 'acct_ozxEbkTyvLPhhoglcALXE' description: The Account ID linked to the Order planID: type: string example: 'plan_guaGulGcrqgTYboPvetgu' description: The Plan ID linked to the Order userID: type: string example: 'user_yf95A86RIkVxau2gzBsjV' description: The User ID for which the Order was generated type: type: string example: 'ONE_OFF' enum: - ONE_OFF - TOP_UP - RECURRING description: > Types: * `ONE_OFF` - The Order is a one-off purchase * `TOP_UP` - The Order tops up an existing Subscription * `RECURRING` - The Order is part of a recurring Subscription paymentID: type: string example: 'pay_4FzTYboPvetguABCDEFGH' description: The Payment ID linked to the Order, when applicable paymentReference: type: string example: 'pi_3OqAbCxYz12345' description: The external payment reference notifyRecipient: type: boolean example: true description: If `true`, the end User has been (or will be) notified about this Order failureReason: type: string example: 'PLAN_NOT_FOUND' description: Set when `status` is `FAILED` — explains why the Order could not be fulfilled plan: $ref: '#/components/schemas/Plan' subscription: $ref: '#/components/schemas/Subscription' createdAt: type: string format: date-time example: '2026-05-12T14:39:23.149Z' updatedAt: type: string format: date-time example: '2026-05-12T14:41:02.501Z' 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. usersIDs: type: array example: ['user_ozxEbkTyvLPhhoglcALXR'] description: > Optional. A list of User IDs for which the Order is being generated. If omitted, the Order defaults to the User making the request. items: type: string orderType: type: string example: 'ONE_OFF' enum: - ONE_OFF - TOP_UP - RECURRING description: > Optional. Defaults to `ONE_OFF` when omitted. * `ONE_OFF` - The Order is a one-off purchase * `TOP_UP` - The Order tops up an existing Subscription — `subscriptionID` must be provided * `RECURRING` - The Order is part of a recurring Subscription subscriptionID: type: string example: 'sub_yf95A86RIkVxau2gzBsjV' description: > Optional. The ID of the Subscription to top up. Required when `orderType` is `TOP_UP`, ignored otherwise. 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' 'account/': 'This special scope will be communicated by your account manager' appIdentifier: type: apiKey in: header name: X-App-Identifier description: > Identifies the calling application. Must be set to `b2b` unless a specific identifier has been attributed to your Account by your account manager. security: - oauth2: - account/write appIdentifier: []