> ## 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.

# Authenticate Roadmap Profiles

> Register all participant profiles for a cognitive roadmap in a single call. Supports both instant authentication and SMS verification depending on the organizer setting.

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.

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

## Endpoint

```http theme={"dark"}
POST https://braintest.ir/api/v2/roadmap/{token}/auth/
```

## Path Parameters

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

## Request Body

<ParamField body="mobile" type="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.
</ParamField>

<ParamField body="roles" type="array" required>
  Array of role entries. Must contain at least one item. Each entry must match a role ID from the roadmap definition.
</ParamField>

### Role Entry Fields

<ParamField body="roles[].id" type="integer" required>
  The role ID. Must match one of the `roles` returned by `GET /roadmap/{token}/`.
</ParamField>

<ParamField body="roles[].profile" type="object" required>
  Profile object for this role.
</ParamField>

<ParamField body="roles[].profile.name" type="string" required>
  Full name in Persian letters. Maximum 50 characters.
</ParamField>

<ParamField body="roles[].profile.birth" type="string" required>
  Date of birth in ISO 8601 format (for example, `1998-01-15`).
</ParamField>

<ParamField body="roles[].profile.is_male" type="boolean" required>
  `true` for male, `false` for female.
</ParamField>

<ParamField body="roles[].profile.external_id" type="integer">
  Optional partner-assigned numeric identifier. Must be unique per organizer account.
</ParamField>

## Response

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

<ResponseField name="data.tests_auth_required" type="boolean">
  Organizer policy. `true` means SMS verification is required and a `draft_token` is returned. `false` means the roles are authenticated immediately.
</ResponseField>

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

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

## Example: Single-Participant Roadmap

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

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

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

**Next step:** call [`PUT /roadmap/{token}/auth/verify/`](/api-reference/roadmaps/verify-profiles) 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:

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