Provision connectivity from your own product

List countries and whether they are purchasable

The destinations Nesoraa publishes. ⚠️ `availability` describes the fixed plan catalogue (`/v1/plans`) only: a country is `available` when an active plan covers it, `coming_soon` when our plan network reaches it but no plan exists yet, and `unsupported` when no plan can serve it. It is NOT the answer to "can I buy here" — `GET /v1/offers?country=` is, and it may sell a destination this endpoint marks `coming_soon` or `unsupported`.

List purchasable plans

The catalogue as this project may buy it. Prices are what you pay per eSIM. A plan reads the same in both environments; what differs is whether it can be provisioned, which surfaces at purchase.

List the offers this project can buy now, in one scope

The same catalogue the portal shows, priced for this project. Buy one with `POST /v1/esims { "offer_id": … }`. Exactly one scope per request: `country=DZ` (that country's own products), `coverage=regional` or `coverage=global`. Regional and global are never returned for a country request. A scope this environment does not serve is a **422 `coverage_not_available`**, never an empty list. An `id` is bound to this project and environment and expires (`expires_at`). The price is re-resolved at purchase; send `max_price` to bound it. Nesoraa sells connectivity from several upstream networks and presents them as ONE catalogue: a product appears once, whoever supplies it, and no supplier is named in this response. `Nesoraa-Catalogue-Complete: false` means one of those upstreams could not be read for this request, so **products are missing from the list** — it is not a hint about staleness. Treat a partial list as a short cache entry and retry; do not treat a product's absence from a partial list as withdrawal. **Test keys** list simulated products in every scope. Buying one charges nothing and provisions deterministically.

Re-quote one offer

Whether the product is still sold, and its price now — the same resolution a purchase performs. A freshly issued `id` is returned.

List eSIMs

⚠️ Activation credentials are never included in a list. Retrieve a single eSIM to obtain them.

Buy an eSIM

Reserves inventory, debits the wallet and records the intent to provision — in one database transaction — then returns **202**. The upstream network has NOT been contacted when this returns. Poll the eSIM, poll its operation, or wait for `esim.provisioned`. ⚠️ `Idempotency-Key` is required. Retrying with the same key returns the same eSIM — even after the offer expired or while purchases are paused. A key reused for a DIFFERENT purchase is refused with `409 idempotency_key_reused`. Send `offer_id` (from `GET /v1/offers`) or `plan_id` (from `GET /v1/plans`, live only). The price is resolved server-side now; `max_price` refuses the purchase with `409 price_changed` if it is higher. A price in the body is ignored. **Test keys** buy from the simulator: no wallet is touched (`wallet_debited: false`) and no real network is contacted.

Retrieve an eSIM, with activation credentials

The only endpoint that returns activation credentials. `activation` appears once the eSIM is `active` or `suspended`. It is a bearer credential: whoever holds `lpa` can install the profile. Show it to your end user and do not log it.

Retrieve consumption and serving network

How much of the allowance is left, and which network is carrying it. ⚠️ **These figures are polled, not live.** `observed_at` says when we last read them and `stale` says whether we still vouch for the reading. There is no upstream push and no bulk endpoint, so usage is synchronised in the background — an endpoint that called the network on every request would let one integration exhaust the shared budget. Every field is nullable, and that is the honest shape: an eSIM that has never been used has no counters, no activation time and no network. Zero would be a different and false statement. `period.activated_at` is when the allowance clock STARTED — first use, not purchase.

Suspend this eSIM

Stop this eSIM carrying traffic, reversibly. ⚠️ **Accepted, not applied.** The response is `202`: the operation is queued and a worker asks the network moments later. Nothing about the eSIM has changed when this returns — poll the operation for the outcome. Only an `active` eSIM can be suspended. Anything else is a `409` naming the current state, so your code can branch without polling. An `Idempotency-Key` header is required. Retrying with the same key returns the same operation rather than creating a second one.

Resume a suspended eSIM

Return a suspended eSIM to service. ⚠️ **Accepted, not applied** — see suspend. The `202` means queued. Only a `suspended` eSIM can be resumed. A disconnected one cannot: that state is final in Nesoraa and a replacement is a new purchase. An `Idempotency-Key` header is required.

Disconnect this eSIM permanently

⚠️ **Final.** End this eSIM’s service permanently. A disconnected eSIM is never returned to service through this API. The upstream subscriber record survives — this is not the supplier’s irreversible end-of-life state, which Nesoraa cannot reach at all — but Nesoraa treats the eSIM as finished, because re-selling a cancelled subscription would silently restore service a customer ended. Getting service again means buying a new eSIM. ⚠️ **Accepted, not applied.** The `202` means queued; poll the operation. An `Idempotency-Key` header is required.

Retrieve the last known approximate network position

Where the mobile network last placed this eSIM. ⚠️ **This is an approximate position derived from the serving cell** — not GPS, not device-reported, and not consented to by the handset. `position.accuracy_meters` is a median error radius: the eSIM is somewhere within roughly that distance, not at the point given. Do not build a geofence on it without accounting for that radius. **It requires its own scope, `location:read`, and `esims:read` will not work.** Position says where a person is, so a credential issued to read eSIM state does not acquire the ability to track handsets. Grant it deliberately. **Positions are pushed by the network, not polled by us**, on a cadence the network decides. That is why the response carries `age_seconds` rather than a `stale` flag as usage does — we cannot honestly tell you a threshold for data whose arrival we do not control, so you apply the one your use case justifies. A **404 with code `location_not_available`** is a normal answer, and a common one: an eSIM that has never attached to a network, or whose network does not report position, will not have one. It is distinct from `esim_not_found`.

List operations

Retrieve an operation

Retrieve the balance

One balance per billing account, shared by both environments — there is no separate test balance. Read-only: adding funds is a payment, not an API call.

List ledger entries

Append-only, newest first. `reference` is the resource an entry paid for, so a line on a statement joins back to the eSIM it bought.

Send an SMS to this eSIM

Returns **202**. The message is recorded and authorised; the mobile network has not been contacted yet. Poll the message or wait for a webhook. ⚠️ **There is no delivery receipt.** The strongest state a message can reach is `accepted` — the network took it for onward transmission. No part of this API can tell you a handset displayed anything, and `accepted` must not be read as delivery. ⚠️ **You cannot choose an arbitrary sender.** `sender` may name only an identity registered to your project AND approved by an operator, and only if your project permits per-request senders. Otherwise the project default is used. This prevents impersonation and is not configurable by the caller. `text` is limited to 140 printable ASCII characters. Non-Latin scripts and emoji are refused rather than transmitted incorrectly. `Idempotency-Key` is required: an SMS cannot be unsent.

List events

Retrieve an event

Use this to verify a webhook you did not authenticate: if the id in a delivery does not exist under your own credential, the delivery was not ours.

List webhook endpoints

Create a webhook endpoint

Retrieve a webhook endpoint

Update a webhook endpoint

Delete a webhook endpoint

Rotate the signing secret

List delivery attempts

Retrieve a delivery attempt

Replay a delivery

List API keys

Create an API key — the secret is shown once

Revoke an API key