Skip to content
eSIM Go Developer Docs

API Version Migration

The eSIM Go API is versioned. This guide summarises the changes between each version so you can plan an upgrade with confidence. The current version is v2.5.

The base URL for each version follows the pattern https://api.esim-go.com/v2.x/.

v2.4 → v2.5

New endpoints:

  • POST /esims/{iccid}/suspend — suspend or unsuspend an eSIM without revoking it
  • GET /esims/{iccid}/suspend — get current suspension status
  • GET /catalogue/prices — retrieve consumption pricing information

New fields:

  • eSIMs now include a state field: Active, Suspended, or Deactivated
  • Branding profiles support installName and networkName configuration
  • Android Quick Install URL returned alongside the existing Apple URL

Platform changes:

  • IP whitelisting introduced — restrict API access by IP address via portal Settings

No breaking changes from v2.4 to v2.5.

v2.3 → v2.4

New endpoints:

  • GET /esims/{iccid}/compatible/{bundle} — check if a bundle is compatible with a specific eSIM before ordering
  • eSIM Branding support added — customise QR code branding via the portal

Platform changes:

  • API rate limiting introduced: 10 requests per second per IP address
  • New notification channels: commercial and technical email groups
  • Daily spend limit alerts added

No breaking changes from v2.3 to v2.4.

v2.2 → v2.3

Response enhancements:

  • Bundle status endpoint now includes assignmentDateTime, assignmentReference, and bundleStatus fields
  • GET /orders response now includes an iccids array by default
  • eSIM history endpoint now returns an alertType field

No breaking changes from v2.2 to v2.3.

v2.1 → v2.2

New endpoints:

  • GET /esims/assignments — unified endpoint for bulk data download (JSON, CSV, or ZIP of QR codes)

Filtering and sorting:

  • Advanced multi-field filtering added to list endpoints with operators: eq, lt, lte, gt, gte

Async processing:

  • Orders with 5 or more bundles are now processed asynchronously. Poll the order status endpoint to check completion.

Response formatting:

  • Dates and integers are now consistently formatted across all responses

No breaking changes from v2.1 to v2.2.

v2.0 → v2.1

New endpoints:

  • POST /esims/apply — request a new eSIM with a bundle pre-applied in a single call
  • GET /catalogue — list all bundles available to your organisation
  • GET /inventory — list purchased bundles
  • QR code and CSV download endpoints added

⚠️ Breaking change:

  • The eSIM Apply endpoint replaced the previous Applied Bundle endpoint. The ICCID is now passed in the request body rather than the URL path. Update your integration before migrating to v2.1.

Staying on an older version

Older API versions remain available while they are supported. Check the Release Notes for deprecation notices. When a version is deprecated, a removal date will be announced with sufficient notice to migrate.

The current API reference for each version is available in the sidebar under Reference.