Documentation

Overview

RoamWorks Partner API v1

Local, regional and global eSIM infrastructure for partners and their agents.

RoamWorks is a wholesale eSIM platform. Approved partners discover local, regional and global offers, bind a 15-minute quote, pay from a prepaid USD, EUR or GBP wallet, and redeem purchased eSIMs through a controlled server-to-server API.

Start the quickstart Read the raw API Markdown Copy the agent prompt

Partner-onlyHMAC-SHA256USD / EUR / GBPOpenAPI 3.1Server-to-server

The API is built for approved resellers and their authorised agents. It is not a public shopping API. Every commerce call is signed, scoped, rate limited and audited, and the wallet is the only payment source for orders. The wallet is funded through Stripe Checkout; the API never receives card details.

What you can build

Catalogue and quotes

List eligible local eSIM offers, then bind offer, quantity and currency to a 15-minute quote, or use one-call ordering.

Wallet-funded orders

Create one atomic purchase with a stable reference and idempotency key. No order and no debit if stock, price or funds fail.

Controlled redemption

Redeem up to 20 eSIMs per idempotent batch and deliver LPA text or QR SVG into an entitled channel.

Delegated agents

Issue scoped agent credentials with budgets, expiry, IP allowlists and per-order/daily/rolling caps. Budget enforcement is live; human approval above a threshold is planned.

Contract status

The docs mark every endpoint and feature with one of three states. Read these labels literally.

State	Meaning
Current	In the published v1 OpenAPI contract and implemented on the v1 API. Safe to build against for sandbox integration.
Preview	Implemented in the v1 service but not yet in the published OpenAPI contract. The path, scope or response may change. Use only behind a feature flag and a human owner.
Planned	Designed but not available. Do not call it. Do not assume a launch date.

The generated API reference is built from the published OpenAPI document at OpenAPI JSON. The compact, complete reference is raw API Markdown, and the paste-ready agent system prompt is agent-prompt.md. The OpenAPI document covers the current paths; the Markdown reference carries the operational detail and recovery rules.

Contract assumptions

The published OpenAPI document is the canonical machine contract. Agent management, usage, activity, one-call ordering and 15-minute quotes are in the schema. Human approval above a threshold and the MCP server are Planned. If this page and the Markdown reference disagree, the raw API Markdown wins, because it records the rollout state explicitly.

The commerce path

Code
GET  /v1/capabilities          confirm flags
GET  /v1/catalog?currency=USD  choose an available offer
POST /v1/quotes                bind offer, quantity, currency, 15-minute expiry
POST /v1/orders (one-call)     buy items directly with an expected total
POST /v1/orders                pay from the wallet with a stable reference and unique idempotency key
GET  /v1/orders/{purchaseId}   inspect the purchase and child orders
POST /v1/orders/{id}/redeem    reveal up to 20 eSIMs into an entitled channel

A catalogue read does not reserve stock. A quote is not a payment. An order is the first state-changing step, and redemption is the first step that reveals bearer credentials.

What is live, what is not

Capability	v1 status
Local eSIM catalogue	Current
Regional and global catalogue	Current
Quotes (15 minutes, 200 lines / 5,000 units)	Current
One-call wallet order	Current
Quote-based wallet order	Current
Multi-currency wallet	Current
Redemption	Current (POST); GET is planned
Partner webhooks	Current (configured in the dashboard)
Stripe Checkout wallet funding	Current when configured; returns 501 while disabled
Direct card purchase	Not available
Partial fulfilment	Processing and failed statuses are current; partially_fulfilled is planned
Usage, progress and traffic reset	Not available
Physical SIM	Early access only, no ordering endpoint
Agent manifest	Current
Agent identities and agent keys	Current
Quote lookup (`GET /v1/quotes?id=`)	Preview
Agent budget enforcement	Current
Human approval workflow	Planned
MCP server	Planned, not live

No upstream identifiers

Catalogue and order responses deliberately omit upstream store identifiers, product codes, cost and margin data. Do not attempt to infer or publish them. This documentation contains no credentials, customer records or private commercial terms.

Security posture

TLS 1.2 or newer, HSTS and a WAF in front of the API.
HMAC-SHA256 signatures with a five-minute timestamp window and nonce replay protection.
Scoped keys, optional per-key IP allowlists, expiry and immediate revocation.
LPA strings and QR codes are bearer secrets. Never log, cache, email or display them outside the entitled partner system.
No secrets or LPA data in request logs. Redemption reveals are audited.
Report a suspected credential exposure to [email protected].

Start here

Read Environments and Quickstart to create a sandbox key and complete a signed request.
Read Authentication before writing your signing helper.
Read Limits and quotas and Errors before retry logic.
If an autonomous agent will call the API, read Agent identities, Agent payment, Approval flow and Prompt.

Partner support: [email protected]. Security: [email protected]. Dashboard: roamworks.io/partners.

Environments