Requests and responses

Every response uses the same envelope, { data, description }, whatever the resource. Send and receive JSON.

Requests and responses are JSON. Every successful response uses the same envelope, whatever the resource.

{
  "data": { "...": "the resource, or a list of them" },
  "description": "Financial account created successfully"
}

data carries the result. description is a human-readable summary of what happened, for logs and for operators, not for branching on.

Conventions that hold everywhere

Money is an object with a string amount and a currency code. See Money.
References, phone numbers and identifiers serialise as bare strings.
Timestamps are ISO-8601.
Enumerated values are upper case with underscores, for example ITEM_NOT_DELIVERED.
Live responses omit nulls, so a real payload is often smaller than the documented shape.

New fields and new endpoints ship without notice. Ignore fields you don’t recognise.
Enumerations grow. Treat an unknown value as unhandled, not as an error.
Breaking changes are announced in the changelog ahead of time.