Verify Roadmap Profiles via SMS

Use this endpoint to finish authenticating all role profiles for a cognitive roadmap when the organizer setting tests_auth_required is true. It exchanges the draft_token from POST /roadmap/{token}/auth/ plus the SMS code for the final list of role profiles.

Only call this endpoint when tests_auth_required is true on the roadmap. If the setting is disabled, the auth call already returns the roles and this endpoint returns a 400 error.

Endpoint

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

Headers

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

Path parameters

string

required

The unique cognitive roadmap instance UUID.

Body parameters

string

required

The draft_token returned by POST /roadmap/{token}/auth/. Valid for 5 minutes.

string

required

The SMS verification code sent to the shared mobile number.

Response

boolean

Echoes the organizer setting. Always true when this endpoint succeeds.

array

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 request

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

Example response

{
  "data": {
    "tests_auth_required": true,
    "roles": [
      {
        "role_id": 1,
        "profile": {
          "token": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
          "external_id": 20001,
          "case_number": "ORG-00001",
          "mobile": "09129876543",
          "name": "Ali Rezaei",
          "age": 34,
          "birth": "1990-03-10",
          "is_male": true
        }
      },
      {
        "role_id": 2,
        "profile": {
          "token": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
          "external_id": 20002,
          "case_number": "ORG-00002",
          "mobile": "09129876543",
          "name": "Sara Mohammadi",
          "age": 32,
          "birth": "1992-07-22",
          "is_male": false
        }
      }
    ]
  },
  "successful": true,
  "messages": []
}

Error responses

Status	Message	Cause
`400`	`Verification draft token is invalid or expired.`	The draft token is unknown or older than 5 minutes. Restart the flow with `POST /roadmap/{token}/auth/`.
`400`	`Verification code is invalid.`	The `vcode` does not match the SMS code. Have the participant re-enter it.
`400`	`SMS verification is not required for this organizer account.`	The organizer setting `tests_auth_required` is `false`. Use the roles returned by the auth call directly.
`429`	API rate limit exceeded	Wait and retry. See Rate Limits.

Overview

Connection

Records

Roadmaps

Verify Roadmap Profiles via SMS

Endpoint

Headers

Path parameters

Body parameters

Response

Example request

Example response

Error responses

​Endpoint

​Headers

​Path parameters

​Body parameters

​Response

​Example request

​Example response

​Error responses

Endpoint

Headers

Path parameters

Body parameters

Response

Example request

Example response

Error responses