Envelope
Every endpoint on this API answers in the same outer shape — an "envelope." A
success wraps your result inside data; an error wraps the details inside error.
Because the shape never changes, once your code can read one response it can read
them all. This page covers that shape, the status codes, and a few rules every
response follows.
Success
{ "data": … }
data holds the actual result — an object or an array, depending on the endpoint.
It is wrapped inside data (rather than handed back on its own) so that if we need
to add more alongside it later — things like paging markers or rate-limit info — we
can add a new field next to data without breaking your code. A bare array would
leave nowhere to put those.
Error
{ "error": { "type": "insufficient_scope", "message": "…", "scope": "sms:send" } }
Look at error.type to decide what to do. See Errors for the full
list.
Status codes
| Status | When |
|---|---|
200 | Success with a body |
201 | Something was created. If the new thing has its own URL, a Location response header gives you that address. |
204 | Success with no body — deletes |
4xx | Rejected. Nothing was created and nothing was charged. |
5xx | Failed on our side. Nothing was charged — which is what makes a retry safe. |
Arrays are never null
An empty list is always [], never null. This holds for every list field on
every response, including nested ones like userIds and skipped. Getting a
null where you expected a list is a common cause of crashes in code, so this API
never sends one.
Note that [] can still mean something: an empty userIds on an SMS line means
everyone, not nobody.
Unknown fields are rejected
If your request body contains a field this API does not recognize, the whole
request is rejected with a 400:
{ "error": { "type": "invalid_request", "message": "malformed request body: json: unknown field \"mesage\"" } }
Why reject it instead of ignoring it? Say you meant to send message but typed
mesage. If the API quietly dropped the unrecognized mesage, the request would
still come back as a success — but without the text you intended, since the real
message field was never set. You would be left wondering why nothing happened,
even though the server accepted the request. Rejecting it instead — and naming the
bad field in the error — catches the typo right away. This is deliberate, and it
applies to every write (any request that changes data).
No customerId anywhere
Your credential already tells the API which account you are working in. Nothing sends an account id back to you, and nothing accepts one — so there is no such field to get wrong, and no way to accidentally point a request at someone else's data.