Extract Observations from a QuestionnaireResponse

Generate FHIR Observation resources from a saved QuestionnaireResponse. The Questionnaire must define which answers to extract, for example with the FHIR Structured Data Capture observation-extract extension and a coded item.

Method	Path
POST	/fhir/R4/QuestionnaireResponse/:id/$extract

First populate and save a QuestionnaireResponse, then pass its saved resource id as :id. The operation reads the answers and questionnaire metadata to construct Observations.

Request

The Alpha reference sends the resource id in the path and no request body.

curl --request POST \
  --url "https://api.sandbox.ovok.com/fhir/R4/QuestionnaireResponse/${QUESTIONNAIRE_RESPONSE_ID}/\$extract" \
  --header "Authorization: Bearer ${OVOK_TOKEN}"

Example of the saved resource the operation reads:

{
  "resourceType": "QuestionnaireResponse",
  "id": "<questionnaire-response-id>",
  "status": "in-progress",
  "questionnaire": "https://api.sandbox.ovok.com/fhir/R4/Questionnaire/<questionnaire-id>|0.1.0",
  "subject": {
    "type": "Patient",
    "reference": "Patient/<patient-id>"
  },
  "item": [
    {
      "linkId": "bmi-calculation",
      "item": [
        {
          "linkId": "bmi-result",
          "answer": [{ "valueDecimal": 32.7 }]
        }
      ]
    }
  ]
}

The answer's linkId must correspond to a Questionnaire item configured for extraction. The item's code supplies the Observation code, and the QuestionnaireResponse's subject supplies the patient reference.

Successful response

The operation returns a FHIR Parameters resource. Its response parameter contains a transaction Bundle with a POST Observation entry for each extracted result.

Response path	Example	Meaning
resourceType	Parameters	FHIR wrapper for the operation output.
parameter[name=response].resource.resourceType	Bundle	The named response parameter contains the generated output Bundle.
parameter[name=response].resource.type	transaction	The Bundle describes FHIR writes.
parameter[name=response].resource.entry[].request	POST Observation	Method and resource type to use when submitting the Bundle.
...entry[].resource.resourceType	Observation	Resource generated from each configured answer.
...entry[].resource.status	final	Status assigned to the generated Observation.
...entry[].resource.code.coding[0]	SNOMED CT 60621009 — Body mass index	Coded clinical concept from the Questionnaire item.
...entry[].resource.subject.reference	Patient/<patient-id>	Patient identified by the source QuestionnaireResponse.
...entry[].resource.derivedFrom[].reference	QuestionnaireResponse/<questionnaire-response-id>	Links the Observation to the response that supplied the answer.
...entry[].resource.valueQuantity.value	32.7	Extracted answer value.

The response provides the transaction Bundle; submit that Bundle to the FHIR endpoint if you want the generated Observations written to the project.

Responses and errors

HTTP status	Meaning
200	Request succeeded; the result contains a transaction Bundle of extracted Observations.
400	The request could not be operated on by the server. Check the QuestionnaireResponse and extraction configuration.
401	The resource owner or authorization server denied the request. Check the access token and its permissions.
404	The QuestionnaireResponse or a referenced resource could not be found. Check the path id and references.
422	The server could not validate the request. Check the QuestionnaireResponse and Questionnaire item configuration.
500	The server encountered an unexpected condition. Retry later or provide the request ID to support.

Errors are returned as a FHIR OperationOutcome; its issue entries describe the failure. Exact diagnostics depend on the request and server state.

Source: Alpha API reference: Extract observations from QuestionnaireResponse.