> ## 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 a Standalone Test Profile

> Register a participant profile for a standalone test record. Supports both instant authentication and SMS verification depending on the organizer setting.

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.

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

## Endpoint

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

<ParamField path="token" type="string" required>
  The UUID token of the test record.
</ParamField>

## Body parameters

<ParamField body="name" type="string" required>
  Participant's full name. Maximum 50 characters. Must contain Persian letters only.
</ParamField>

<ParamField body="mobile" type="string" required>
  Participant's mobile number in Iranian format: 11 digits starting with `09`, for example `09123456789`.
</ParamField>

<ParamField body="birth" type="string" required>
  Participant's birth date in ISO 8601 format, for example `1990-05-15`.
</ParamField>

<ParamField body="is_male" type="boolean" required>
  Participant's gender. `true` for male, `false` for female.
</ParamField>

<ParamField body="external_id" type="integer">
  Your own unique identifier for this participant. Must be unique per organizer. Useful for idempotent lookups later.
</ParamField>

## Response

The response shape depends on the organizer's `tests_auth_required` setting, which is echoed in every record 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 profile is created immediately.
</ResponseField>

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

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

## Example request

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

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

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

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