Skip to main content

QuestionnaireResponse $extract

The $extract operation transforms completed questionnaire responses into structured FHIR resources. This bridges the gap between form-based data collection and your clinical data model-automatically converting patient intake forms, assessments, or surveys into Observations, Conditions, Procedures, and other FHIR resources.

This is a key component of the Structured Data Capture workflow, allowing you to design forms that both collect information from users and populate your FHIR database without custom mapping code.

Use Cases​

  • Patient Intake: Convert registration forms into Patient, Coverage, and RelatedPerson resources
  • Clinical Assessments: Transform PHQ-9, GAD-7, or other assessment questionnaires into Observation resources with proper coding
  • History Collection: Extract past medical history responses into Condition resources
  • Prior Authorization: Generate ServiceRequest and supporting documentation from PA request forms
  • Research Data Collection: Convert study questionnaires into Observation resources for analysis

Invoke the $extract operation​

[baseUrl]/QuestionnaireResponse/$extract
[baseUrl]/QuestionnaireResponse/[id]/$extract

Parameters​

NameTypeDescriptionRequired
questionnaire-responseQuestionnaireResponseThe response to parseNo1
questionnaireQuestionnaireThe Questionnaire to use for parsing the responseNo2

1 If not called on a specific QuestionnaireResponse by ID, the response must be specified via the questionnaire-response parameter.

2 If QuestionnaireResponse.questionnaire is not specified in the resource, it must be passed in via the questionnaire parameter; otherwise it can be used to override the Questionnaire used for parsing.

Output​

The operation returns a Bundle resource containing the resources populated from templates in the Questionnaire, derived from values in the QuestionnaireResponse.

Request:

Given a QuestionnaireResponse with an associated Questionnaire, e.g.`

{
  "resourceType": "QuestionnaireResponse",
  "id": "1c503f4e-a08c-4b7d-8ebd-bfc67b0ab761",
  "status": "completed",
  "questionnaire": "Questionnaire/f80e508b-9aaa-41e3-aa8e-0e4817c86b44"
  // ...
}
GET https://api.medplum.com/fhir/R4/QuestionnaireResponse/1c503f4e-a08c-4b7d-8ebd-bfc67b0ab761/$extract
curl 'https://api.medplum.com/fhir/R4/QuestionnaireResponse/1c503f4e-a08c-4b7d-8ebd-bfc67b0ab761/$extract' \
  -H "Authorization: Bearer $MY_ACCESS_TOKEN"

Response (200 OK):

{
  "resourceType": "Bundle",
  "type": "transaction",
  "entry": [
    // Populated template resources
  ]
}