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

# Run a Standalone Psychological Test

> End-to-end flow for a single psychological test on Braintest: list records, authenticate a participant (SMS or instant), submit answers, retrieve results.

This guide walks you through administering a standalone psychological test (a single record) using the Braintest API. You will list available records, authenticate a participant profile using either SMS verification or the instant path (depending on your organizer setting), fetch questions, submit answers, and retrieve the final result.

<Note>
  **Prerequisites**

  * A valid API key from the organizer panel, sent in the `API-KEY` header
  * At least one record with `status: 2` (ready) available in your account
</Note>

<Warning>
  Do **not** call `/record/{token}/auth/` for records that belong to a cognitive roadmap. Roadmap records must be authenticated through the roadmap endpoint instead. See the [Cognitive Roadmap guide](/guides/run-cognitive-roadmap) for details.
</Warning>

## Two authentication paths

Every record payload includes an organizer-level flag named `tests_auth_required` that controls how authentication works:

| `tests_auth_required` | Behavior                                                                                                                                                         |
| --------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `true` (default)      | `POST /record/{token}/auth/` sends an SMS code to the participant's mobile and returns a `draft_token`. Finish the flow with `PUT /record/{token}/auth/verify/`. |
| `false`               | `POST /record/{token}/auth/` authenticates the profile immediately and returns it. Skip the verify step.                                                         |

Read `tests_auth_required` from the record before choosing the next step. Your integration should handle both paths.

<Steps>
  <Step title="List your records">
    Fetch your available records. Filter for unfinished, ready records so you only see tests that can be started.

    ```bash theme={"dark"}
    curl -X GET "https://braintest.ir/api/v2/record/?filter__is_finished=false" \
      -H "API-KEY: YOUR_API_KEY"
    ```

    Look for a record with `status: 2` (ready) and `auth_required: true`. The response includes the `token` you need for the next steps, plus `tests_auth_required` which tells you whether SMS verification is on.
  </Step>

  <Step title="Inspect the record">
    Retrieve the full record details before starting.

    ```bash theme={"dark"}
    curl -X GET "https://braintest.ir/api/v2/record/{token}/" \
      -H "API-KEY: YOUR_API_KEY"
    ```

    Key fields to review:

    * `status`: must be `2` (ready)
    * `auth_required`: must be `true` before you can authenticate
    * `tests_auth_required`: selects the auth path (see the decision matrix above)
    * `test.questions_count`: total number of questions
    * `test.doing_time_minutes`: recommended time limit
    * `test.gender_permission`: gender restrictions, if any
  </Step>

  <Step title="Start authentication">
    Post the participant profile to the auth endpoint. The body is the same regardless of `tests_auth_required`.

    ```bash theme={"dark"}
    curl -X POST "https://braintest.ir/api/v2/record/{token}/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
      }'
    ```

    **Profile fields**

    | Field         | Type    | Required | Description                                               |
    | ------------- | ------- | -------- | --------------------------------------------------------- |
    | `name`        | string  | Yes      | Participant name, max 50 characters, Persian letters only |
    | `mobile`      | string  | Yes      | Iranian mobile number, 11 digits starting with `09`       |
    | `birth`       | string  | Yes      | Date of birth in ISO 8601 format (`YYYY-MM-DD`)           |
    | `is_male`     | boolean | Yes      | `true` for male, `false` for female                       |
    | `external_id` | integer | No       | Partner-assigned unique identifier per organizer          |

    The response echoes `tests_auth_required`. Branch on it to decide the next step.

    **SMS path (`tests_auth_required: true`)**

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

    An SMS code is sent to the participant's mobile. Keep the `draft_token` for the verify step. It expires after 5 minutes.

    **Instant path (`tests_auth_required: false`)**

    ```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": []
    }
    ```

    The profile is created and linked to the record immediately. Skip the next step and jump to fetching questions.
  </Step>

  <Step title="Verify the SMS code (SMS path only)">
    Ask the participant for the code they received, then send it with the `draft_token` to complete authentication.

    ```bash theme={"dark"}
    curl -X PUT "https://braintest.ir/api/v2/record/{token}/auth/verify/" \
      -H "API-KEY: YOUR_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{
        "draft_token": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
        "vcode": "58291"
      }'
    ```

    **Success response**

    ```json theme={"dark"}
    {
      "data": {
        "tests_auth_required": true,
        "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": []
    }
    ```

    **Common errors**

    | Message                                                        | Fix                                                                                            |
    | -------------------------------------------------------------- | ---------------------------------------------------------------------------------------------- |
    | `Verification draft token is invalid or expired.`              | The draft token is unknown or older than 5 minutes. Restart from `POST /record/{token}/auth/`. |
    | `Verification code is invalid.`                                | Ask the participant to re-enter the code.                                                      |
    | `SMS verification is not required for this organizer account.` | The setting is disabled. Use the profile returned by the auth call instead.                    |

    Skip this step entirely when `tests_auth_required` is `false`.
  </Step>

  <Step title="Fetch the questions">
    Retrieve the question set for the authenticated participant.

    ```bash theme={"dark"}
    curl -X GET "https://braintest.ir/api/v2/record/{token}/questions/" \
      -H "API-KEY: YOUR_API_KEY"
    ```

    The API supports two response formats:

    * **JSON** (default): structured question objects with IDs, text, and options
    * **HTML**: pre-rendered question markup for direct embedding in a web view

    Request HTML explicitly by adding `?format=html` to the URL if your client renders a web interface.
  </Step>

  <Step title="Submit answers">
    Send the participant's responses back. The `record` array maps each question to its selected answer.

    ```bash theme={"dark"}
    curl -X POST "https://braintest.ir/api/v2/record/{token}/" \
      -H "API-KEY: YOUR_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{
        "record": [
          { "question_id": 1, "answer_id": 3 },
          { "question_id": 2, "answer_id": 1 },
          { "question_id": 3, "answer_id": 4 }
        ],
        "doing_duration_in_minutes": 12
      }'
    ```

    * `record`: array of objects, each with `question_id` and `answer_id`
    * `doing_duration_in_minutes`: integer, time the participant spent answering

    After submission, the record status changes to `1` (finished) and results become available.
  </Step>

  <Step title="Retrieve the result">
    Once `is_finished` is `true`, fetch the test results in your preferred format.

    <CodeGroup>
      ```bash JSON result theme={"dark"}
      curl -X GET "https://braintest.ir/api/v2/record/{token}/result/json/" \
        -H "API-KEY: YOUR_API_KEY"
      ```

      ```bash HTML result theme={"dark"}
      curl -X GET "https://braintest.ir/api/v2/record/{token}/result/html/" \
        -H "API-KEY: YOUR_API_KEY"
      ```
    </CodeGroup>

    The JSON response contains structured scores, interpretations, and metadata. The HTML response is a ready-to-render report page.
  </Step>
</Steps>

## Flow summary

**SMS enabled (`tests_auth_required: true`, default)**

```text theme={"dark"}
GET  /record/                          → read tests_auth_required
POST /record/{token}/auth/             → draft_token (SMS sent)
PUT  /record/{token}/auth/verify/      → profile
GET  /record/{token}/questions/
POST /record/{token}/
GET  /record/{token}/result/json|html/
```

**SMS disabled (`tests_auth_required: false`)**

```text theme={"dark"}
POST /record/{token}/auth/             → profile (instant)
GET  /record/{token}/questions/
POST /record/{token}/
GET  /record/{token}/result/json|html/
```

## What to do next

* Learn how to run [multi-test cognitive roadmaps](/guides/run-cognitive-roadmap) with AI-powered analysis
* Review the [status code reference](/reference/status-codes) to understand record lifecycle states
* Check the [error reference](/reference/errors) for common issues and how to resolve them