Base URLs
Use staging for development and testing. Messages sent from staging are still
charged, so treat test sends with the same care as production ones.
Getting started
1
Create an API key
An Owner or Admin of your organization creates a key in Settings → API
keys, with the scopes the integration needs. The key is shown once, so store
it in your secret manager. See
Authentication with API keys.
2
Send it on every request
Send
Authorization: Bearer hk_live_…. The key identifies your organization,
so no other header is needed.3
Send a test message
Call
POST /api/v1/sms/single with a recipient, a sender ID and your message.
Confirm it appears in SMS Management in the web application, with the API
channel.Conventions
API keys
An organization API key on every request.
Response format
Most responses use a standard envelope.
Errors
Status codes and error handling.
Scope of this reference
This reference documents the operations available to customer integrations. Three groups of operations are intentionally excluded:
If an operation you require is not documented here, contact your account manager
rather than calling an undocumented endpoint, as undocumented operations are not
covered by any compatibility commitment.
Before you build
Three behaviours materially affect integrations and are worth confirming your client handles:- An API key reaches only the operations of its scopes. Every other operation
in this reference answers
403to a key. Operations that accept a key show the scope they need on their page. See Scopes. - Not every response uses the standard envelope. A small number of operations return their payload directly. See Response format.
- Success is represented two ways in acknowledgement payloads, depending on the operation. Check each operation’s schema rather than generalising from another.