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

# Get Started with the Braintest API

> Make your first Braintest API call: verify your key, authenticate a participant (SMS or instant), submit answers, and retrieve a test result.

This guide walks you through your first complete standalone test flow. By the end, you will have verified your connection, authenticated a participant, submitted answers, and retrieved a result from the Braintest API.

## Prerequisites

* A Braintest partner account with API access
* Your API key from the organizer panel
* `curl` or any HTTP client

## Authentication paths

Every record includes an organizer setting called `tests_auth_required`:

* `true` (default): profile authentication requires SMS verification. `POST /record/{token}/auth/` returns a `draft_token`, then you finish with `PUT /record/{token}/auth/verify/` and the SMS code.
* `false`: `POST /record/{token}/auth/` creates the profile immediately.

The quickstart shows both paths so you can adapt to whichever your account uses.

## Step-by-step flow

<Steps>
  <Step title="Get your API key">
    Log in to the Braintest organizer panel and generate an API key. Send it in the `API-KEY` header on every request.
  </Step>

  <Step title="Verify the connection">
    Test that your key works by calling the connection endpoint.

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

    Expected response:

    ```json theme={"dark"}
    {
      "data": { "connected": true },
      "successful": true,
      "messages": []
    }
    ```
  </Step>

  <Step title="List available records">
    Fetch the list of records and find one with `status: 2` (ready) and `auth_required: true`. Note the `tests_auth_required` field so you know which path to follow.

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

    Example response (truncated):

    ```json theme={"dark"}
    {
      "data": [
        {
          "token": "rec_abc123",
          "test_id": 1,
          "test_title": "DASS-21",
          "status": 2,
          "auth_required": true,
          "tests_auth_required": true,
          "is_finished": false
        }
      ],
      "successful": true,
      "messages": []
    }
    ```

    Save the `token` value for the next step.
  </Step>

  <Step title="Start authentication">
    Send the participant profile to the auth endpoint. The request body is the same regardless of the path.

    ```bash theme={"dark"}
    curl -X POST "https://braintest.ir/api/v2/record/rec_abc123/auth/" \
      -H "API-KEY: YOUR_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{
        "name": "علی احمدی",
        "mobile": "09123456789",
        "birth": "1990-05-15",
        "is_male": true
      }'
    ```

    Branch on the response.

    **SMS path (`tests_auth_required: true`)** returns a `draft_token` and sends an SMS code to the participant's mobile:

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

    **Instant path (`tests_auth_required: false`)** returns the profile immediately. Skip the next step.

    ```json theme={"dark"}
    {
      "data": {
        "tests_auth_required": false,
        "profile": { "token": "prof_xyz", "name": "علی احمدی", "age": 34, "is_male": true }
      },
      "successful": true,
      "messages": []
    }
    ```
  </Step>

  <Step title="Verify the SMS code (SMS path only)">
    Ask the participant for the code they received and submit it with the `draft_token`. The draft token is valid for 5 minutes.

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

    Expected response:

    ```json theme={"dark"}
    {
      "data": {
        "tests_auth_required": true,
        "profile": {
          "token": "prof_xyz",
          "name": "علی احمدی",
          "age": 34,
          "is_male": true
        }
      },
      "successful": true,
      "messages": []
    }
    ```

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

  <Step title="Fetch questions">
    Retrieve the test questions for the authenticated record.

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

    Example response:

    ```json theme={"dark"}
    {
      "data": {
        "questions": [
          { "id": 1, "text": "I found it hard to wind down", "options": [] },
          { "id": 2, "text": "I was aware of dryness of my mouth", "options": [] }
        ]
      },
      "successful": true,
      "messages": []
    }
    ```
  </Step>

  <Step title="Submit answers">
    Send the participant answers back. The `record` array maps question IDs to selected option values.

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

    Expected response:

    ```json theme={"dark"}
    {
      "data": { "submitted": true },
      "successful": true,
      "messages": []
    }
    ```
  </Step>

  <Step title="Retrieve the result">
    After submission, fetch the scored result.

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

    Example response:

    ```json theme={"dark"}
    {
      "data": {
        "scores": {
          "depression": 12,
          "anxiety": 8,
          "stress": 10
        },
        "interpretation": "Moderate depression, mild anxiety, moderate stress"
      },
      "successful": true,
      "messages": []
    }
    ```

    You can also request HTML output by calling `/result/html/` instead.
  </Step>
</Steps>

## Next steps

* Learn about [authentication details](/authentication)
* Explore [test records](/concepts/records) and [cognitive roadmaps](/concepts/roadmaps)
* Follow the [cognitive roadmap guide](/guides/run-cognitive-roadmap) for multi-test flows