Skip to main content

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​

StatusWhen
200Success with a body
201Something was created. If the new thing has its own URL, a Location response header gives you that address.
204Success with no body — deletes
4xxRejected. Nothing was created and nothing was charged.
5xxFailed 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.