Record and Roadmap Status Code Reference

Braintest uses numeric status codes to communicate the lifecycle state of records (standalone tests) and roadmaps (multi-test packages). This page lists every code, explains what it means, and tells you what action to take next.

Record status codes

Records represent individual psychological test instances such as MCMI, NEO, DASS-21, or PHQ-9.

Status	Name	Meaning	Next step
0	VIP wait	The record is reserved and waiting for VIP processing.	No action needed. The platform will update the status automatically.
1	Finished	The test is complete and results are available.	Retrieve results via `/record/{token}/result/json/` or `/result/html/`.
2	Ready	The record is active and can be started.	Authenticate the profile if `auth_required: true`, then fetch questions and submit answers.

Roadmap status codes

Roadmaps are multi-test packages that combine several records into a single AI-powered analysis.

Status	Name	Meaning	Next step
0	VIP wait	The roadmap is reserved and waiting for VIP processing.	No action needed. The platform will update the status automatically.
1	Finished with AI	All tests are complete and the AI analysis is ready.	Retrieve results via `/roadmap/{token}/result/json/` or `/result/html/`.
2	Ready	The roadmap is active and can be started.	Authenticate profiles, complete each test record, then request AI generation.
3	In progress	At least one test record has been started but the roadmap is not yet complete.	Continue completing the remaining test records.
4	AI processing	All tests are finished and the AI analysis is being generated.	Poll `/roadmap/{token}/generate/status/` until the state is `completed` or `failed`.

Gender codes

Gender appears in three places across the API. Use the values consistently.

Field	Type	Values	Notes
`is_male`	boolean	`true` or `false`	Required in profile objects. `true` = male, `false` = female.
Role `gender`	string	`"male"` or `"female"`	Specifies the expected gender for a roadmap role.
`gender_permission`	string or null	`"male"`, `"female"`, or `null`	Test-level restriction. `null` means no restriction.

When gender_permission is set on a record, the participant’s profile gender must match the permission value or the API returns a 403 error.

Pagination

List endpoints return paginated results with 30 items per page.

Parameter	Type	Description
`page`	integer	The page number to fetch. Defaults to 1.
`next`	string (URL)	URL for the next page, or `null` if there is none.
`previous`	string (URL)	URL for the previous page, or `null` if there is none.

Example paginated response snippet

{
  "data": {
    "count": 87,
    "next": "https://braintest.ir/api/v2/record/?page=2",
    "previous": null,
    "results": [
      { "token": "abc123", "status": 2, "auth_required": true }
    ]
  },
  "successful": true,
  "messages": []
}

To navigate pages, pass ?page=N as a query parameter:

curl -X GET "https://braintest.ir/api/v2/record/?page=3" \
  -H "API-KEY: YOUR_API_KEY"

Run a standalone test: step-by-step guide for working with records
Run a cognitive roadmap: step-by-step guide for working with roadmaps
API error reference: how to handle errors when status checks fail

Get Started

Core Concepts

Guides

Reference

Record and Roadmap Status Code Reference

Record status codes

Roadmap status codes

Gender codes

​Record status codes

​Roadmap status codes

​Gender codes

​Pagination

​Related pages

Record status codes

Roadmap status codes

Gender codes

Pagination

Related pages