> ## Documentation Index
> Fetch the complete documentation index at: https://docs.braintest.ir/llms.txt
> Use this file to discover all available pages before exploring further.

# Verify Roadmap Profiles via SMS

> Complete SMS-based cognitive roadmap authentication by submitting the draft token and the code the participant received.

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.

<Note>
  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.
</Note>

## Endpoint

```http theme={"dark"}
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

<ParamField path="token" type="string" required>
  The unique cognitive roadmap instance UUID.
</ParamField>

## Body parameters

<ParamField body="draft_token" type="string" required>
  The `draft_token` returned by `POST /roadmap/{token}/auth/`. Valid for 5 minutes.
</ParamField>

<ParamField body="vcode" type="string" required>
  The SMS verification code sent to the shared mobile number.
</ParamField>

## Response

<ResponseField name="data.tests_auth_required" type="boolean">
  Echoes the organizer setting. Always `true` when this endpoint succeeds.
</ResponseField>

<ResponseField name="data.roles" type="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`.
</ResponseField>

## Example request

```bash theme={"dark"}
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

```json theme={"dark"}
{
  "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](/reference/rate-limits).                                                |