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.

SandboxLive
Key prefixnumk_test_numk_live_
AvailableImmediately, on sign-upThe moment your first card top-up is confirmed, once the sandbox checklist is complete
Credit$100 of test credit, refilled automaticallyReal prepaid credit you top up by card in the console (minimum $50)
eSIMsDemo eSIMs. Not real.Real eSIMs on real networks
Cost to youNothing, everThe wholesale price of each order
BehaviourIdentical to live—

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 1 GB · 7 days",
      "country": "JP",
      "dataMb": 1024,
      "days": 7,
      "topUp": true,
      "wholesale": { "amountMinor": 155, "amount": "1.55", "currency": "USD" },
      "retail":    { "amountMinor": 186, "amount": "1.86", "currency": "USD" }
    }
  ]
}
FieldMeaning
planIdNum's identifier for the plan. Stable: the same plan always has the same id. Send it back when ordering
wholesaleWhat an order of this plan costs you
retailA suggested price for your customer, from the markup you set in the console. Yours to use or ignore
dataMb, daysData allowance and validity

Rules that keep an integration correct in production:


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 1 GB · 7 days",
  "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

StatusMeaningWhat you do
activeThe eSIM is issued. activationCode and qrUrl are presentGive it to your customer
pendingPaid for, and the network has not released the profile yet. Usually seconds, occasionally minutesWait for the order.active webhook, or poll GET /v1/orders/{id}
failedIt could not be issued. The charge has been reversed to your balanceTell your customer; order again if you wish
cancellingA cancellation is being carried outNothing; it becomes cancelled
cancelledThe eSIM has been stopped. Credit is not returned—

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.

FieldWhat it isUse it for
qrUrlA hosted PNG of the activation QR code. Needs no API key; the link itself is unguessableEmails, confirmation pages, PDFs: put it in an <img> tag
activationCodeThe LPA:1$… string the QR encodesRendering your own QR, or manual entry on the phone
install.ios, install.androidA link that opens the phone's own eSIM installerA button shown on the phone that will use the 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:

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.

FieldMeaning
customerEmailOptional. Where to send the eSIM
customerNameOptional. Used in the greeting
sendEmailOptional, default true. Send false to store the address without emailing

The order reports what happened:

"customerEmail": "[email protected]",
"email": { "customer": "sent", "partner": "sent", "note": null }
email.customerMeaning
sentEmailed to the traveller (live)
preview_sentSandbox: a preview went to your login email, not to the traveller
skippedNot sent; note says why
nullNo customerEmail was given

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.


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

EventWhendata
order.activeAn eSIM is issued, straight away or after being pending{ order }
order.failedAn order could not be issued; the charge was reversed{ order }
order.cancelledAn eSIM was cancelled, by you or by Num{ order, cancelledBy }
credit.addedCredit landed on your balance: a card top-up, or credit posted by Num{ amount, balance, reference, source }
account.liveLive was switched on for your account, by your first top-up once the checklist was complete. Sent to each endpoint you have configured, sandbox and live, since you may only have one at that moment{ account, activatedAt, trigger, reference, balance }
balance.lowAn order took your balance below your threshold (default $20). In live we also email your account owner with a top-up link{ balance, threshold }
pingYou pressed "Send test event"{ message }

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

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 } }
StatusMeaningRetry?
400The request is malformed: a missing header, a bad country codeNo. Fix the request
401Missing, unknown or revoked keyNo
402Not enough credit for this order. Nothing was issuedAfter credit is added
403The key may not do this: live is not enabled, the account is suspended, the country is switched offNo
404No such order, or the plan is not soldNo. Refresh the catalogue
409The order is in a state that does not allow thisNo
429Rate limit reachedYes, after a short wait
500Something went wrong on our sideYes, with the same Idempotency-Key
424The eSIM could not be issued. The charge has been reversedYes, with a new Idempotency-Key

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:

Num-SimulateWhat happensWhat your code must do
insufficient_credit402, nothing issued, nothing chargedStop selling, alert whoever tops up, tell the customer plainly
provisioning_failedThe order is charged, fails, and is reversed. 424, then order.failedNot deliver anything; retry with a new key or offer another plan
pendingThe order returns pending with no activation code, and becomes active about 15 seconds later with order.activeWait for the webhook or poll, then deliver

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" } ] }
CheckHow it is completed
Create a test API keyConsole → API keys
Fetch the catalogueGET /v1/catalog
Place a sandbox orderPOST /v1/orders returns active
Read an order backGET /v1/orders/{id}
Retry an order safelyThe same Idempotency-Key sent twice
Handle insufficient creditNum-Simulate: insufficient_credit
Handle a failed orderNum-Simulate: provisioning_failed
Handle a delayed eSIMNum-Simulate: pending, then the order reaches active
Set a webhook endpointConsole → Webhooks
Receive a signed webhookYour endpoint answers 2xx
Check your balance or statementGET /v1/balance or GET /v1/ledger

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

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 1 GB · 7 days · JP",
    "createdAt": "2026-10-04T09:12:44.000Z" } ] }
typeMeaning
topupCredit added. ref is the top-up reference (NUMT-…) for a card top-up, or the invoice number when Num posted it
orderAn eSIM you ordered. ref is the order id
refundA charge reversed because an eSIM could not be issued
adjustmentA correction by Num, or sandbox test credit

12. Billing and cancellation

CurrencyUSD. Every price, charge and balance
ModelPrepaid credit. You top up; orders draw on the balance. Nothing is issued on credit you have not paid for
Topping upInstant and automatic. Pay by card in the console and the credit is added within seconds, 24/7, with an emailed receipt and credit.added; nobody at Num needs to act. Minimum $50 per top-up, maximum $10,000. Your first top-up, once the sandbox checklist is complete, also switches live on
Card processing feeAdded at checkout: 2.9% + 30¢ of the amount charged, so the credit you receive is exactly the amount you chose. For a $100 top-up the card is charged $103.30
Invoice billingBy arrangement, for larger accounts: we invoice you, and credit is added when the invoice is paid. An invoiced account does not top up by card
What an order costsThe wholesale price in the catalogue when the order is placed
Other feesNone. No setup fee, no monthly fee, no minimum volume
If the balance is shortThe order is refused with 402 and nothing is issued
If an eSIM cannot be issuedThe charge is reversed to your balance automatically
RefundsCredit is non-refundable, and an issued eSIM is not refunded
CancellingYou can cancel an eSIM at any time. Cancelling does not return credit
Num's rightsNum may cancel or suspend an eSIM or an account at any time, as set out in the API Terms

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