API

Everything the application does is available over a REST API: browse the catalog, price a route, buy a number and follow the order to its conclusion.

This build issues no credentials

The endpoints below are the declared contract. This is an interface demonstration, so no key is issued and no request is served.

Authentication

Requests carry a scoped API key in an Authorization: Bearer header. Keys are scoped at creation — a key that only reads the catalog cannot place an order — and are revocable individually without disturbing any other integration.

The secret half of a key is shown exactly once, when it is created, and is never retrievable afterwards. If it is lost, it is rotated rather than recovered.

Endpoints

Catalog

GET/api/v1/catalog/countriesCacheable
Every country in the canonical catalog, with its dialling prefix.
GET/api/v1/catalog/servicesCacheable
Service categories the platform sells against.
GET/api/v1/catalog/availabilityCacheable
Availability band per country and service. A band, never a count.

Commerce

POST/api/v1/quotes
Price a route before committing. Reads nothing and moves nothing.
POST/api/v1/ordersIdempotent
Create an order. Requires an Idempotency-Key.
GET/api/v1/orders
List the orders you own, newest first.
GET/api/v1/orders/{orderId}
One order and its current state.
GET/api/v1/orders/{orderId}/events
The order timeline, including the message once it arrives.
POST/api/v1/orders/{orderId}/cancel
Release the number early and return the hold.

Buying a number

Order creation requires an Idempotency-Key. Replaying the same key returns the original order rather than creating a second one, so a retry after a network timeout can never double-charge.

Request

POST /api/v1/orders HTTP/1.1
Host: api.example
Authorization: Bearer frs_live_...
Idempotency-Key: 7c9e6679-7425-40de-944b-e07fc1f90ae7
Content-Type: application/json

{
  "countryIso2": "DE",
  "serviceSlug": "marketplace"
}

Response

HTTP/1.1 201 Created
Content-Type: application/json
Cache-Control: private, no-store

{
  "id": "ord_01J9T4Z8QF6M2XA7C3KDV0RB",
  "reference": "FR-7QK2M4",
  "state": "PROVISIONING",
  "countryIso2": "DE",
  "serviceSlug": "marketplace",
  "msisdn": null,
  "price": { "amount": "0.94", "currency": "USD" },
  "expiresAt": "2026-09-01T09:27:00.000Z"
}

What the contract guarantees

Availability is a band

The catalog returns one of high, medium, low, none or unknown — never a stock count. unknown means we have not confirmed the route recently and is not orderable.

No supplier detail, ever

Responses contain no supplier identity, no upstream identifier and no upstream error code. Your integration depends on our contract, so changing how we source a route never breaks it.

Money is a decimal string

Amounts are transmitted as an exact decimal string with an ISO-4217 code, never as a floating-point number. Parse them as decimals.

Errors are typed

Failures return a structured problem document with a stable machine-readable type and a correlation reference you can quote to support.

Create an account See pricing