Surge home page
SupportDashboard
Surge

Introduction

Surge provides a REST API for sending and receiving SMS and MMS, managing voice calls, registering messaging campaigns with carriers, and provisioning phone numbers. All requests go to https://api.surge.app and all responses are JSON.

The API is organized around accounts. Your platform can have many accounts, one per customer is the recommended pattern. Most endpoints take an account ID in the path, for example:

POST /accounts/acct_01jrzhe8d9enptypyx360pcmxj/messages
GET  /accounts/acct_01jrzhe8d9enptypyx360pcmxj/phone_numbers

A handful of endpoints don't require an account ID (verifications, attachments, and a few others). Those paths look like /verifications, /attachments/{attachment_id}.

Authentication

Every request requires an API key. Pass it as a bearer token:

Authorization: Bearer sk_live_your_api_key_here

See Authentication for key types, Basic auth support, and error codes.

Format

  • Request bodies must be JSON with Content-Type: application/json
  • Timestamps are ISO 8601 in UTC (2024-10-21T23:29:43Z)
  • IDs use TypeID, prefixed UUIDs like msg_01jav968..., acct_01jrz...
  • Phone numbers are E.164 with a leading +, for example +18015551234

Errors

All errors return a JSON body with a type slug and a human-readable message. Validation errors include a detail map with per-field errors. See Error Reference for the full list.

OpenAPI spec

A machine-readable OpenAPI 3.1 spec is available at GET https://api.surge.app/openapi.json. The interactive ReDoc UI is at GET https://api.surge.app/docs.