> ## Documentation Index
> Fetch the complete documentation index at: https://docs.olira.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Questionnaires

> Structured instrument submissions and scored questionnaires. 2 log types with payload schemas and examples.

Structured instrument submissions and scored questionnaires. Submit these via `POST /v1/logs/batch` or the [Python SDK](/reference/sdk); see [How logs work](/send-data/how-logs-work) for submission fields and the difference between **lifecycle-tracked** and point-in-time log types.

## Questionnaire response

**Type:** `questionnaire_response` · **Source:** Python SDK / REST, Integration · **Extensible**

Reserved for a complete multi-item questionnaire or instrument submission: validated (PHQ-9, GAD-7, etc.) or custom instrument with instrument block, administration, item\_responses\[], and scores; one event per completed instrument.

**Payload**

<ResponseField name="instrument" type="object" required>
  <Expandable title="fields">
    <ResponseField name="instrument_id" type="string" required>
      Instrument identifier.. Example: `PHQ-9`, `GAD-7`, `FACT-G`
    </ResponseField>

    <ResponseField name="instrument_type" type="string" required>
      Whether this is a standardised validated instrument or a custom one.. Example: `validated`, `custom`
    </ResponseField>

    <ResponseField name="instrument_version" type="string">
      Version string of the instrument.
    </ResponseField>

    <ResponseField name="recall_period_days" type="integer">
      Recall window in days (e.g. PHQ-9 = 14, GAD-7 = 14). Resolved from registry for standard instruments.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="administration" type="object" required>
  <Expandable title="fields">
    <ResponseField name="administration_mode" type="string" required>
      Who completed the questionnaire.. Example: `patient_self_report`, `clinician_administered`, `caregiver_proxy`
    </ResponseField>

    <ResponseField name="platform" type="string">
      The platform on which the questionnaire was administered.. Example: `mobile_app`, `web`, `paper_transcribed`
    </ResponseField>

    <ResponseField name="language" type="string">
      BCP 47 language tag (e.g. en-US).
    </ResponseField>

    <ResponseField name="completion_time_seconds" type="number">
      Time taken to complete, in seconds.
    </ResponseField>

    <ResponseField name="items_completed" type="integer">
      Number of items completed.
    </ResponseField>

    <ResponseField name="items_skipped" type="integer">
      Number of items skipped.
    </ResponseField>

    <ResponseField name="administered_by" type="object">
      <Expandable title="fields">
        <ResponseField name="name" type="string">
          Name of person who administered; required when mode is not patient\_self\_report.
        </ResponseField>

        <ResponseField name="npi" type="string">
          NPI of administrator if applicable.
        </ResponseField>

        <ResponseField name="role" type="string">
          Role of administrator.
        </ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="item_responses" type="object[]" required>
  <Expandable title="fields">
    <ResponseField name="item_number" type="integer" required>
      1-indexed item number.
    </ResponseField>

    <ResponseField name="item_text" type="string">
      Question text. Required for custom instruments; optional for standard instruments (resolved from registry).
    </ResponseField>

    <ResponseField name="response_value" type="number | string | boolean" required>
      Response value for this item. Numeric for scored instruments (e.g. 2 for PHQ-9 items), boolean for yes/no items, or string for categorical responses (e.g. 'daily', 'sometimes').
    </ResponseField>

    <ResponseField name="response_label" type="string">
      Human-readable label for the response (e.g. 'More than half the days').
    </ResponseField>

    <ResponseField name="response_scale_max" type="number">
      Maximum value of the item response scale. Only meaningful for numeric response\_value.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="scores" type="object" required>
  <Expandable title="fields">
    <ResponseField name="total_score" type="number">
      Total instrument score. Only set when all item response\_values are numeric; omit for non-numeric questionnaires.
    </ResponseField>

    <ResponseField name="total_score_max" type="number">
      Maximum possible total score. For standard instruments this is computed internally.
    </ResponseField>

    <ResponseField name="severity_category" type="string">
      Severity interpretation (e.g. mild, moderate, severe).. Example: `minimal`, `mild`, `moderate`
    </ResponseField>

    <ResponseField name="domain_scores" type="object">
      Map of domain name to domain score for multi-domain instruments.
    </ResponseField>

    <ResponseField name="clinically_significant" type="boolean">
      Whether the total score meets or exceeds the clinical significance threshold.
    </ResponseField>

    <ResponseField name="significance_threshold" type="number">
      Score threshold for clinical significance. Resolved from registry for standard instruments.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="change" type="object">
  Change from prior administration.

  <Expandable title="fields">
    <ResponseField name="prior_score" type="number">
      Score from prior administration.
    </ResponseField>

    <ResponseField name="prior_date" type="string">
      Date of prior administration.
    </ResponseField>

    <ResponseField name="change" type="number">
      Numeric change in score.
    </ResponseField>

    <ResponseField name="minimally_important_difference" type="number">
      MID for this instrument; used to interpret change.
    </ResponseField>

    <ResponseField name="change_classification" type="string">
      Direction of change relative to prior score.. Example: `improved`, `stable`, `worsened`
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="extensions" type="object">
  Open key/value bag for client/source-specific fields that lack a typed slot; merged into the entry's extensions (leaf-level, last-writer-wins by event timestamp).
</ResponseField>

<ResponseField name="source" type="string | object">
  Who asserted this fact. Accepts a legacy string (e.g. 'patient\_self\_report') or a structured Source object.
</ResponseField>

**Example**

<CodeGroup>
  ```python Python theme={null}
  import olira
  from olira import OliraLogType

  olira.log(
      log_type=OliraLogType.QUESTIONNAIRE_RESPONSE,
      patient_id="your-patient-id",
      payload={
          "instrument": {...},
          "administration": {...},
          "item_responses": [...],
          "scores": {...}
      },
  )
  ```

  ```http HTTP theme={null}
  POST /v1/logs/batch
  Authorization: Bearer YOUR_API_KEY
  Content-Type: application/json

  {
    "logs": [
      {
        "log_type": "questionnaire_response",
        "patient_id": "8a4fde23-0f1b-4c2a-9d7e-b36c1a5f0e82",
        "timestamp": "2026-03-18T09:00:00Z",
        "payload": {
          "instrument": {...},
          "administration": {...},
          "item_responses": [...],
          "scores": {...}
      }
      }
    ]
  }
  ```
</CodeGroup>

<Note>
  **Related types:** Use [`questionnaire_item_response`](/reference/log-types/questionnaires#questionnaire-item-response) for single question and answer, [`mood_report`](/reference/log-types/symptom-reports#mood-report) for mood list, [`health_metric`](/reference/log-types/symptom-reports#health-metric) for single health metric, [`symptom_report`](/reference/log-types/symptom-reports#symptom-report) for symptom report.
</Note>

## Questionnaire item response

**Type:** `questionnaire_item_response` · **Source:** Python SDK / REST

Reserved for a single question-and-answer pair, not a full instrument: mid-conversation prompted question, ad-hoc assessment, or per-item logging; question + response\_value (and optional response\_label, scale).

**Payload**

<ResponseField name="question" type="string" required>
  The full text of the question as presented to the patient.
</ResponseField>

<ResponseField name="response_value" type="number | string | boolean" required>
  Response value. Numeric for scored items, boolean for yes/no questions, or string for categorical responses (e.g. 'daily', 'sometimes').
</ResponseField>

<ResponseField name="response_scale_max" type="number">
  Maximum value on the item response scale. Only meaningful for numeric response\_value.
</ResponseField>

<ResponseField name="response_label" type="string">
  Human-readable label for the response value.
</ResponseField>

<ResponseField name="instrument_id" type="string">
  Optional link to a known instrument if this is from a partial instrument submission.
</ResponseField>

<ResponseField name="item_number" type="integer">
  1-indexed position of this item within the instrument.
</ResponseField>

<ResponseField name="context" type="string">
  Where or how this item response was captured.. Example: `conversation`, `check_in`, `standalone`
</ResponseField>

<ResponseField name="source" type="string | object">
  Who asserted this fact. Accepts a legacy string (e.g. 'patient\_self\_report') or a structured Source object.
</ResponseField>

**Example**

<CodeGroup>
  ```python Python theme={null}
  import olira
  from olira import OliraLogType

  olira.log(
      log_type=OliraLogType.QUESTIONNAIRE_ITEM_RESPONSE,
      patient_id="your-patient-id",
      payload={
          "question": "...",
          "response_value": "..."
      },
  )
  ```

  ```http HTTP theme={null}
  POST /v1/logs/batch
  Authorization: Bearer YOUR_API_KEY
  Content-Type: application/json

  {
    "logs": [
      {
        "log_type": "questionnaire_item_response",
        "patient_id": "8a4fde23-0f1b-4c2a-9d7e-b36c1a5f0e82",
        "timestamp": "2026-03-18T09:00:00Z",
        "payload": {
          "question": "...",
          "response_value": "..."
      }
      }
    ]
  }
  ```
</CodeGroup>

<Note>
  **Related types:** Use [`questionnaire_response`](/reference/log-types/questionnaires#questionnaire-response) for full questionnaire submission, [`symptom_detail`](/reference/log-types/symptom-reports#symptom-detail) for symptom follow-up detail, [`health_metric`](/reference/log-types/symptom-reports#health-metric) for scalar metric without question text, [`mood_report`](/reference/log-types/symptom-reports#mood-report) for mood.
</Note>