Get Test Questions

Fetch questionnaire content for an authenticated test record as a flat JSON questions array or a pre-rendered HTML form.

Use this endpoint to retrieve the questionnaire for a test record from the Braintest analyst engine. The response is either a flat JSON questions[] array (when the test has a JSON definition) or a rendered HTML form (when the test uses an HTML template).

Endpoint

GET https://braintest.ir/api/v2/record/{token}/questions/

Headers

Header	Value
API-KEY	Your API key from the organizer panel

Path parameters

token · string · required

The UUID token of the test record.

Prerequisites

• Profile authenticated (auth_required is false on the record).
• If the organizer has tests_auth_required: true, complete POST /record/{token}/auth/ followed by PUT /record/{token}/auth/verify/ first.
• Record must not be finished; billing/VIP checks must pass. Otherwise the endpoint returns 403 or 409.

Response formats

The analyst chooses the delivery format per test. There is no sections wrapper: questions are a flat array in display order.

Format	When	data shape
JSON questionnaire	Test has a JSON definition in analyst	test_id, optional preface, questions[]
HTML questionnaire	Test uses an HTML template in analyst	{ "html": "<...>" } only

JSON response fields

test_id · string

Test identifier. Matches the test_id on the record (for example, MCMI, NEO, DASS21).

preface · string | null

Optional instruction text shown before the questions.

questions · array

Flat array of questions in display order. Each item contains:

Show question item

num · string

Question number as defined in analyst data.

question · object

Question stem with optional media.

• text (string): Question text.
• audio (string | null): Optional audio path (may be relative to the analyst media base URL).
• image (string | null): Optional image path (may be relative to the analyst media base URL).

answer · object

Answer specification.

• text (boolean): true means free-text answer (no options); false means the participant selects one option from options.
• options (array, present when text is false): Available choices.

Each option object contains:

id · integer

Value to submit in the record array for this question when the participant selects this option.

num · string

Display order label.

text · string

Option label shown to the participant. Do not send this string as the answer.

audio · string | null

Optional audio path.

image · string | null

Optional image path.

Example request

curl -X GET "https://braintest.ir/api/v2/record/3fa85f64-5717-4562-b3fc-2c963f66afa6/questions/" \
  -H "API-KEY: YOUR_API_KEY"

Example response (JSON questionnaire)

{
  "data": {
    "test_id": "MCMI",
    "preface": "Read each statement and select the closest answer.",
    "questions": [
      {
        "num": "1",
        "question": {
          "text": "Lately, I feel I have not had much energy even in the morning.",
          "audio": null,
          "image": null
        },
        "answer": {
          "text": false,
          "options": [
            { "num": "1", "id": 0, "text": "True", "audio": null, "image": null },
            { "num": "2", "id": 1, "text": "False", "audio": null, "image": null }
          ]
        }
      },
      {
        "num": "2",
        "question": {
          "text": "I must be sure my work is well planned and organized.",
          "audio": null,
          "image": null
        },
        "answer": {
          "text": false,
          "options": [
            { "num": "1", "id": 0, "text": "True", "audio": null, "image": null },
            { "num": "2", "id": 1, "text": "False", "audio": null, "image": null }
          ]
        }
      }
    ]
  },
  "successful": true,
  "messages": []
}

Submitting answers

Call POST /record/{token}/ with record as an array with one entry per question, in the same order as questions[]:

• Option questions → the selected option’s id (integer).
• Free-text questions (answer.text: true) → the participant’s string answer.

Example for a 3-item test: [1, 0, "my written answer"].

Allowed values and array length are validated by the analyst for each test (for example, MCMI expects 195 integers of 0 or 1).

Example response (HTML questionnaire)

When the analyst uses an HTML template, data contains only an html string:

{
  "data": {
    "html": "<div class=\"test-form\">...</div>"
  },
  "successful": true,
  "messages": []
}

Embed the html string in an iframe or WebView. HTML forms are designed for the Braintest panel flow; for deep external integration, prefer tests that return JSON so you control the UI and submit via POST /record/{token}/.

Errors

Status	Meaning
403	Profile auth, payment, or VIP prerequisite not met.
404	Test record not found.
409	Record already completed.