Authenticate Roadmap Profiles

Use this endpoint to authenticate participant profiles for every role in a cognitive roadmap. 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 shared mobile number; without SMS, all role profiles are created immediately and linked to every associated test record.

Do not call /record/{token}/auth/ for test records that are part of a roadmap. Always use /roadmap/{token}/auth/ instead. Calling the record-level auth endpoint for a roadmap record returns a 409 error.

Endpoint

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

Path Parameters

string

required

The unique cognitive roadmap instance UUID.

Request Body

string

required

Shared Iranian mobile number applied to every role profile. Must be 11 digits starting with 09. When SMS verification is enabled, the code is sent to this number.

array

required

Array of role entries. Must contain at least one item. Each entry must match a role ID from the roadmap definition.

Role Entry Fields

integer

required

The role ID. Must match one of the roles returned by GET /roadmap/{token}/.

object

required

Profile object for this role.

string

required

Full name in Persian letters. Maximum 50 characters.

string

required

Date of birth in ISO 8601 format (for example, 1998-01-15).

boolean

required

true for male, false for female.

integer

Optional partner-assigned numeric identifier. Must be unique per organizer account.

Response

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

boolean

Organizer policy. true means SMS verification is required and a draft_token is returned. false means the roles are authenticated immediately.

string

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

array

Returned only when tests_auth_required is false. Array of authenticated roles. Each item contains role_id and a profile object with token, external_id, case_number, mobile, name, age, birth, and is_male.

Example: Single-Participant Roadmap

curl -X POST "https://braintest.ir/api/v2/roadmap/b2c3d4e5-f6a7-8901-bcde-f12345678901/auth/" \
  -H "API-KEY: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "mobile": "09123456789",
    "roles": [
      {
        "id": 1,
        "profile": {
          "name": "Ali Rezaei",
          "birth": "1998-01-15",
          "is_male": true,
          "external_id": 10042
        }
      }
    ]
  }'

Example: Two-Role Roadmap (Couple)

curl -X POST "https://braintest.ir/api/v2/roadmap/b2c3d4e5-f6a7-8901-bcde-f12345678901/auth/" \
  -H "API-KEY: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "mobile": "09129876543",
    "roles": [
      {
        "id": 1,
        "profile": {
          "name": "Ali Rezaei",
          "birth": "1990-03-10",
          "is_male": true,
          "external_id": 20001
        }
      },
      {
        "id": 2,
        "profile": {
          "name": "Sara Mohammadi",
          "birth": "1992-07-22",
          "is_male": false,
          "external_id": 20002
        }
      }
    ]
  }'

Example response (SMS verification enabled)

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

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

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

Example response (SMS verification disabled)

When tests_auth_required is false, all role profiles are created immediately:

{
  "data": {
    "tests_auth_required": false,
    "roles": [
      {
        "role_id": 1,
        "profile": {
          "token": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
          "external_id": 10042,
          "case_number": "ORG-00001",
          "mobile": "09123456789",
          "name": "Ali Rezaei",
          "age": 28,
          "birth": "1998-01-15",
          "is_male": true
        }
      }
    ]
  },
  "successful": true,
  "messages": []
}

Next step: loop through the roadmap’s test_records and, for each one, fetch questions and submit answers.

Error Responses

HTTP	Cause
400	Invalid profile data, missing required fields, or age/gender mismatch
400	Mobile duplicate limit reached (SMS mode only)
404	Roadmap not found or already finished
409	Duplicate `external_id` for this organizer account
429	API rate limit exceeded (100/minute or 3,000/hour). See Rate Limits.

Overview

Connection

Records

Roadmaps

Authenticate Roadmap Profiles

Endpoint

Path Parameters

Request Body

Role Entry Fields

Response

Example: Single-Participant Roadmap

Example: Two-Role Roadmap (Couple)

Example response (SMS verification enabled)

Example response (SMS verification disabled)

Error Responses

​Endpoint

​Path Parameters

​Request Body

​Role Entry Fields

​Response

​Example: Single-Participant Roadmap

​Example: Two-Role Roadmap (Couple)

​Example response (SMS verification enabled)

​Example response (SMS verification disabled)

​Error Responses

Endpoint

Path Parameters

Request Body

Role Entry Fields

Response

Example: Single-Participant Roadmap

Example: Two-Role Roadmap (Couple)

Example response (SMS verification enabled)

Example response (SMS verification disabled)

Error Responses