Questionnaires

Structured instrument submissions and scored questionnaires. Submit these via POST /v1/logs/batch or the Python SDK; see 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

instrument

object

required

Show fields

instrument_id

string

required

Instrument identifier.. Example: PHQ-9, GAD-7, FACT-G

instrument_type

string

required

Whether this is a standardised validated instrument or a custom one.. Example: validated, custom

instrument_version

string

Version string of the instrument.

recall_period_days

integer

Recall window in days (e.g. PHQ-9 = 14, GAD-7 = 14). Resolved from registry for standard instruments.

administration

object

required

Show fields

administration_mode

string

required

Who completed the questionnaire.. Example: patient_self_report, clinician_administered, caregiver_proxy

platform

string

The platform on which the questionnaire was administered.. Example: mobile_app, web, paper_transcribed

language

string

BCP 47 language tag (e.g. en-US).

completion_time_seconds

number

Time taken to complete, in seconds.

items_completed

integer

Number of items completed.

items_skipped

integer

Number of items skipped.

administered_by

object

Show fields

name

string

Name of person who administered; required when mode is not patient_self_report.

npi

string

NPI of administrator if applicable.

role

string

Role of administrator.

item_responses

object[]

required

Show fields

item_number

integer

required

1-indexed item number.

item_text

string

Question text. Required for custom instruments; optional for standard instruments (resolved from registry).

response_value

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’).

response_label

string

Human-readable label for the response (e.g. ‘More than half the days’).

response_scale_max

number

Maximum value of the item response scale. Only meaningful for numeric response_value.

scores

object

required

Show fields

total_score

number

Total instrument score. Only set when all item response_values are numeric; omit for non-numeric questionnaires.

total_score_max

number

Maximum possible total score. For standard instruments this is computed internally.

severity_category

string

Severity interpretation (e.g. mild, moderate, severe).. Example: minimal, mild, moderate

domain_scores

object

Map of domain name to domain score for multi-domain instruments.

clinically_significant

boolean

Whether the total score meets or exceeds the clinical significance threshold.

significance_threshold

number

Score threshold for clinical significance. Resolved from registry for standard instruments.

change

object

Change from prior administration.

Show fields

prior_score

number

Score from prior administration.

prior_date

string

Date of prior administration.

change

number

Numeric change in score.

minimally_important_difference

number

MID for this instrument; used to interpret change.

change_classification

string

Direction of change relative to prior score.. Example: improved, stable, worsened

extensions

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

source

string | object

Who asserted this fact. Accepts a legacy string (e.g. ‘patient_self_report’) or a structured Source object.

Example

import olira
from olira import OliraLogType

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

Related types: Use questionnaire_item_response for single question and answer, mood_report for mood list, health_metric for single health metric, symptom_report for symptom report.

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

question

string

required

The full text of the question as presented to the patient.

response_value

number | string | boolean

required

Response value. Numeric for scored items, boolean for yes/no questions, or string for categorical responses (e.g. ‘daily’, ‘sometimes’).

response_scale_max

number

Maximum value on the item response scale. Only meaningful for numeric response_value.

response_label

string

Human-readable label for the response value.

instrument_id

string

Optional link to a known instrument if this is from a partial instrument submission.

item_number

integer

1-indexed position of this item within the instrument.

context

string

Where or how this item response was captured.. Example: conversation, check_in, standalone

source

string | object

Who asserted this fact. Accepts a legacy string (e.g. ‘patient_self_report’) or a structured Source object.

Example

import olira
from olira import OliraLogType

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

Related types: Use questionnaire_response for full questionnaire submission, symptom_detail for symptom follow-up detail, health_metric for scalar metric without question text, mood_report for mood.

​Questionnaire response

​Questionnaire item response

Questionnaire response

Questionnaire item response