# Populate a Questionnaire

Canonical page: https://docs.ovok.com/primitives/populate-questionnaire

Populate a FHIR `QuestionnaireResponse` using a saved `Questionnaire`, its patient context, and optional values supplied by the caller. Questionnaire variables and calculated expressions can fetch or derive values while the response is assembled.

| Method | Path |
| --- | --- |
| `POST` | `/fhir/R4/Questionnaire/:id/$populate` |

Replace `:id` with the id of a `Questionnaire` already available in the project. The Questionnaire can define FHIR Structured Data Capture variables, a patient `launchContext`, and calculated-expression extensions. For example, a variable can query the latest height Observation for the active patient; a calculated expression can use height and weight answers to populate a BMI item.

## Request [#request]

The request body is a FHIR `Parameters` resource. Use `context` to pass named application data and `response` to provide an in-progress response with answers that should be retained or used in calculations.

```bash
curl --request POST \
  --url "https://api.sandbox.ovok.com/fhir/R4/Questionnaire/${QUESTIONNAIRE_ID}/\$populate" \
  --header "Authorization: Bearer ${OVOK_TOKEN}" \
  --header 'Content-Type: application/json' \
  --data @populate-parameters.json
```

Example `populate-parameters.json`:

```json
{
  "resourceType": "Parameters",
  "parameter": [
    {
      "name": "context",
      "part": [
        {
          "name": "name",
          "valueString": "myCustomVariableName"
        },
        {
          "name": "content",
          "resource": {
            "myCustomDataKey": "myCustomDataValue"
          }
        }
      ]
    },
    {
      "name": "response",
      "resource": {
        "resourceType": "QuestionnaireResponse",
        "status": "in-progress",
        "item": [
          {
            "linkId": "bmi-calculation",
            "item": [
              {
                "linkId": "patient-height",
                "answer": [{ "valueDecimal": 175 }]
              },
              {
                "linkId": "patient-weight",
                "answer": [{ "valueDecimal": 100 }]
              }
            ]
          }
        ]
      }
    }
  ]
}
```

- The outer `Parameters` resource carries inputs to the operation.
- A `context` parameter has `part` entries: `name` identifies the variable, and `content` carries its value. Questionnaire expressions can access it through `%context.<name>`.
- The `response` parameter contains an initial `QuestionnaireResponse`. Its `item` and `answer` elements provide existing answers; Questionnaire expressions can reference them while calculating new answers.
- `linkId` values connect response items to the corresponding items in the saved Questionnaire.

## Successful response [#successful-response]

The Alpha reference shows a generated `QuestionnaireResponse` example and also documents a `Parameters` response schema that wraps the response under `parameter[name=response].resource`. The schema example is shown here; inspect the returned `resourceType` and wrapper when integrating with a particular deployment.

| Response path | Example | Meaning |
| --- | --- | --- |
| `resourceType` | `Parameters` | FHIR wrapper for the operation output. |
| `parameter[name=response].resource.resourceType` | `QuestionnaireResponse` | Generated response resource inside the named output parameter. |
| `...resource.status` | `in-progress` | Status of the populated response. |
| `...resource.questionnaire` | `Questionnaire/<questionnaire-id>\|0.1.0` | Source Questionnaire canonical URL and optional version. |
| `...resource.subject.reference` | `Patient/<patient-id>` | Patient the answers belong to. |
| `...resource.item[].linkId` | `bmi-calculation`, `patient-height`, `patient-weight`, `bmi-result` | Nested items corresponding to the Questionnaire's structure. |
| `...answer[].valueDecimal` | `175`, `100`, `32.7` | Supplied or populated answers; calculated answers can be filled from Questionnaire expressions. |
| `...resource.meta.profile[]` | `http://hl7.org/fhir/uv/sdc/StructureDefinition/sdc-questionnaireresponse` | QuestionnaireResponse profile used by the implementation, when present. |

The QuestionnaireResponse is returned to the caller. Save it with a FHIR create or update request if it should persist in the project.

## Responses and errors [#responses-and-errors]

| HTTP status | Meaning |
| --- | --- |
| `200` | Request succeeded; the result contains the populated response. |
| `400` | The request could not be operated on by the server. Check the Parameters body. |
| `401` | The resource owner or authorization server denied the request. Check the access token and its permissions. |
| `404` | The Questionnaire or a referenced resource could not be found. Check the path id and references. |
| `422` | The server could not validate the request or Questionnaire. Check its FHIR structure and expressions. |
| `500` | The server encountered an unexpected condition. Retry later or provide the request ID to support. |

On error, the operation can return a FHIR `OperationOutcome` instead of a populated response. Its `issue` entries describe the failure; exact diagnostics depend on the request and server state.

Source: [Alpha API reference: Populate questionnaire](https://docs.ovok.com/alpha/api/fhir/custom-operations/fhir-controller-populate-questionnaire).
