# Extract Observations from a QuestionnaireResponse

Canonical page: https://docs.ovok.com/primitives/extract-observations

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 [#request]

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

```bash
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:

```json
{
  "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 [#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 [#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](https://docs.ovok.com/alpha/api/fhir/custom-operations/fhir-controller-extract-observations-from-questionnaire-response).
