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:
- 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.
- 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.
- 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).
- Finished (status 1, is_finished: true): Answers have been submitted and scored. Results are available via the result endpoints.
Status codes
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. You must authenticate them through
/roadmap/{token}/auth/ instead. Calling /record/{token}/auth/ on a roadmap record will fail.
Always check whether a record belongs to a roadmap before choosing the authentication endpoint. Roadmap records include a roadmap field in their detail response.
Key fields
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. 
