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
- Sign up at numesim.uk/business. Your sandbox account exists the moment you do: no approval, $100 of test credit already on it.
- Create a test key in the console under API keys. It starts
numk_test_. - 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 | Live | |
|---|---|---|
| Key prefix | numk_test_ | numk_live_ |
| Available | Immediately, on sign-up | The moment your first card top-up is confirmed, once the sandbox checklist is complete |
| Credit | $100 of test credit, refilled automatically | Real prepaid credit you top up by card in the console (minimum $50) |
| eSIMs | Demo eSIMs. Not real. | Real eSIMs on real networks |
| Cost to you | Nothing, ever | The wholesale price of each order |
| Behaviour | Identical 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" }
}
]
}
| Field | Meaning |
|---|---|
planId | Num's identifier for the plan. Stable: the same plan always has the same id. Send it back when ordering |
wholesale | What an order of this plan costs you |
retail | A suggested price for your customer, from the markup you set in the console. Yours to use or ignore |
dataMb, days | Data allowance and validity |
Rules that keep an integration correct in production:
- Money is integers in minor units.
155is $1.55. Never parseamountas 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
planIdyou stored last month may no longer be sold; ordering it returns404. 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 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
| Status | Meaning | What you do |
|---|---|---|
active | The eSIM is issued. activationCode and qrUrl are present | Give it to your customer |
pending | Paid for, and the network has not released the profile yet. Usually seconds, occasionally minutes | Wait for the order.active webhook, or poll GET /v1/orders/{id} |
failed | It could not be issued. The charge has been reversed to your balance | Tell your customer; order again if you wish |
cancelling | A cancellation is being carried out | Nothing; it becomes cancelled |
cancelled | The 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.
| Field | What it is | Use it for |
|---|---|---|
qrUrl | A hosted PNG of the activation QR code. Needs no API key; the link itself is unguessable | Emails, confirmation pages, PDFs: put it in an <img> tag |
activationCode | The LPA:1$… string the QR encodes | Rendering your own QR, or manual entry on the phone |
install.ios, install.android | A link that opens the phone's own eSIM installer | A 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:
- 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
installlink or the activation code as well. installisnullin 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
qrUrllike 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.
| Field | Meaning |
|---|---|
customerEmail | Optional. Where to send the eSIM |
customerName | Optional. Used in the greeting |
sendEmail | Optional, 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.customer | Meaning |
|---|---|
sent | Emailed to the traveller (live) |
preview_sent | Sandbox: a preview went to your login email, not to the traveller |
skipped | Not sent; note says why |
null | No customerEmail was given |
- 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 apendingorder that is when the eSIM is released, not when you placed the order. POST /v1/orders/{id}/emailsends it again. Put acustomerEmailin 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
| Event | When | data |
|---|---|---|
order.active | An eSIM is issued, straight away or after being pending | { order } |
order.failed | An order could not be issued; the charge was reversed | { order } |
order.cancelled | An eSIM was cancelled, by you or by Num | { order, cancelledBy } |
credit.added | Credit landed on your balance: a card top-up, or credit posted by Num | { amount, balance, reference, source } |
account.live | Live 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.low | An order took your balance below your threshold (default $20). In live we also email your account owner with a top-up link | { balance, threshold } |
ping | You 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
- Answer with any
2xxwithin 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
idand make your handler safe to run twice. - Events can arrive out of order. Trust the
statusin 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 } }
| Status | Meaning | Retry? |
|---|---|---|
400 | The request is malformed: a missing header, a bad country code | No. Fix the request |
401 | Missing, unknown or revoked key | No |
402 | Not enough credit for this order. Nothing was issued | After credit is added |
403 | The key may not do this: live is not enabled, the account is suspended, the country is switched off | No |
404 | No such order, or the plan is not sold | No. Refresh the catalogue |
409 | The order is in a state that does not allow this | No |
429 | Rate limit reached | Yes, after a short wait |
500 | Something went wrong on our side | Yes, with the same Idempotency-Key |
424 | The eSIM could not be issued. The charge has been reversed | Yes, 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-Simulate | What happens | What your code must do |
|---|---|---|
insufficient_credit | 402, nothing issued, nothing charged | Stop selling, alert whoever tops up, tell the customer plainly |
provisioning_failed | The order is charged, fails, and is reversed. 424, then order.failed | Not deliver anything; retry with a new key or offer another plan |
pending | The order returns pending with no activation code, and becomes active about 15 seconds later with order.active | Wait 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" } ] }
| Check | How it is completed |
|---|---|
| Create a test API key | Console → API keys |
| Fetch the catalogue | GET /v1/catalog |
| Place a sandbox order | POST /v1/orders returns active |
| Read an order back | GET /v1/orders/{id} |
| Retry an order safely | The same Idempotency-Key sent twice |
| Handle insufficient credit | Num-Simulate: insufficient_credit |
| Handle a failed order | Num-Simulate: provisioning_failed |
| Handle a delayed eSIM | Num-Simulate: pending, then the order reaches active |
| Set a webhook endpoint | Console → Webhooks |
| Receive a signed webhook | Your endpoint answers 2xx |
| Check your balance or statement | GET /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:
- Keys live in a secret store on your server, never in a browser, an app or a repository.
- You store our order
idagainst 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.
- Finish the checklist: every item above, in sandbox, and confirm your login email in the console.
GET /v1/readinesstells you when it is complete. - Set your live webhook endpoint now (Console → Webhooks → Live), so the activation and your first
credit.addedreach you. - 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.livefires to each endpoint you have configured, thencredit.addedfires. You receive an email saying you are live. - 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" } ] }
type | Meaning |
|---|---|
topup | Credit added. ref is the top-up reference (NUMT-…) for a card top-up, or the invoice number when Num posted it |
order | An eSIM you ordered. ref is the order id |
refund | A charge reversed because an eSIM could not be issued |
adjustment | A correction by Num, or sandbox test credit |
12. Billing and cancellation
| Currency | USD. Every price, charge and balance |
| Model | Prepaid credit. You top up; orders draw on the balance. Nothing is issued on credit you have not paid for |
| Topping up | Instant 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 fee | Added 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 billing | By 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 costs | The wholesale price in the catalogue when the order is placed |
| Other fees | None. No setup fee, no monthly fee, no minimum volume |
| If the balance is short | The order is refused with 402 and nothing is issued |
| If an eSIM cannot be issued | The charge is reversed to your balance automatically |
| Refunds | Credit is non-refundable, and an issued eSIM is not refunded |
| Cancelling | You can cancel an eSIM at any time. Cancelling does not return credit |
| Num's rights | Num 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
- 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 usefunding: "credit". - Live cancellation is not instant. A live order moves to
cancellingwhile the eSIM is stopped, then tocancelled. 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.
topUptells 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.