Run a Standalone Psychological Test

This guide walks you through administering a standalone psychological test (a single record) using the Braintest API. You will list available records, authenticate a participant profile using either SMS verification or the instant path (depending on your organizer setting), fetch questions, submit answers, and retrieve the final result.

Prerequisites

A valid API key from the organizer panel, sent in the API-KEY header
At least one record with status: 2 (ready) available in your account

Do not call /record/{token}/auth/ for records that belong to a cognitive roadmap. Roadmap records must be authenticated through the roadmap endpoint instead. See the Cognitive Roadmap guide for details.

Two authentication paths

Every record payload includes an organizer-level flag named tests_auth_required that controls how authentication works:

`tests_auth_required`	Behavior
`true` (default)	`POST /record/{token}/auth/` sends an SMS code to the participant’s mobile and returns a `draft_token`. Finish the flow with `PUT /record/{token}/auth/verify/`.
`false`	`POST /record/{token}/auth/` authenticates the profile immediately and returns it. Skip the verify step.

Read tests_auth_required from the record before choosing the next step. Your integration should handle both paths.

List your records

Fetch your available records. Filter for unfinished, ready records so you only see tests that can be started.

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

Look for a record with status: 2 (ready) and auth_required: true. The response includes the token you need for the next steps, plus tests_auth_required which tells you whether SMS verification is on.

Inspect the record

Retrieve the full record details before starting.

curl -X GET "https://braintest.ir/api/v2/record/{token}/" \
  -H "API-KEY: YOUR_API_KEY"

Key fields to review:

status: must be 2 (ready)
auth_required: must be true before you can authenticate
tests_auth_required: selects the auth path (see the decision matrix above)
test.questions_count: total number of questions
test.doing_time_minutes: recommended time limit
test.gender_permission: gender restrictions, if any

Start authentication

Post the participant profile to the auth endpoint. The body is the same regardless of tests_auth_required.

curl -X POST "https://braintest.ir/api/v2/record/{token}/auth/" \
  -H "API-KEY: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "علی احمدی",
    "mobile": "09123456789",
    "birth": "1990-05-15",
    "is_male": true,
    "external_id": 12345
  }'

Profile fields

Field	Type	Required	Description
`name`	string	Yes	Participant name, max 50 characters, Persian letters only
`mobile`	string	Yes	Iranian mobile number, 11 digits starting with `09`
`birth`	string	Yes	Date of birth in ISO 8601 format (`YYYY-MM-DD`)
`is_male`	boolean	Yes	`true` for male, `false` for female
`external_id`	integer	No	Partner-assigned unique identifier per organizer

The response echoes tests_auth_required. Branch on it to decide the next step.SMS path (tests_auth_required: true)

{
  "data": {
    "tests_auth_required": true,
    "draft_token": "f47ac10b-58cc-4372-a567-0e02b2c3d479"
  },
  "successful": true,
  "messages": []
}

An SMS code is sent to the participant’s mobile. Keep the draft_token for the verify step. It expires after 5 minutes.Instant path (tests_auth_required: false)

{
  "data": {
    "tests_auth_required": false,
    "profile": {
      "token": "f1e2d3c4-b5a6-7890-abcd-ef0987654321",
      "external_id": 12345,
      "case_number": "ORG-00001",
      "mobile": "09123456789",
      "name": "علی احمدی",
      "age": 34,
      "birth": "1990-05-15",
      "is_male": true
    }
  },
  "successful": true,
  "messages": []
}

The profile is created and linked to the record immediately. Skip the next step and jump to fetching questions.

Verify the SMS code (SMS path only)

Ask the participant for the code they received, then send it with the draft_token to complete authentication.

curl -X PUT "https://braintest.ir/api/v2/record/{token}/auth/verify/" \
  -H "API-KEY: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "draft_token": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
    "vcode": "58291"
  }'

Success response

{
  "data": {
    "tests_auth_required": true,
    "profile": {
      "token": "f1e2d3c4-b5a6-7890-abcd-ef0987654321",
      "external_id": 12345,
      "case_number": "ORG-00001",
      "mobile": "09123456789",
      "name": "علی احمدی",
      "age": 34,
      "birth": "1990-05-15",
      "is_male": true
    }
  },
  "successful": true,
  "messages": []
}

Common errors

Message	Fix
`Verification draft token is invalid or expired.`	The draft token is unknown or older than 5 minutes. Restart from `POST /record/{token}/auth/`.
`Verification code is invalid.`	Ask the participant to re-enter the code.
`SMS verification is not required for this organizer account.`	The setting is disabled. Use the profile returned by the auth call instead.

Skip this step entirely when tests_auth_required is false.

Fetch the questions

Retrieve the question set for the authenticated participant.

curl -X GET "https://braintest.ir/api/v2/record/{token}/questions/" \
  -H "API-KEY: YOUR_API_KEY"

The API supports two response formats:

JSON (default): structured question objects with IDs, text, and options
HTML: pre-rendered question markup for direct embedding in a web view

Request HTML explicitly by adding ?format=html to the URL if your client renders a web interface.

Submit answers

Send the participant’s responses back. The record array maps each question to its selected answer.

curl -X POST "https://braintest.ir/api/v2/record/{token}/" \
  -H "API-KEY: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "record": [
      { "question_id": 1, "answer_id": 3 },
      { "question_id": 2, "answer_id": 1 },
      { "question_id": 3, "answer_id": 4 }
    ],
    "doing_duration_in_minutes": 12
  }'

record: array of objects, each with question_id and answer_id
doing_duration_in_minutes: integer, time the participant spent answering

After submission, the record status changes to 1 (finished) and results become available.

Retrieve the result

Once is_finished is true, fetch the test results in your preferred format.

curl -X GET "https://braintest.ir/api/v2/record/{token}/result/json/" \
  -H "API-KEY: YOUR_API_KEY"

curl -X GET "https://braintest.ir/api/v2/record/{token}/result/html/" \
  -H "API-KEY: YOUR_API_KEY"

The JSON response contains structured scores, interpretations, and metadata. The HTML response is a ready-to-render report page.

Flow summary

SMS enabled (tests_auth_required: true, default)

GET  /record/                          → read tests_auth_required
POST /record/{token}/auth/             → draft_token (SMS sent)
PUT  /record/{token}/auth/verify/      → profile
GET  /record/{token}/questions/
POST /record/{token}/
GET  /record/{token}/result/json|html/

SMS disabled (tests_auth_required: false)

POST /record/{token}/auth/             → profile (instant)
GET  /record/{token}/questions/
POST /record/{token}/
GET  /record/{token}/result/json|html/

What to do next

Learn how to run multi-test cognitive roadmaps with AI-powered analysis
Review the status code reference to understand record lifecycle states
Check the error reference for common issues and how to resolve them

Get Started

Core Concepts

Guides

Reference

Run a Standalone Psychological Test

Two authentication paths

Flow summary

What to do next

​Two authentication paths

​Flow summary

​What to do next

Two authentication paths

Flow summary

What to do next