Skip to main content
eSIM Story API lets you order eSIMs from your own systems over HTTP.

​
How an order works

Orders are asynchronous. You get an acknowledgement straight away, and the eSIM itself arrives later on your webhook.
  1. Sign the request. Every call carries three headers derived from your secret key. See Authentication.
  2. Create the order. POST /v1/api_partner/orders with your own order ID and the products you want.
  3. Read the 201. It returns one topup_id per unit ordered. The eSIM data is not in this response.
  4. Receive a webhook per unit. Once each eSIM is issued, we POST its activation data to your webhook URL. Failed deliveries are retried, so the same unit can arrive more than once.
  5. Verify the signature, then process. Match the delivery to your order with external_order_id, and to the unit with topup_id — which is also the key to deduplicate on.
There is no endpoint to poll for eSIM data. If you have not configured a webhook URL, you will never receive it.

​
Base URL

Production
Sandbox
Paths in these docs are relative to that base. POST /v1/api_partner/orders means https://api.esimstory.com/api/v1/api_partner/orders.

​
Credentials

Three values, issued per environment: Production credentials are in your partner dashboard. Sandbox credentials are issued separately — contact support to have a sandbox account set up. Sandbox and production do not share credentials. Sandbox orders use test data and cost nothing, and its webhooks are signed exactly as production ones are, so you can build and test signature verification there before going live.

​
Before you write any code

Two of these come from us and cannot be worked out from the docs, so collect them first rather than discovering them mid-integration.
1

Your product catalogue

The option_id values you order with are not discoverable through the API — there is no catalogue endpoint. eSIM Story issues your catalogue as a CSV when your partner account is set up; ask support if you do not have it. See Reading your catalogue for which column goes in the request.
2

A registered webhook URL

The eSIM never appears in an API response, and there is nothing to poll instead. Give support the URL before you place your first order.

​
Reading these docs with an AI assistant

The docs are published in machine-readable form, so you can point a coding agent at them rather than pasting pages:
State your option_id values in the prompt. They come from your catalogue rather than from any endpoint, so an assistant working from the docs alone cannot find them — and will invent one if you let it.

Authentication

Sign your requests

Create an order

The endpoint, the webhook, and the errors
Last modified on August 10, 2026