Integrate mental health questionnaires by defining a lossless data contract, an accountable review workflow, and visible exception states before automating transfers. A total score alone is not enough. The receiving record needs the patient, encounter context, questionnaire identity and version, response status, timing, source, scoring provenance, and review state.
Begin with the clinical handoff
Map who sends the questionnaire, who completes it, who reviews it, where the original response lives, and which action the receiving system supports. Include late, partial, duplicate, amended, and misfiled results. This map is more useful than starting with a vendor feature list.
Ask what the EHR user needs to distinguish at a glance:
- Was this questionnaire assigned to the correct patient and encounter?
- Is it complete, partial, amended, or entered in error?
- Was it completed by the patient, a proxy, or a staff member?
- Which instrument version, language, and administration mode were used?
- How and when was the score calculated?
- Has a qualified person reviewed it?
A workflow that cannot answer those questions may move data quickly while making it harder to interpret safely.
Use the same contract for a PHQ-9, a GAD-7, or another approved measure. The fields may vary, but identity, version, status, source, and review remain visible.
Separate the response from the derived score
The HL7 FHIR R4 QuestionnaireResponse resource represents structured questions and answers and can identify the questionnaire, subject, encounter, status, authored time, author, and source. It can represent a response that is complete or still in progress. That makes it a useful model for preserving what was actually asked and answered.
A calculated total is different from the response itself. The FHIR Observation definition allows an Observation to be derived from a QuestionnaireResponse. Keeping that relationship explicit lets a receiving system trace a score back to its source rather than treating the number as raw input.
The exact standard and profile will depend on the connected systems, jurisdiction, and implementation guide. Even when an interface is not FHIR-based, the distinction remains useful: preserve the original response, then identify each derived result and the rules used to create it.
Define the interface contract
A practical contract should specify each field, allowed value, source of truth, validation rule, and failure behavior.
| Data element | Why it matters |
|---|---|
| Patient and encounter identifiers | Prevents a valid result from reaching the wrong chart or visit |
| Questionnaire canonical identifier, version, and language | Shows which wording and scoring rules apply |
| Response status and completeness | Keeps partial or amended data from appearing final |
| Authored time, respondent, source, and administration mode | Establishes who provided the information and under what conditions |
| Item responses, when authorized and clinically needed | Preserves detail that a total cannot recover |
| Derived score and scoring version | Makes recalculation and comparison auditable |
| Safety-routing state | Shows whether a separate response workflow was invoked |
| Review state, reviewer, and review time | Distinguishes availability from clinical review |
| Provenance, corrections, and superseded identifiers | Makes retries and amendments traceable |
Do not collapse “received” and “reviewed” into one status. A result can exist in the chart without any clinician having seen it. Likewise, an interface acknowledgment proves technical receipt, not clinical action.
Choose an integration method that fits the workflow
Native EHR questionnaires may reduce system boundaries, but still need version, scoring, accessibility, and exception review. A third-party interface may offer a broader library or different patient experience, but adds identity matching, data-transfer, contracting, and monitoring responsibilities. Custom interfaces add control and maintenance obligations. Structured manual entry can be appropriate when volume and risk controls support it, provided the record identifies the source and a second check catches transcription errors.
Evaluate each method against the same handoff. Avoid assuming that a direct connection is complete because a total appears in the chart. Verify whether item responses, status, provenance, corrections, and reviewer state also survive the transfer.
For remote collection, the teletherapy assessment guide covers mode suitability, privacy, accessibility, and documentation before the result reaches the interface.
Make failures visible
Define what the systems do when identifiers do not match, an encounter is missing, the same message arrives twice, a response is incomplete, a score cannot be calculated, or the destination is unavailable. Queue uncertain records for reconciliation rather than guessing. Keep enough information to retry without creating duplicates.
Use non-patient test data to exercise:
- a routine complete response;
- a partial response without a total;
- a late response after the encounter closes;
- a correction that supersedes an earlier record;
- a duplicate delivery and safe retry;
- a wrong-patient or ambiguous match;
- a scoring-version mismatch; and
- downtime followed by recovery.
If a questionnaire contains an answer concerning suicide or self-harm, test that route separately. The individual answer needs the organization's written safety response even when the total is low, unavailable, or delayed. A screen can signal the need for direct assessment; it cannot determine current risk.
If you need help now. In the US, Call 988 or text 988. Call 911 if you are in immediate danger. Outside the US, contact your local emergency number or find support in your country.
The EHR should show the state of that response without pretending that an automated flag completed the assessment. Define backup coverage, unreachable-patient handling, documentation, and downtime procedures before launch.
Design the human review
Place results where the responsible role already works, but do not scatter uncontrolled copies across notes, flowsheets, and inboxes. Identify one source of truth and define how other views reference it. If a note imports a result, include enough context to show the instrument, date, status, and source without implying that the author independently verified every answer.
A score can support an interview or longitudinal review. It does not diagnose a disorder, select treatment, or prove that care caused a change. The between-appointment psychiatry guide explains how to use repeated results without turning correlation into a medication claim.
Validate before and after release
Before launch, reconcile expected source records against destination records and inspect both normal and exception paths. Confirm access controls, audit events, retention behavior, amendments, downtime recovery, and the patient-facing message about review timing. The HIPAA vendor checklist provides a broader framework for contracts, safeguards, and representative tests.
Train each role on the states they own and the conditions they escalate. The staff assessment training guide offers a role-based test plan. Repeat interface validation after a questionnaire version, scoring rule, EHR configuration, identity service, or routing process changes.