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

Quick Start

This guide takes you from a new partner account to an eSIM your customer can install, using the API directly. It runs in the sandbox, so nothing is bought and nothing is charged.

Before you start

Section titled “Before you start”

You need a partner account and a test key. If you do not have an account yet, register at business.esimify.in or ask for partner access.

  1. Sign in to the Business portal at business.esimify.in and open Developers. If the page says API access is not enabled, email support@esimify.in.
  2. Copy your base URL from the Overview tab. It ends in /partner/api.
  3. On the API keys tab, choose Create key in Test mode. Copy the key straight away. It is shown once.

Every example below uses two environment variables:

Terminal window
export ESIMIFY_API_URL="<the base URL from the Developers page>"
export ESIMIFY_API_KEY="sk_test_..."

The commands are written for bash or zsh. On Windows use Git Bash or WSL, or run the Postman collection instead.

The ids in the examples, such as pkg_10482 and 8999999000000012345, are samples. Replace them with the ids from your own responses.

Step 1: Find a package

Section titled “Step 1: Find a package”

List the packages for a destination. Each one comes with its data allowance, validity and price for your account.

Terminal window
curl "$ESIMIFY_API_URL/v1/packages?country=TH&limit=1" \
  -H "Authorization: Bearer $ESIMIFY_API_KEY"
{
  "data": [
    {
      "id": "pkg_10482",
      "name": "Thailand 1 GB 7 days",
      "type": "country",
      "country": "TH",
      "countries": [
        "TH"
      ],
      "data_mb": 1024,
      "unlimited": false,
      "validity_days": 7,
      "price": {
        "amount": "249.00",
        "currency": "INR"
      },
      "retail_price": {
        "amount": "349.00",
        "currency": "INR"
      },
      "topup": true
    }
  ],
  "has_more": true,
  "next_cursor": "MTA0ODI"
}

Keep the id of the package your customer chooses. price is what it costs you. The list shows one package for each destination, data size and validity. See How the catalogue works.

Step 2: Check your balance

Section titled “Step 2: Check your balance”

Orders are charged to your partner balance. In the sandbox the balance is virtual and starts at 1000000.00 INR.

Terminal window
curl "$ESIMIFY_API_URL/v1/balance" \
  -H "Authorization: Bearer $ESIMIFY_API_KEY"
{
  "balance": {
    "amount": "1000000.00",
    "currency": "INR"
  },
  "low_balance_threshold": null,
  "mode": "test"
}

low_balance_threshold is null until you set a threshold in the Business portal under Settings.

Step 3: Place the order

Section titled “Step 3: Place the order”

Send the package id, a quantity and your own reference for the sale. The Idempotency-Key header is required. It makes the call safe to retry: sending the same key again returns the first order instead of creating a second one. Use the id you got in step 1 as package_id, and a new Idempotency-Key for each new order.

Terminal window
curl -X POST "$ESIMIFY_API_URL/v1/orders" \
  -H "Authorization: Bearer $ESIMIFY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: booking-84512" \
  -d '{
    "package_id": "pkg_10482",
    "quantity": 1,
    "customer_ref": "booking-84512"
  }'
{
  "id": "ord_test_3f9a1c2b7d4e",
  "status": "completed",
  "mode": "test",
  "package_id": "pkg_10482",
  "quantity": 1,
  "items": [
    {
      "package_id": "pkg_10482",
      "quantity": 1
    }
  ],
  "customer_ref": "booking-84512",
  "total": {
    "amount": "249.00",
    "currency": "INR"
  },
  "refunded": {
    "amount": "0.00",
    "currency": "INR"
  },
  "balance_after": {
    "amount": "999751.00",
    "currency": "INR"
  },
  "created": "2026-10-02T09:14:07Z",
  "esims": [
    {
      "iccid": "8999999000000012345",
      "status": "ready"
    }
  ]
}

Always check status. Most orders are completed in the same call. If the status is processing, wait for the order.completed or order.failed webhook, or fetch the order again. The order lists the ICCID of each eSIM. The install details are on the eSIM itself, in the next step.

Step 4: Deliver the eSIM

Section titled “Step 4: Deliver the eSIM”

Fetch the eSIM to get everything your customer needs to install it.

Terminal window
curl "$ESIMIFY_API_URL/v1/esims/8999999000000012345" \
  -H "Authorization: Bearer $ESIMIFY_API_KEY"
{
  "iccid": "8999999000000012345",
  "status": "ready",
  "mode": "test",
  "order_id": "ord_test_3f9a1c2b7d4e",
  "customer_ref": "booking-84512",
  "package": {
    "id": "pkg_10482",
    "name": "Thailand 1 GB 7 days"
  },
  "qr_code_url": "https://api.example.com/partner/api/v1/qr/ODk5OTk5OTAwMDAwMDAxMjM0NQ.3f9a1c2b5e8d7c6b4a39281706f5e4d3c2b1a098.png",
  "activation": {
    "lpa": "LPA:1$sandbox.esimify.in$TEST-A1B2C3D4E5F6",
    "smdp_address": "sandbox.esimify.in",
    "activation_code": "TEST-A1B2C3D4E5F6"
  },
  "install_links": {
    "ios": "https://esimsetup.apple.com/esim_qrcode_provisioning?carddata=LPA%3A1%24sandbox.esimify.in%24TEST-A1B2C3D4E5F6",
    "android": "https://esimsetup.android.com/esim_qrcode_provisioning?carddata=LPA%3A1%24sandbox.esimify.in%24TEST-A1B2C3D4E5F6"
  },
  "data": {
    "unlimited": false,
    "total_mb": 1024,
    "used_mb": 0,
    "remaining_mb": 1024
  },
  "validity_days": 7,
  "activated_at": null,
  "expires_at": null,
  "created": "2026-10-02T09:14:07Z"
}

Show the image at qr_code_url, or offer the one-tap link from install_links. Use both exactly as returned: the links are already encoded, so do not encode them again. Delivering eSIMs covers both. Sandbox eSIMs cannot be installed on a phone.

Step 5: Top up the eSIM

Section titled “Step 5: Top up the eSIM”

When the customer needs more data, add a package to the eSIM they already have. First ask which packages this eSIM can take:

Terminal window
curl "$ESIMIFY_API_URL/v1/esims/8999999000000012345/topup-packages" \
  -H "Authorization: Bearer $ESIMIFY_API_KEY"

The answer is { "data": [ ... ] }, a list of Package objects.

Then add one of them. Use a new Idempotency-Key for each top-up.

Terminal window
curl -X POST "$ESIMIFY_API_URL/v1/esims/8999999000000012345/topups" \
  -H "Authorization: Bearer $ESIMIFY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: booking-84512-topup-1" \
  -d '{ "package_id": "pkg_10482" }'
{
  "id": "top_test_7a1c9e02b4d6",
  "status": "completed",
  "iccid": "8999999000000012345",
  "package_id": "pkg_10482",
  "customer_ref": null,
  "total": {
    "amount": "249.00",
    "currency": "INR"
  },
  "balance_after": {
    "amount": "999502.00",
    "currency": "INR"
  },
  "created": "2026-10-04T06:30:12Z"
}

Check status here too. A top-up can come back as failed, with the amount returned to your balance.

Step 6: Receive a webhook

Section titled “Step 6: Receive a webhook”

Webhooks tell your server when something changes, so you do not have to keep asking.

  1. In the Business portal, open Developers, then Webhooks, and choose Add endpoint to add an HTTPS address in Test mode.
  2. Copy the signing secret, which starts with whsec_.
  3. Choose Send test event on the endpoint. A ping event arrives there.
  4. Make the sandbox eSIM look activated:
Terminal window
curl -X POST "$ESIMIFY_API_URL/v1/sandbox/esims/8999999000000012345/simulate" \
  -H "Authorization: Bearer $ESIMIFY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: sim-activated-001" \
  -d '{ "event": "activated" }'

An esim.activated event arrives at your endpoint. Webhooks shows how to check its signature.

The event is sent the first time only. If you run this command again with the same Idempotency-Key, you get the first response back and nothing is sent. If you run it with a new key, the eSIM is already active, so nothing changes and nothing is sent.

What’s next

Section titled “What’s next”