Authenticate a Standalone Test Profile

Use this endpoint to link a participant profile to a standalone test record. The response depends on the organizer setting tests_auth_required: with SMS verification enabled, the API returns a draft_token and sends a code to the participant; without SMS, the profile is created immediately.

This endpoint is for standalone records only. If the record belongs to a cognitive roadmap, use POST /roadmap/{token}/auth/ instead. Calling this endpoint on a roadmap record returns HTTP 409.

Endpoint

POST https://braintest.ir/api/v2/record/{token}/auth/

Headers

Header	Value
`API-KEY`	Your API key from the organizer panel
`Content-Type`	`application/json`

Path parameters

string

required

The UUID token of the test record.

Body parameters

string

required

Participant’s full name. Maximum 50 characters. Must contain Persian letters only.

string

required

Participant’s mobile number in Iranian format: 11 digits starting with 09, for example 09123456789.

string

required

Participant’s birth date in ISO 8601 format, for example 1990-05-15.

boolean

required

Participant’s gender. true for male, false for female.

integer

Your own unique identifier for this participant. Must be unique per organizer. Useful for idempotent lookups later.

Response

The response shape depends on the organizer’s tests_auth_required setting, which is echoed in every record payload.

boolean

Organizer policy. true means SMS verification is required and a draft_token is returned. false means the profile is created immediately.

string

Returned only when tests_auth_required is true. Pass this to PUT /record/{token}/auth/verify/ along with the SMS code. Valid for 5 minutes.

object

Returned only when tests_auth_required is false. Contains the created profile with token, external_id, case_number, mobile, name, age, birth, and is_male.

Example request

curl -X POST "https://braintest.ir/api/v2/record/a1b2c3d4-e5f6-7890-abcd-ef1234567890/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
  }'

Example response (SMS verification enabled)

When tests_auth_required is true (default), the API sends an SMS code and returns a draft token:

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

Next step: call PUT /record/{token}/auth/verify/ with the draft_token and the SMS code the participant received.

Example response (SMS verification disabled)

When tests_auth_required is false, the profile is created immediately:

{
  "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": []
}

Next step: call GET /record/{token}/questions/ to fetch the test questions.

Error responses

Status	Meaning	What to do
`400`	Mobile duplicate limit reached (SMS mode only)	Use a different mobile number or contact support.
`409`	Record belongs to a roadmap	Use `POST /roadmap/{token}/auth/` instead.
`409`	Duplicate `external_id`	Choose a unique `external_id` per organizer.
`429`	API rate limit exceeded (100/minute or 3,000/hour)	Wait and retry. See Rate Limits.

Overview

Connection

Records

Roadmaps

Authenticate a Standalone Test Profile

Endpoint

Headers

Path parameters

Body parameters

Response

Example request

Example response (SMS verification enabled)

Example response (SMS verification disabled)

Error responses

​Endpoint

​Headers

​Path parameters

​Body parameters

​Response

​Example request

​Example response (SMS verification enabled)

​Example response (SMS verification disabled)

​Error responses

Endpoint

Headers

Path parameters

Body parameters

Response

Example request

Example response (SMS verification enabled)

Example response (SMS verification disabled)

Error responses