Skip to main content
The phone primitive provisions US phone numbers and sends/receives SMS via Surge. Numbers are carrier-registered (10DLC) automatically; inbound SMS works immediately while outbound SMS unlocks when the campaign is approved. Brands register at the standard tier (LLC formation + EIN) or the sole_proprietor tier (passed KYC, no LLC/EIN — verified via SMS OTP, lower carrier throughput). All endpoints are available company-level (/v1/phone/...) and per-user (/v1/users/:user_id/phone/...). They are gated by the phone primitive in the subject’s AccountKit.

Endpoints

Capabilities object

Every phone row carries a capabilities 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. Receiving 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.