# Submit a questionnaire response

Operation ID: `patient.createQuestionnaireResponse`

Create a FHIR QuestionnaireResponse for the given Questionnaire. `patient_id` is required in the body because a field agent or provider may submit a response on behalf of a different patient; a PATIENT-pool caller may only target their own FHIR patient id (403 on mismatch). Requires a Bearer JWT (any authenticated pool type).

## Public method

`createQuestionnaireResponse`

Signature: `patient.createQuestionnaireResponse(questionnaireId, request)`

Return type: `Promise<QuestionnaireResponseCreated>`

## Authentication

Classification: **AUTHENTICATED**

Schemes: `bearerAuth`

## Prerequisites

None documented.

## HTTP

`POST /questionnaires/{questionnaire_id}/responses`

## Path parameters

| Name | Type | Required | Format | Allowed values | Default | Nullable | Description |
|---|---|---:|---|---|---|---:|---|
| `questionnaire_id` | `string` | Yes |  |  |  | No |  |

## Query parameters

None.

## Body parameters

| Name | Type | Required | Format | Allowed values | Default | Nullable | Description |
|---|---|---:|---|---|---|---:|---|
| `body` | [`CreateQuestionnaireResponseRequest`](../models/CreateQuestionnaireResponseRequest.md) | Yes |  |  |  | No |  |

Request model: [`CreateQuestionnaireResponseRequest`](../models/CreateQuestionnaireResponseRequest.md)

## Request example

```json
{
  "encounter_id": "6e0d484f-4f8b-4025-b6ef-abedf69f0f91",
  "items": [
    {
      "answers": [],
      "link_id": "sdk-q1"
    }
  ],
  "patient_id": "patient-example-001",
  "status": "completed"
}
```

## Success responses

| Status | Shape | Content type | Description |
|---|---|---|---|
| `201` | [`CreateQuestionnaireResponseResponse`](../models/CreateQuestionnaireResponseResponse.md) | application/json | Questionnaire response created |

## Success response examples

### 201

```json
{
  "fhir_id": "3208a464-3412-405e-98a7-b93cd0fc2145"
}
```

## Common errors

| Status | Shape | Content type | Description |
|---|---|---|---|
| `400` | [`patient.ErrorResponse`](../models/patient.ErrorResponse.md) | application/json | Bad request — patient_id is missing, or the answers failed validation |
| `401` | [`patient.ErrorResponse`](../models/patient.ErrorResponse.md) | application/json | Authorization required — missing or invalid Bearer JWT |
| `403` | [`patient.ErrorResponse`](../models/patient.ErrorResponse.md) | application/json | A PATIENT-pool caller attempted to submit a response for another patient |

## Error examples

### 400 — patient_id is required

```json
{
  "error": "patient_id is required (FHIR Patient resource ID)"
}
```

### 401 — Missing or invalid access token

```json
{
  "error": "Authorization required"
}
```

### 403 — Cannot act on another patient's data

```json
{
  "error": "Cannot act on another patient's data"
}
```

## NodeJS / TypeScript implementation

```ts
import { HCSDK } from "@healthcloudai/hc-sdk";
import type { CreateQuestionnaireResponseRequest } from "@healthcloudai/hc-sdk";
```

```ts
const questionnaireId = "<QUESTIONNAIRE_ID>";

const request = {
  "encounter_id": "6e0d484f-4f8b-4025-b6ef-abedf69f0f91",
  "items": [
    {
      "answers": [],
      "link_id": "sdk-q1"
    }
  ],
  "patient_id": "patient-example-001",
  "status": "completed"
};

const result = await patient.createQuestionnaireResponse(questionnaireId, request);
```

## cURL

```bash
curl -X POST \
  -H 'Authorization: Bearer <ACCESS_TOKEN>' \
  -H 'Content-Type: application/json' \
  -d '{"encounter_id":"6e0d484f-4f8b-4025-b6ef-abedf69f0f91","items":[{"answers":[],"link_id":"sdk-q1"}],"patient_id":"patient-example-001","status":"completed"}' \
  'https://dev-api-patient.health.cloud/questionnaires/%3CQUESTIONNAIRE_ID%3E/responses'
```

## Notes

- If supplying `encounter_id` in the request body, it must be the encounter's `fhir_id` from `createEncounter`'s response, not its service-internal `encounter_id` — the latter causes a `FHIR 400: Bad Request`. Confirmed live against DEV on 2026-08-10.

## Prepared Test Console scenario

No canonical scenario is currently associated.

## Real response

No approved real integration response is currently published. Unapproved candidates are never rendered as examples.