/v1/phone/...) and per-user (/v1/users/:user_id/phone/...). They are gated by the phone primitive in the subject’s AccountKit.
Endpoints
| Method & Path | Description |
|---|---|
POST /v1/phone/provision | Buy a US number + register the carrier campaign |
GET /v1/phone | List phone numbers (optional ?agent=<id>) |
GET /v1/phone/status | The account → campaign → numbers pipeline |
GET /v1/phone/:id | Get a single phone number |
DELETE /v1/phone/:id | Release the number back to the provider (stops billing) |
POST /v1/phone/:id/sms | Send an outbound SMS (carrier-gated until campaign approval) |
GET /v1/phone/:id/messages | List received SMS (newest first, cursor-paginated) |
GET /v1/phone/messages/:id | Read a single received SMS |
GET /v1/phone/:id/campaign | The carrier-registration campaign for a number |
GET /v1/phone/:id/assignments | List agents connected to a number |
POST /v1/phone/:id/assign | Connect an agent (permissions: send_sms, receive_sms) |
DELETE /v1/phone/:id/assign/:agentId | Disconnect an agent |
Capabilities object
Every phone row carries acapabilities object reflecting carrier-side state:
sms_outbound flips to true automatically when the carrier campaign is approved.
Billing & gating
Provisioning a number charges a one-time carrier registration (first number only) plus the first month’s rental, and is approval-gated by default. Monthly rental recurs per number until released (DELETE /v1/phone/:id). Outbound SMS is billed per 160-char segment and is not approval-gated. Inbound SMS is free. See the guide for credit amounts.
Inbound webhook
Surge delivers inbound events (message.received, campaign.approved, …) to POST /webhooks/surge, verified with the Surge-Signature HMAC-SHA256 header. Received texts are stored and also fan out to your per-user sms.received webhook subscriptions.