Num Corporate API — v1

Issue travel eSIMs from your own product. One call returns an activation code, a hosted QR image and one-tap install links for your customer.

This page is the complete reference, and it is written so that an integration which passes in sandbox is ready for production. Section 10 lists the cases your code must handle, how to trigger each one in sandbox, and a checklist we track for you automatically.

Base URL:

https://numesim.uk/v1

JSON in, JSON out, UTF-8. All money is USD, always, whatever country the plan is for.

1. Quickstart

1. Sign up at numesim.uk/business. Your sandbox account exists the moment you do: no approval, $100 of test credit already on it.
2. Create a test key in the console under API keys. It starts numk_test_.
3. Price a destination, then place an order:

curl "https://numesim.uk/v1/catalog?country=JP" \
  -H "Authorization: Bearer numk_test_…"

curl -X POST https://numesim.uk/v1/orders \
  -H "Authorization: Bearer numk_test_…" \
  -H "Idempotency-Key: booking-48213" \
  -H "Content-Type: application/json" \
  -d '{"planId":"np_3f9a61c0d2e47b18aa","country":"JP","funding":"credit"}'

The response is the eSIM: an activationCode, a qrUrl you can put straight into an email, and its iccid.

2. Sandbox and live

There are two environments. The key prefix chooses between them, and they never mix.

Sandbox eSIMs are not real. A sandbox order never contacts a mobile network. Its activation code looks like LPA:1$demo.esim.test$…, its ICCID starts 8900000000, and every sandbox order carries "demo": true. A demo code will scan as a QR but will not install on a phone. Never show a sandbox code to a traveller; branch on demo if your test and production systems share code.

Sandbox is always usable. Test credit refills itself when an order would run it dry, so an integration is never stopped by a balance that was never real. To rehearse an empty balance, use the simulation header in section 10.

Everything else is the same in both: the endpoints, the response shapes, the prices, the errors and the webhooks. Going live is a change of key, not a change of code.

3. Authentication

A bearer key on every request:

Authorization: Bearer numk_test_9f2c…

Keys are created in the business console and shown once. We store only a SHA-256 hash, so a lost key cannot be recovered, only replaced. Create one key per system so you can revoke one without stopping the others. Revocation takes effect within a minute.

There is no CORS. These endpoints are server-to-server. A key that reaches browser or mobile-app code is a public key, and anyone reading the page can spend your credit. Call the API from your backend.

4. Plans and prices

GET /v1/catalog?country=JP

country is an ISO 3166-1 alpha-2 code, or one of the regional bundles: GLOBAL, EUROPE, ASIA, MIDDLE-EAST, AFRICA, CARIBBEAN. With no country at all you get the Global eSIM catalogue.

Lead with the Global eSIM. It is one plan that works in 130+ countries, from a week to a year, so for a booking that crosses borders, a stopover, a cruise, or a customer who travels often, it is the product to offer first: one SKU to integrate, nothing to pick per country, and a customer who never needs a second eSIM mid-trip. A single-country plan is cheaper per gigabyte for one destination; offer both and let the itinerary decide.

GET /v1/catalog?country=GLOBAL
GET /v1/catalog

{
  "country": "JP",
  "currency": "USD",
  "plans": [
    {
      "planId": "np_3f9a61c0d2e47b18aa",
      "name": "Japan 1GB 7Days",
      "country": "JP",
      "dataMb": 1024,
      "days": 7,
      "topUp": true,
      "wholesale": { "amountMinor": 155, "amount": "1.55", "currency": "USD" },
      "retail":    { "amountMinor": 186, "amount": "1.86", "currency": "USD" }
    }
  ]
}

Rules that keep an integration correct in production:

• Money is integers in minor units. 155 is $1.55. Never parse amount as a float for arithmetic; it is there for display.
• Prices move. Read the catalogue rather than hard-coding prices, and cache it for no longer than an hour. An order is charged the wholesale price in force when it is placed.
• Plans come and go. A planId you stored last month may no longer be sold; ordering it returns 404. Refresh from the catalogue.
• Countries and packages you have switched off in the console do not appear.

5. Orders

POST /v1/orders

Requires an Idempotency-Key header (section 7).

{ "planId": "np_3f9a61c0d2e47b18aa", "country": "JP", "funding": "credit" }

country is the code or region name you fetched the catalogue with; for the Global eSIM send "country": "GLOBAL":

{ "planId": "np_7c1e22b0f9a84d6e11", "country": "GLOBAL", "funding": "credit" }

201 Created:

{
  "id": "NAH9XIRi4HjCaQwsrfc5",
  "status": "active",
  "funding": "credit",
  "mode": "sandbox",
  "demo": true,
  "country": "JP",
  "planId": "np_3f9a61c0d2e47b18aa",
  "planName": "Japan 1GB 7Days",
  "charged": { "amountMinor": 155, "amount": "1.55", "currency": "USD" },
  "activationCode": "LPA:1$demo.esim.test$NAH9XIRI4HJCAQWSRFC5",
  "iccid": "8900000000NAH9XIRi4",
  "qrUrl": "https://numesim.uk/v1/qr/…png",
  "install": null,
  "customerEmail": null,
  "email": { "customer": null, "partner": "sent", "note": null },
  "createdAt": "2026-10-04T09:12:44.000Z"
}

Optional request fields: customerEmail, customerName and sendEmail, to have Num email the eSIM to your traveller. See section 6.

Order status

Always handle pending. Most orders are active in the response. Some are not, and code that assumes an activation code is always present will break on the day it matters. Section 10 shows how to trigger a pending order in sandbox.

GET /v1/orders and GET /v1/orders/{id}

GET /v1/orders?limit=50 returns your newest orders first (maximum 100). GET /v1/orders/{id} returns one, and is how you poll a pending order. Poll no more often than every five seconds; prefer the webhook.

POST /v1/orders/{id}/cancel

Stops an eSIM. Returns the order, with status cancelled (sandbox) or cancelling then cancelled (live).

Cancelling does not return credit. Credit is prepaid and non-refundable; a cancellation ends the eSIM, it does not undo the purchase. Cancelling an order that is already cancelled is not an error.

6. Giving the eSIM to your customer

An active order gives you three ways to deliver it. Use whichever fits your product; they all install the same eSIM.

GET /v1/orders/{id}/qr returns the same PNG with your bearer key, if you would rather fetch the image yourself and serve it from your own domain.

Notes:

• The QR is scanned by another screen. A traveller reading your email on the phone they want to install on cannot scan it; give them the install link or the activation code as well.
• install is null in sandbox: a demo code would open the installer and then fail in front of the user.
• An activation code can normally be installed once. Treat qrUrl like the eSIM itself and send it only to the customer it belongs to.

Let Num email it for you

Pass the traveller's address on the order and Num sends the eSIM to them, under your brand name:

{ "planId": "np_3f9a61c0d2e47b18aa", "country": "JP", "funding": "credit",
  "customerEmail": "[email protected]", "customerName": "Alex" }

The email carries your brand name as its heading and sender name, the QR code, the activation code, install buttons and install steps. Replies go to the support address you set. Set your brand name and addresses in the console under Branding & email, and send yourself a preview from there.

The order reports what happened:

"customerEmail": "[email protected]",
"email": { "customer": "sent", "partner": "sent", "note": null }

• Sandbox never emails a traveller. The address you pass is recorded, and a preview of the email is sent to your own login address instead, once you have verified it. This is deliberate: a sandbox eSIM is not real, and a test must not be able to reach a real person.
• The email is sent when the order becomes active. For a pending order that is when the eSIM is released, not when you placed the order.
• POST /v1/orders/{id}/email sends it again. Put a customerEmail in the body to correct a mistyped address first.
• The email is sent by Num. Your brand name is shown as plain text; logos and custom HTML are not supported.

You are told about every purchase too. Each time an eSIM is issued on your account, Num emails your notification address with the plan, the charge and your balance. Turn this off in the console if you would rather rely on the order.active webhook.

Installation, for your help pages: Settings → Mobile Service → Add eSIM → Use QR Code, then turn on Data Roaming for the new line.

7. Idempotency

POST /v1/orders requires an Idempotency-Key header: any string that is unique to the purchase you are making, such as your own booking reference.

Send the same key again and you get the original order back with 200, not a second eSIM and not a second charge. This is what makes a retry safe: if a request times out and you do not know whether it worked, send it again with the same key.

• Use one key per purchase, never one per attempt.
• Do not reuse a key for a different plan; the original order is what returns.

8. Webhooks

Set one https endpoint per environment in the console under Webhooks. We send a POST with a JSON body whenever something happens that you would otherwise have to poll for.

Events

Payload

{
  "id": "evt_8tQ2mWc1YbN4",
  "type": "order.active",
  "mode": "live",
  "createdAt": "2026-10-04T09:12:46.000Z",
  "data": { "order": { "id": "NAH9XIRi4HjCaQwsrfc5", "status": "active", "…": "…" } }
}

order is exactly the object GET /v1/orders/{id} returns.

Verifying the signature

Every delivery carries:

Num-Signature: t=1791112366,v1=5f2b…e9
Num-Event: order.active
Num-Delivery: 8tQ2mWc1YbN4

v1 is the HMAC-SHA256, in hex, of the string {t}.{raw request body} using your endpoint's signing secret (shown once when you save the endpoint; saving again rotates it). Verify it before trusting anything in the body, compare in constant time, and reject a timestamp more than five minutes old.

Node:

const crypto = require("crypto");

function verify(rawBody, header, secret) {
  const parts = Object.fromEntries(header.split(",").map((p) => p.split("=")));
  if (Math.abs(Date.now() / 1000 - Number(parts.t)) > 300) return false;
  const expected = crypto.createHmac("sha256", secret)
    .update(parts.t + "." + rawBody).digest("hex");
  const a = Buffer.from(expected), b = Buffer.from(parts.v1 || "");
  return a.length === b.length && crypto.timingSafeEqual(a, b);
}

Python:

import hashlib, hmac, time

def verify(raw_body: bytes, header: str, secret: str) -> bool:
    parts = dict(p.split("=", 1) for p in header.split(","))
    if abs(time.time() - int(parts["t"])) > 300:
        return False
    signed = parts["t"].encode() + b"." + raw_body
    expected = hmac.new(secret.encode(), signed, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, parts.get("v1", ""))

PHP:

function verify(string $rawBody, string $header, string $secret): bool {
    parse_str(str_replace(',', '&', $header), $parts);
    if (abs(time() - (int) $parts['t']) > 300) return false;
    $expected = hash_hmac('sha256', $parts['t'] . '.' . $rawBody, $secret);
    return hash_equals($expected, $parts['v1'] ?? '');
}

Use the raw request body, byte for byte. Parsing the JSON and re-serialising it changes the bytes and the signature will not match.

Delivery rules

• Answer with any 2xx within 5 seconds. Do the real work after you have answered; a slow handler is treated as a failure.
• A failed delivery is retried after about 1 minute, 5 minutes, 30 minutes, 2 hours, 6 hours and 12 hours, then abandoned. Seven attempts in all.
• The same event can arrive more than once. Deduplicate on the event id and make your handler safe to run twice.
• Events can arrive out of order. Trust the status in the payload, or fetch the order, rather than the order in which events reached you.
• Redirects are not followed. Give us the final URL.
• The console shows every delivery, its attempts and the last error.

Webhooks are a convenience, not the record. GET /v1/orders/{id} is always authoritative, and an integration should still work, more slowly, with the endpoint switched off.

9. Errors

Standard HTTP status with a JSON body:

{ "error": "Insufficient credit.", "detail": { "balanceMinor": 40, "requiredMinor": 155, "shortfallMinor": 115 } }

Retry with exponential backoff, starting at one second. Any other 5xx, including an HTML error page from the network in front of the API, means the same as 500. On a timeout or a 5xx you do not know whether the order exists, which is exactly what the idempotency key is for.

10. Building for production

Sandbox lets you rehearse every outcome production can produce. Send the Num-Simulate header on POST /v1/orders with a test key:

The header is rejected with 400 on a live key. Nothing a client sends can make a real order fail.

Go-live checklist

We tick each of these the first time your account does it in sandbox. See it in the console under Go live, or fetch it:

curl https://numesim.uk/v1/readiness -H "Authorization: Bearer numk_test_…"

{ "liveEnabled": false, "done": 7, "total": 11,
  "items": [ { "key": "catalog", "label": "Fetch the catalogue", "done": true, "at": "2026-10-04T09:10:02.000Z" } ] }

The checklist records that each path was exercised. It cannot see whether your handler did the right thing, so also confirm for yourself:

• Keys live in a secret store on your server, never in a browser, an app or a repository.
• You store our order id against your own booking.
• A sandbox order ("demo": true) can never reach a real customer.
• If Num emails your travellers, you have sent yourself a preview and your brand name and reply-to address are right.
• Webhook signatures are verified and events are deduplicated by id.
• Something alerts a person when the balance is low, before orders start returning 402.
• Your customer is told what to do if the eSIM does not arrive within a minute.

Going live

There is no approval step. Live is switched on by your first verified top-up.

1. Finish the checklist: every item above, in sandbox, and confirm your login email in the console. GET /v1/readiness tells you when it is complete.
2. Set your live webhook endpoint now (Console → Webhooks → Live), so the activation and your first credit.added reach you.
3. Add your first credit by card from the console: choose an amount (minimum $50), pay it plus the card processing fee on Stripe. When Stripe confirms the payment, in that order and in one go: the credit is posted to your live balance, live is switched on for your account, account.live fires to each endpoint you have configured, then credit.added fires. You receive an email saying you are live.
4. Create a numk_live_ key and change the key in your configuration. Nothing else changes.

Activation is idempotent: a retried Stripe event, a second top-up, or an account already switched on by Num never fires account.live twice. If your checklist is not complete, the console will not let you start a live top-up, and a top-up that somehow arrived early would be credited without switching live on; the next top-up after the checklist is complete switches it on.

Want volume pricing or invoice billing before you go live? Press Contact us about going live in the console; it does not hold anything up.

11. Account, balance and statement

GET /v1/me

{ "companyName": "Northwind Travel", "mode": "sandbox", "liveEnabled": false,
  "discountPercent": 10, "currency": "USD",
  "balance": { "amountMinor": 9845, "amount": "98.45", "currency": "USD" } }

GET /v1/balance

{ "mode": "live", "balance": { "amountMinor": 48210, "amount": "482.10", "currency": "USD" } }

GET /v1/ledger?limit=50

Your statement, newest first: every credit, order and reversal with the balance after it.

{ "mode": "live", "entries": [
  { "id": "9dK…", "type": "order", "amountMinor": -155, "amount": "-1.55", "currency": "USD",
    "balanceAfter": "482.10", "ref": "NAH9XIRi4HjCaQwsrfc5", "note": "Japan 1GB 7Days · JP",
    "createdAt": "2026-10-04T09:12:44.000Z" } ] }

12. Billing and cancellation

By creating an account you agree to the Num API Terms.

13. Rate limits

120 requests per minute, per key. Over that returns 429; wait and retry. The catalogue changes slowly, so cache it rather than fetching it per page view.

14. Known limits, stated plainly

• Hosted checkout is sandbox only. funding: "checkout", a payment page for your traveller, can be rehearsed in sandbox and is not available in live. Live orders use funding: "credit".
• Live cancellation is not instant. A live order moves to cancelling while the eSIM is stopped, then to cancelled. Sandbox cancels at once.
• One endpoint per environment. A single webhook URL for sandbox and a single one for live.
• Top-ups of an existing eSIM are not exposed in this version. topUp tells you whether a plan supports them.
• One currency. Everything is USD. You may charge your customer in any currency you like; what you pay us is USD.

Num API Terms

Version 2026-10-09.

These terms apply to every business that creates an account to use the Num API or the Num business console. By creating an account you agree to them on behalf of your company. They are written to be read; if anything is unclear, ask us before you rely on it.

"Num", "we" and "us" mean WorkersLab LLC, 30 N Gould St Ste R, Sheridan, WY 82801-6317, United States. "You" means the company whose account it is.

1. What you get

An account with a sandbox environment for building and testing, and, once we switch it on for you, a live environment in which orders issue real travel eSIMs.

Sandbox is not real. Sandbox eSIMs are demonstration data. They do not connect to any network and must not be given, sold or shown to a customer as a working eSIM. Sandbox credit has no monetary value.

2. Your account

• You are responsible for everything done with your account and your API keys. Keep keys secret and on your own servers. Tell us at once if a key may have leaked; we will revoke it.
• The information you give us about your company must be true, and you must keep your contact address current.
• Live is switched on for your account when you have completed the sandbox checklist in the console and your first top-up is confirmed. Live access remains at our discretion: we may ask what you intend to sell and to whom, and we may decline, delay or withdraw it under section 5.

3. Prices and payment

• All prices, charges and balances are in United States dollars.
• The price of an order is the wholesale price shown for that plan when the order is placed. Prices can change at any time; the catalogue is the current price.
• Live credit is prepaid. You add credit by card in the console: the minimum top-up is US$50, and the card processing fee (2.9% + 30¢ of the amount charged, or as shown at checkout) is added to the payment. The credit you receive is the amount you chose. By arrangement we may instead invoice you, in which case credit is added when the invoice is paid. Orders draw on the balance. We do not issue eSIMs on credit you have not paid for.
• A card top-up is a purchase of credit, and the fee is not returned if the credit is later unused.
• You set the price you charge your own customers, and you are responsible for any taxes on your sales.

4. No refunds; cancellation

• Credit is non-refundable. Prepaid credit that you have not spent is not returned, including when an account is closed.
• An issued eSIM is not refunded, whether or not it is installed or used.
• You may cancel an eSIM at any time through the API or the console. A cancelled eSIM stops working and cannot be restored. Cancelling does not return credit.
• If we are unable to issue an eSIM you ordered, the charge for that order is reversed to your balance. That is the only circumstance in which a charge is reversed.

5. Our right to cancel or suspend

We may cancel or suspend any eSIM, any order, any API key or your account, at any time and without notice, including where we believe there is fraud, misuse, a breach of these terms, a risk to a network or to other customers, an unpaid invoice, or a legal or regulatory reason to do so. Where we reasonably can, we will tell you what we have done and why. A cancellation under this section does not entitle you to a refund or a credit.

6. What you may not do

• Resell access to the API itself, or let another company use your keys.
• Use eSIMs for unlawful purposes, for automated or machine-to-machine traffic not agreed with us, or in a way that breaches a network's fair-use rules.
• Attempt to discover, contact or deal directly with our suppliers, or to work out our costs. The identity of our suppliers and the prices we pay are confidential.
• Probe, overload or attempt to circumvent the API's limits or security.
• Describe yourself as Num, or imply that we endorse your product, without our written agreement.

7. Your customers

You are the seller to your customers. You are responsible for telling them what they are buying, for their support in the first instance, and for complying with the consumer, telecommunications and data-protection law that applies to you. Give us only the personal data we need to provide the service; an order requires none.

8. Service

We aim for the API to be available at all times and for eSIMs to be issued within seconds, but we do not guarantee either. Mobile networks are operated by third parties: coverage, speed and availability vary by place and time and are outside our control. Plans and destinations may be withdrawn.

9. Liability

To the extent the law allows, the service is provided as is. We are not liable for indirect or consequential loss, lost profit, or loss arising from a network being unavailable. Our total liability to you in any twelve-month period is limited to the amount you paid us for orders in that period.

10. Changes and ending

We may change these terms. When a change is material we will tell the contact on your account, and continuing to use the API after that is acceptance of the new terms. You may stop using the API at any time. Sections 3, 4, 6, 7 and 9 continue to apply afterwards.

11. Law

These terms are governed by the laws of the State of Wyoming, United States, and its courts have jurisdiction, unless a law that applies to you cannot be excluded by agreement.

Questions: [email protected].