# Create an encounter

Operation ID: `patient.createEncounter`

Create a FHIR Encounter for a patient. `patient_id` is required in the body because a field agent or provider may create an encounter 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

`createEncounter`

Signature: `patient.createEncounter(request)`

Return type: `Promise<EncounterResponse>`

## Authentication

Classification: **AUTHENTICATED**

Schemes: `bearerAuth`

## Prerequisites

None documented.

## HTTP

`POST /encounters`

## Path parameters

None.

## Query parameters

None.

## Body parameters

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

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

## Request example

```json
{
  "appointment_id": null,
  "created_by": "self",
  "created_date": null,
  "diagnoses": [],
  "encounter_class": "AMB",
  "encounter_id": "167dd34e-1833-4260-a8b1-ea0b38229a1b",
  "fhir_id": null,
  "hospitalization": null,
  "length_minutes": null,
  "locations": [],
  "participants": [],
  "patient_id": "patient-example-001",
  "period_end": null,
  "period_start": null,
  "priority_code": null,
  "priority_display": null,
  "reason_code": null,
  "reason_display": null,
  "service_provider_display": null,
  "service_provider_id": null,
  "service_type_code": null,
  "service_type_display": null,
  "status": "planned",
  "type_code": null,
  "type_display": null
}
```

## Success responses

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

## Success response examples

### 201

```json
{
  "appointment_id": "string",
  "athena_appointment_id": "string",
  "athena_encounter_id": "string",
  "created_by": "self",
  "created_date": "2026-01-01T09:00:00Z",
  "diagnoses": [
    {
      "condition_display": "string",
      "condition_id": "string",
      "rank": 1,
      "use_code": "CC"
    }
  ],
  "encounter_class": "AMB",
  "encounter_id": "00000000-0000-0000-0000-000000000000",
  "fhir_id": "string",
  "hospitalization": {
    "admit_source_code": "string",
    "destination_id": "string",
    "discharge_disposition": "home",
    "origin_id": "string",
    "pre_admission_id": "string",
    "re_admission_code": "string"
  },
  "length_minutes": 0,
  "locations": [
    {
      "location_display": "string",
      "location_id": "string",
      "period_end": "2026-01-01T09:00:00Z",
      "period_start": "2026-01-01T09:00:00Z",
      "status": "active"
    }
  ],
  "notes": "string",
  "openloop_appointment_id": "string",
  "openloop_encounter_id": "string",
  "participants": [
    {
      "participant_type": "PPRF",
      "period_end": "2026-01-01T09:00:00Z",
      "period_start": "2026-01-01T09:00:00Z",
      "practitioner_display": "string",
      "practitioner_id": "string"
    }
  ],
  "patient_id": "string",
  "period_end": "2026-01-01T09:00:00Z",
  "period_start": "2026-01-01T09:00:00Z",
  "priority_code": "string",
  "priority_display": "string",
  "reason_code": "string",
  "reason_display": "string",
  "service_provider_display": "string",
  "service_provider_id": "string",
  "service_type_code": "string",
  "service_type_display": "string",
  "status": "planned",
  "steadymd_consult_guid": "string",
  "steadymd_episode_guid": "string",
  "type_code": "string",
  "type_display": "string"
}
```

## Common errors

| Status | Shape | Content type | Description |
|---|---|---|---|
| `400` | [`patient.ErrorResponse`](../models/patient.ErrorResponse.md) | application/json | Bad request — patient_id is missing, or the body 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 create an encounter 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 { CreateEncounterRequest } from "@healthcloudai/hc-sdk";
```

```ts
const request = {
  "appointment_id": null,
  "created_by": "self",
  "created_date": null,
  "diagnoses": [],
  "encounter_class": "AMB",
  "encounter_id": "167dd34e-1833-4260-a8b1-ea0b38229a1b",
  "fhir_id": null,
  "hospitalization": null,
  "length_minutes": null,
  "locations": [],
  "participants": [],
  "patient_id": "patient-example-001",
  "period_end": null,
  "period_start": null,
  "priority_code": null,
  "priority_display": null,
  "reason_code": null,
  "reason_display": null,
  "service_provider_display": null,
  "service_provider_id": null,
  "service_type_code": null,
  "service_type_display": null,
  "status": "planned",
  "type_code": null,
  "type_display": null
};

const result = await patient.createEncounter(request);
```

## cURL

```bash
curl -X POST \
  -H 'Authorization: Bearer <ACCESS_TOKEN>' \
  -H 'Content-Type: application/json' \
  -d '{"appointment_id":null,"created_by":"self","created_date":null,"diagnoses":[],"encounter_class":"AMB","encounter_id":"167dd34e-1833-4260-a8b1-ea0b38229a1b","fhir_id":null,"hospitalization":null,"length_minutes":null,"locations":[],"participants":[],"patient_id":"patient-example-001","period_end":null,"period_start":null,"priority_code":null,"priority_display":null,"reason_code":null,"reason_display":null,"service_provider_display":null,"service_provider_id":null,"service_type_code":null,"service_type_display":null,"status":"planned","type_code":null,"type_display":null}' \
  'https://dev-api-patient.health.cloud/encounters'
```

## Notes

- The response includes both `encounter_id` (a service-internal identifier) and `fhir_id` (the FHIR resource id). Use `fhir_id` for subsequent `getEncounter` calls and for the `encounter_id` field on `createQuestionnaireResponse` — the service-internal `encounter_id` will 404/400 if used there. 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.