API Response Envelope Format - Braintest API

Every response from the Braintest API returns the same top-level envelope, regardless of endpoint or HTTP status code. This consistency makes it easier to parse responses in your integration code.

Envelope schema

All JSON responses share this structure:

{
  "data": {},
  "successful": true,
  "messages": []
}

Field reference

Field	Type	Description
`data`	object, array, or null	The actual payload for the request. Contains endpoint-specific data on success. Set to `null` on error.
`successful`	boolean	`true` when the request succeeded and `data` is valid. `false` when an error occurred.
`messages`	array of strings	Empty on success. Contains one or more human-readable error descriptions on failure.

Success example

{
  "data": {
    "token": "rec_abc123",
    "test_title": "DASS-21",
    "status": 2,
    "auth_required": true
  },
  "successful": true,
  "messages": []
}

Failure example

{
  "data": null,
  "successful": false,
  "messages": [
    "Authentication failed. The provided mobile number is invalid.",
    "Name must contain only Persian letters and be at most 50 characters."
  ]
}

Error handling notes

The API does not use a separate message or devMessage field. All error text lives in the messages array.
Multiple validation errors can appear in a single response. Check every entry in messages before showing feedback to the user.
HTTP status codes still matter: 401 and 403 indicate authentication issues, 404 indicates a missing resource, and 422 indicates validation errors. Always inspect successful alongside the status code.

Because data is null on error, your parser should check successful before attempting to read fields from data.