Skip to content
Partners API
Preview. The Partners API is not live yet, so details on this page can change before launch.

Changelog

Every change to the API is listed here, newest first. While the API is in preview, paths and fields can still change.

2 October 2026: v1 preview, update 1

Section titled “2 October 2026: v1 preview, update 1”

Changes made after the first round of testing. If you started building against the first preview, read this list.

New

  • GET /v1/esims/{iccid}/topups lists the top-ups of an eSIM, and GET /v1/topups/{id} fetches one. Sandbox top-ups are stored too.
  • Every Event has a sequence number. Order events by it.
  • Every Order has items, a list of { package_id, quantity }.
  • New error codes: 404 topup_not_found and, in the sandbox, 409 invalid_state.
  • The sandbox customer_ref triggers now work on top-ups as well.
  • balance.low is now sent in the sandbox too, against the virtual balance and the threshold from Settings.
  • Requests refused with 401 because the key was revoked or has expired now appear in your request log.

Changed

  • Region codes from GET /v1/countries are now region- and a number. The old codes are still accepted by GET /v1/packages?region=.
  • On an order that holds several packages, the top-level package_id and quantity are null. This can only happen to orders placed in the Business portal.
  • The first delivery attempt of a webhook is made at once, and an endpoint gets one request at a time, in sequence order.
  • A top-up with a package that is not one of the eSIM’s top-up packages now answers 404 package_not_found in both modes. Listing top-up packages for an expired or cancelled eSIM answers 409 esim_not_topupable in both modes.
  • The sandbox balance starts at 1000000.00 INR and refills below 10000.00 INR.
  • The sandbox simulate endpoint follows the life of a real eSIM: activated first, then usage, then expired. A repeated event changes nothing and sends no webhook.
  • low_balance_threshold is null until you set a threshold. There is no built-in default.
  • After a completed top-up, esim.usage_80 and esim.usage_100 can be sent again.
  • created_after now includes its own instant. created_before still does not.
  • Cursors only work on the list and the kind of key they came from.
  • Text with control characters is refused with 400. Lengths are counted in characters.
  • A body that is not valid JSON, or is larger than 64 KB, is answered with the normal error body.
  • Only accepted requests are remembered for an Idempotency-Key. After an error the same key runs the request again.

Documentation

  • The Topup object lists customer_ref, balance_after and all three statuses.
  • order.completed is documented as covering partially completed orders.
  • 503 supplier_unavailable is documented as a sandbox response.
  • The webhook verification samples are stricter: they reject a header that is not exactly in the documented form, and an empty secret.
  • The Postman collection has its environment file linked, and the walkthrough runs from start to finish.

2 October 2026: v1 preview

Section titled “2 October 2026: v1 preview”

The first preview of version 1.

Endpoints

  • Catalogue: GET /v1/countries, GET /v1/packages, GET /v1/packages/{id}.
  • Balance: GET /v1/balance.
  • Orders: POST /v1/orders, GET /v1/orders/{id}, GET /v1/orders.
  • eSIMs: GET /v1/esims, GET /v1/esims/{iccid}.
  • Top-ups: GET /v1/esims/{iccid}/topup-packages, POST /v1/esims/{iccid}/topups.
  • Events: GET /v1/events, GET /v1/events/{id}.
  • Sandbox: POST /v1/sandbox/esims/{iccid}/simulate.

Platform

  • Test and live API keys, created in the Business portal under Developers. Keys can be rolled with a 24-hour overlap and limited to an IP allowlist.
  • A sandbox with a virtual balance, customer_ref triggers for failures, and simulated eSIM events.
  • Required Idempotency-Key on every POST, with the Idempotent-Replayed response header.
  • Rate limits of 120 requests a minute and 30 POST requests a minute for each key, with X-RateLimit-* headers.
  • Webhooks for order.completed, order.failed, esim.activated, esim.usage_80, esim.usage_100, esim.expired, topup.completed and balance.low, signed with HMAC-SHA256 in the X-Esimify-Signature header.
  • A delivery log, manual retry and a test ping event in the portal.

Changes from the earlier preview docs

  • Package ids are now pkg_ and a number, such as pkg_10482.
  • The webhook signature is now t=<timestamp>,v1=<signature>, computed over the timestamp, a dot and the raw body. The earlier docs showed a signature over the body alone.
  • The event body now includes mode, and data for order events is the full Order object.
  • Idempotency-Key is now required on every POST.
  • Error bodies and identifiers now use the formats in the reference.

Documentation