CarrierLayer
API overviewRequest access

Developers · Preview

An API that behaves like software, not a carrier.

Plain REST and JSON. Idempotent writes. One signed webhook when the work is done. Full reference docs and keys are shared with partners during onboarding.

Request API access →

How it works

Accepted now. Confirmed when it's real.

Carriers don't finish work instantly, so neither do we pretend to. A change returns 202 Accepted immediately, and a webhook follows when the carrier confirms it.

  • Idempotency keys on every writeSend the same request twice and get the same result — never two lines.
  • One change per line at a timeA second change while one is pending is refused with a clear error.
  • Server-side keys onlySecret keys per partner, scoped to your own lines. Never ship them to a browser.
requestAPI preview
POST /v1/lines/ln_7Hq2kR/suspend
Idempotency-Key: invoice_5512_overdue

// 202 Accepted — the carrier is working on it
{
  "request": "req_91Fa",
  "status": "pending"
}

Webhooks

One event per change. Exactly what happened.

Carrier systems repeat themselves and sometimes contradict themselves. We deduplicate, reconcile and send you one signed event with a clear outcome.

  • Signed with your secretVerify the signature and timestamp before acting on any event.
  • Three honest outcomessucceeded, failed, or needs_review when a carrier's answer can't be trusted as-is.
webhook
# Every event is signed. Verify before you trust it.
CarrierLayer-Signature: t=1792200000,v1=5f2b…c9e1

{
  "id": "evt_3kV9",
  "type": "line.suspended",
  "request": "req_91Fa",
  "line": "ln_7Hq2kR",
  "outcome": "succeeded"
}

Endpoints

The API at a glance.

The core resources in the developer preview. Partners receive the full reference, including request and response schemas, during onboarding.

EndpointWhat it does
POST/v1/linesActivate a line — eSIM or physical SIM
GET/v1/linesList lines, filtered by status, plan or customer
GET/v1/lines/{id}A line's current state and network
POST/v1/lines/{id}/suspendSuspend service
POST/v1/lines/{id}/restoreRestore a suspended line
POST/v1/lines/{id}/planChange plan
POST/v1/lines/{id}/networkSet the primary network (multi-network SIMs)
POST/v1/lines/{id}/swapSwap SIM or device
POST/v1/lines/{id}/smsSend an SMS to the device
GET/v1/lines/{id}/esimeSIM QR code and install status
GET/v1/usageData usage by line and billing cycle