Get Started with the Braintest API

This guide walks you through your first complete standalone test flow. By the end, you will have verified your connection, authenticated a participant, submitted answers, and retrieved a result from the Braintest API.

Prerequisites

A Braintest partner account with API access
Your API key from the organizer panel
curl or any HTTP client

Authentication paths

Every record includes an organizer setting called tests_auth_required:

true (default): profile authentication requires SMS verification. POST /record/{token}/auth/ returns a draft_token, then you finish with PUT /record/{token}/auth/verify/ and the SMS code.
false: POST /record/{token}/auth/ creates the profile immediately.

The quickstart shows both paths so you can adapt to whichever your account uses.

Step-by-step flow

Get your API key

Verify the connection

Test that your key works by calling the connection endpoint.

curl -X GET "https://braintest.ir/api/v2/auth/connect/" \
  -H "API-KEY: YOUR_API_KEY"

Expected response:

{
  "data": { "connected": true },
  "successful": true,
  "messages": []
}

List available records

Fetch the list of records and find one with status: 2 (ready) and auth_required: true. Note the tests_auth_required field so you know which path to follow.

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

Example response (truncated):

{
  "data": [
    {
      "token": "rec_abc123",
      "test_id": 1,
      "test_title": "DASS-21",
      "status": 2,
      "auth_required": true,
      "tests_auth_required": true,
      "is_finished": false
    }
  ],
  "successful": true,
  "messages": []
}

Save the token value for the next step.

Start authentication

Send the participant profile to the auth endpoint. The request body is the same regardless of the path.

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

Branch on the response.SMS path (tests_auth_required: true) returns a draft_token and sends an SMS code to the participant’s mobile:

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

Instant path (tests_auth_required: false) returns the profile immediately. Skip the next step.

{
  "data": {
    "tests_auth_required": false,
    "profile": { "token": "prof_xyz", "name": "علی احمدی", "age": 34, "is_male": true }
  },
  "successful": true,
  "messages": []
}

Verify the SMS code (SMS path only)

Ask the participant for the code they received and submit it with the draft_token. The draft token is valid for 5 minutes.

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

Expected response:

{
  "data": {
    "tests_auth_required": true,
    "profile": {
      "token": "prof_xyz",
      "name": "علی احمدی",
      "age": 34,
      "is_male": true
    }
  },
  "successful": true,
  "messages": []
}

Skip this step when tests_auth_required is false.

Fetch questions

Retrieve the test questions for the authenticated record.

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

Example response:

{
  "data": {
    "questions": [
      { "id": 1, "text": "I found it hard to wind down", "options": [] },
      { "id": 2, "text": "I was aware of dryness of my mouth", "options": [] }
    ]
  },
  "successful": true,
  "messages": []
}

Submit answers

Send the participant answers back. The record array maps question IDs to selected option values.

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

Expected response:

{
  "data": { "submitted": true },
  "successful": true,
  "messages": []
}

Retrieve the result

After submission, fetch the scored result.

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

Example response:

{
  "data": {
    "scores": {
      "depression": 12,
      "anxiety": 8,
      "stress": 10
    },
    "interpretation": "Moderate depression, mild anxiety, moderate stress"
  },
  "successful": true,
  "messages": []
}

You can also request HTML output by calling /result/html/ instead.

Next steps

Learn about authentication details
Explore test records and cognitive roadmaps
Follow the cognitive roadmap guide for multi-test flows

Get Started

Core Concepts

Guides

Reference

Get Started with the Braintest API

Prerequisites

Authentication paths

Step-by-step flow

Next steps

​Prerequisites

​Authentication paths

​Step-by-step flow

​Next steps

Prerequisites

Authentication paths

Step-by-step flow

Next steps