> ## Documentation Index
> Fetch the complete documentation index at: https://docs.esimmu.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Introduction

**eSIMmu 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](https://docs.esimmu.com/authentication/overview.md).
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.

To check an eSIM afterwards, see [Get eSIM status](https://docs.esimmu.com/endpoints/esim-status.md) and
[Get eSIM usage](https://docs.esimmu.com/endpoints/esim-usage.md). To refund one, see [Request a
refund](https://docs.esimmu.com/endpoints/request-refund.md).

> [!WARNING]
>
> There is no endpoint to poll for eSIM data. If you have not configured a
> webhook URL, you will never receive it.

## Base URL

```
https://api.esimmu.com/api
```

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

> [!NOTE]
>
> **Sandbox: coming soon.** There is no sandbox environment yet. Until there
> is, build and test against the [test vector](https://docs.esimmu.com/authentication/overview.md#test-vector)
> for signing and the [webhook test vector](https://docs.esimmu.com/endpoints/webhooks.md#test-vector)
> for verification, and place your first live order with your account manager
> aware of it.

## Credentials

Three values, issued by your account manager:

| Credential | Used for |
| - | - |
| Access key | Identifies you on every request |
| Secret key | Signs the requests you send us |
| Webhook signing secret | Verifies the webhooks we send you |

## Before you write any code

Collect these first rather than discovering them mid-integration.

**1. Your product list**

The `option_id` values you order with come from [List
products](https://docs.esimmu.com/endpoints/list-products.md), at your own price.

**2. A registered webhook URL**

The eSIM never appears in an API response, and there is nothing to poll
instead. Give your account manager 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:

| Resource | Path on this site |
| - | - |
| Page index for LLMs | `/llms.txt` |
| Every page as one file | `/llms-full.txt` |
| Any page as Markdown | Append `.md`, e.g. `/authentication/overview.md` |
| OpenAPI spec | `/api-reference/openapi.json` |
| Docs MCP server | `/mcp` |

> [!NOTE]
>
> An assistant working from the docs alone has no real `option_id` values, and
> will invent one if you let it. Have it call [List
> products](https://docs.esimmu.com/endpoints/list-products.md) for them, or paste a few into the prompt.

> [card] [Authentication](https://docs.esimmu.com/authentication/overview.md)
>
> Sign your requests

> [card] [List products](https://docs.esimmu.com/endpoints/list-products.md)
>
> The catalogue, at your price

> [card] [Create an order](https://docs.esimmu.com/endpoints/create-order.md)
>
> The endpoint and its errors

> [card] [Webhooks](https://docs.esimmu.com/endpoints/webhooks.md)
>
> Issued eSIMs and refund decisions

> [card] [Request a refund](https://docs.esimmu.com/endpoints/request-refund.md)
>
> Ask for a refund on one eSIM


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.