> ## 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. **Created (status 0, VIP wait)**: The record exists but is not yet available for the participant. This is typically a temporary state for premium or queued tests.
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 (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`, this state is reached only after a two-step SMS flow (auth then 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 | Record exists but is not yet active.                     |
| 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 via the API or organizer panel for a single test. You authenticate them with `/record/{token}/auth/`.
* **Roadmap records**: Belong to a [cognitive roadmap](/concepts/roadmaps). You must authenticate them through `/roadmap/{token}/auth/` instead. Calling `/record/{token}/auth/` on a roadmap record will fail.

<Warning>
  Always check whether a record belongs to a roadmap before choosing the authentication endpoint. Roadmap records include a `roadmap` field in their detail response.
</Warning>

## Key fields

| Field                 | Type              | Description                                                                                                                                                                              |
| --------------------- | ----------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `token`               | string            | Unique identifier for this record instance. Used in all record endpoints.                                                                                                                |
| `test_id`             | integer           | ID of the underlying psychological test (e.g., DASS-21).                                                                                                                                 |
| `test_title`          | string            | Human-readable test name.                                                                                                                                                                |
| `status`              | integer           | Lifecycle state: 0 (VIP wait), 1 (finished), 2 (ready).                                                                                                                                  |
| `auth_required`       | boolean           | `true` if the participant must be authenticated before fetching questions.                                                                                                               |
| `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` if answers have been submitted and the test is complete.                                                                                                                          |
| `role`                | object            | The participant role assigned to this record (e.g., "Participant", "Partner 1"). Relevant for multi-person roadmaps.                                                                     |
| `profile`             | object            | The linked participant profile, if authentication has already occurred.                                                                                                                  |
| `submit_on`           | string (ISO 8601) | Timestamp when answers were submitted. Null until finished.                                                                                                                              |

## 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.