Core Concepts

Every endpoint in the Partner API follows the same handful of patterns. Learning them once here means you won’t have to re-learn them per-endpoint in the reference.

Entities and terminology

Term	Meaning
SIM	A physical or eSIM identified by its ICCID. The unit everything else attaches to.
Subscription	The data/voice/SMS plan currently active on a SIM, with a status and billing cycle.
Plan (product)	A catalog item you can purchase and attach to a SIM as a subscription — identified by `productId`/`productName`.
SIM product	A catalog item for the physical or eSIM unit itself (separate from the data plan) — what you purchase to provision a new SIM.
User	An end user on your account that SIMs and devices are assigned to. Identified by email — there is no separate user ID exposed today. Don’t key persistent storage off email: it’s a mutable lookup value, not a stable primary key.
Team member	An admin on your account (a different resource from User) — someone who manages the account itself, with a role tier (`Admin`, `RW Admin`, `RO Admin`, `Standard Admin`). Identified by email.
Device	A phone/tablet in your device catalog, assignable to a User. Identified by its IMEI.
Order	A record of a purchase (a plan purchase, eSIM purchase, port-in, and so on).
Transaction (financial)	A charge, refund or other financial movement tied to an order — not the same thing as the async `transactionId` below, despite the shared name.
Invoice	A billing document for a period, with line items and a usage summary.
Port-in	A request to bring an existing phone number from another carrier onto a Spenza SIM.
Device Group / SIM Group / User Group	A named group (with an optional spend limit and data quota) that devices, SIMs, or users can be moved into and out of.
Webhook registration	Your configuration telling Spenza where and how to deliver operator SMS/voice events.

Two different things are both called “transaction.” GET /api/v1.1/transactions is your account’s financial transaction ledger — charges, refunds, and their status. The transactionId returned by an async operation (POST /api/v1.1/esim, POST /api/v3/plans/purchase, and others) is unrelated — it’s a handle for polling that one operation’s progress via GET /api/v3/transactions/{transactionId}. They happen to share a name; nothing else connects them.

How resources relate

User (email)
  └─ assigned ─▶ SIM (iccid)
                   ├─ has ─▶ Subscription (plan/product)
                   └─ has ─▶ Usage (current billing cycle)

User (email)
  └─ assigned ─▶ Device

SIM / Device / User
  └─ organized into ─▶ SIM Group / Device Group / User Group

Order
  └─ produces ─▶ Transaction(s)   (financial ledger entries)

Invoice
  └─ summarizes ─▶ a billing period's Orders/Subscriptions/Usage

A SIM is the anchor: it’s assigned to a user, has a subscription, accrues usage against that subscription’s billing cycle, and its purchase/port-in/plan-change events show up as orders and financial transactions.

The success/error envelope

Every response is JSON with a success boolean at the top:

{
  "success": true,
  "data": { "...": "..." },
  "meta": { "page": 1, "pageSize": 25, "total": 240, "totalPages": 10 }
}

data is an object for a single-resource response, or an array for a list.
meta is present only on list responses, and carries pagination totals.

{
  "success": false,
  "error": { "code": "SIM_NOT_FOUND", "message": "No SIM found.", "details": {} }
}

On failure, success is false and error.code is a stable, machine-readable string from a fixed taxonomy — see Errors.

Two documented exceptions. GET /api/v1.1/invoices/{id}/pdf returns a raw 302 redirect on success, not this envelope. POST /api/v3/port-in isn’t on this envelope at all — see Environments & Versioning.

Pagination

List endpoints accept:

Parameter	Default	Notes
`page`	`1`	1-indexed — the first page is `1`, not `0`.
`pageSize`	`25`	Max `100`.

The response’s meta echoes page/pageSize back and adds total (matching records) and totalPages.

Field conventions

Fields are camelCase throughout (the one exception is POST /api/v1.1/auth/token’s response, which is deliberately snake_case to match OAuth2 conventions), with one spelling per concept across every endpoint that returns it — iccid, operator, productName, phoneNumber mean the same thing everywhere they appear.

Idempotency

Many write endpoints (SIM assignment, plan/eSIM purchase, subscription cancel, group membership changes, webhook registration and more — check each operation’s page) accept an optional Idempotency-Key request header:

Omit it — the call behaves exactly as it always has; nothing changes.
Send it, and retry with the same key + same request body — the original response is replayed verbatim, with an Idempotency-Replayed: true response header. No side effect runs twice.
Reuse the key with a different body, or against a different route — 409 IDEMPOTENCY_KEY_REUSED.
Retry while the original call is still in flight — 409 CONFLICT. Wait for the first call to finish and reuse the same key.

There’s no fixed format required for the key — any string unique to that logical request (a UUID is the common choice) works.

Async operations

A handful of endpoints don’t return the finished resource directly — they return 202 (or, for POST /api/v1.1/top-up, 201) with a transactionId and a statusEndpoint:

{
  "success": true,
  "data": {
    "transactionId": "64f1a2b3c4d5e6f7a8b9c0d1",
    "statusEndpoint": "/api/v3/transactions/64f1a2b3c4d5e6f7a8b9c0d1"
  }
}

Poll statusEndpoint — no authentication required, the transactionId itself is the credential — until status leaves the in-flight states:

PENDING → PROCESSING → COMPLETED | FAILED | SCHEDULED

data.result on a COMPLETED transaction holds the operation-specific payload (for example, the provisioned iccid/qrCode from an eSIM). A FAILED transaction is still a 200 from the status endpoint — check data.status and data.errorCode, not the HTTP status of the poll itself. See Guides → Handling async operations for a full polling example. Endpoints that always return this shape: POST /api/v1.1/esim, POST /api/v3/plans/purchase, POST /api/v1.1/top-up, POST /api/v3/port-in. Every other endpoint blocks and returns its finished resource directly.

Sandbox vs. production

No sandbox yet. There’s a single base URL for the Partner API today — https://api.spenza.com (see Environments & Versioning). Every request you make against it acts on real account data. A sandbox is planned, but until it ships, confirm with your Spenza account representative before assuming any environment other than production exists for your account.

Next steps

Authentication — the token exchange in full detail.
Quickstart — put these concepts together into a working integration.
API Reference (sidebar) — every endpoint that implements this contract.

Overview

Build

Reference

Help

API Reference

Entities and terminology

How resources relate

The success/error envelope

Field conventions

Idempotency

Async operations

Sandbox vs. production

Next steps

​Entities and terminology

​How resources relate

​The success/error envelope

​Pagination

​Field conventions

​Idempotency

​Async operations

​Sandbox vs. production

​Next steps

Entities and terminology

How resources relate

The success/error envelope

Pagination

Field conventions

Idempotency

Async operations

Sandbox vs. production

Next steps