> ## Documentation Index
> Fetch the complete documentation index at: https://docs.braintest.ir/llms.txt
> Use this file to discover all available pages before exploring further.

# Test Records: Standalone Psychological Tests

> Learn what a test record is, how it moves through its lifecycle, and how status codes and auth_required guide your integration flow.

A record is a single instance of a psychological test assigned to a participant. Braintest supports validated instruments such as MCMI, NEO, DASS-21, and PHQ-9. Each record has a unique token, a lifecycle status, and an authentication requirement that tells your integration what step to perform next.

## Record lifecycle

A record moves through the following states from creation to completion:

1. **VIP wait (`status: 0`)**: The record exists but is not yet available. The organizer must complete a VIP or billing action before the record becomes active.
2. **Ready (`status: 2`, `auth_required: true`)**: The record is active and waiting for participant authentication. This is the state you look for when listing records.
3. **Authenticated (`status: 2`, `auth_required: false`)**: The participant profile is linked. The record is ready for questions to be fetched and answers submitted. When the organizer has `tests_auth_required: true` (default), this state is reached only after a two-step SMS flow (`POST /record/{token}/auth/` then `PUT /record/{token}/auth/verify/`).
4. **Finished (`status: 1`, `is_finished: true`)**: Answers have been submitted and scored. Results are available via the result endpoints.

## Status codes

| Code | Name     | Meaning                                                  |
| ---- | -------- | -------------------------------------------------------- |
| 0    | VIP wait | Waiting for organizer VIP or billing action.             |
| 1    | Finished | Test completed. Results are ready.                       |
| 2    | Ready    | Record is active and awaiting authentication or answers. |

## Standalone vs roadmap records

Records can exist in two contexts:

* **Standalone records**: Created directly for a single test. Authenticate them with `POST /record/{token}/auth/`. The `role` field is `null`.
* **Roadmap records**: Belong to a [cognitive roadmap](/concepts/roadmaps). Authenticate them through `POST /roadmap/{token}/auth/` instead. Calling `/record/{token}/auth/` on a roadmap record returns **409**. The `role` field contains the role ID from the roadmap definition.

<Warning>
  Always check whether a record belongs to a roadmap before choosing the authentication endpoint. Roadmap records have a non-null `role` field.
</Warning>

## Key fields

| Field                 | Type                      | Description                                                                                                                                                                              |
| --------------------- | ------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `token`               | string (UUID)             | Unique identifier for this record instance. Used in all record endpoints.                                                                                                                |
| `test_id`             | string                    | ID of the underlying psychological test (for example, `MCMI`, `NEO`, `DASS21`).                                                                                                          |
| `test_title`          | string                    | Human-readable test name.                                                                                                                                                                |
| `status`              | integer                   | Lifecycle state: `0` (VIP wait), `1` (finished), `2` (ready).                                                                                                                            |
| `auth_required`       | boolean                   | `true` when no profile is linked yet. Becomes `false` after authentication completes.                                                                                                    |
| `tests_auth_required` | boolean                   | Organizer policy for the auth flow. `true` (default) requires SMS verification via `POST /auth/` then `PUT /auth/verify/`. `false` completes authentication instantly on the first call. |
| `is_finished`         | boolean                   | `true` when answers have been submitted and scoring is complete.                                                                                                                         |
| `role`                | integer or null           | Role ID when the record belongs to a roadmap. `null` for standalone records.                                                                                                             |
| `profile`             | object or null            | The linked participant profile, if authentication has already occurred.                                                                                                                  |
| `submit_on`           | string (ISO 8601) or null | Timestamp when answers were submitted. `null` until finished.                                                                                                                            |
| `create`              | string (ISO 8601)         | Timestamp when the record was created.                                                                                                                                                   |

The record detail response (`GET /record/{token}/`) also includes a nested `test` object with the test's `id`, `title`, `questions_count`, `doing_time_minutes`, `min_age`, `max_age`, `gender_permission`, and `categories`.

## Integration checklist for records

When listing records, filter for `status: 2` and `auth_required: true` to find tests that are ready for a new participant. After authentication, the record remains `status: 2` but `auth_required` becomes `false`, signaling that you can proceed to fetch questions and submit answers.