Skip to main content
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 project can have many accounts, one per customer is the recommended pattern. Most endpoints take an account ID in the path, for example:

​
Authentication

Every request requires an API key. Pass it as a bearer token:
See Authentication for key types 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 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

Surge publishes a machine-readable OpenAPI 3.1 spec that powers this site’s endpoint pages.