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

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

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.