# Create a medication order

Operation ID: `patient.createMedication`

Create a medication order (FHIR MedicationRequest/MedicationStatement) for the authenticated patient. Required: `name`, `route`, `dosage.value`, `dosage.unit`, `dosage.frequency`. Requires a patient Bearer JWT.

## Public method

`createMedication`

Signature: `patient.createMedication(request)`

Return type: `Promise<MedicationResponse>`

## Authentication

Classification: **AUTHENTICATED**

Schemes: `bearerAuth`

## Prerequisites

None documented.

## HTTP

`POST /patients/medications`

## Path parameters

None.

## Query parameters

None.

## Body parameters

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

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

## Request example

```json
{
  "authored_on": null,
  "brand_name": null,
  "discontinued_reason": null,
  "dosage": {
    "duration_days": null,
    "frequency": "once_daily",
    "frequency_details": null,
    "instructions": null,
    "max_daily_dose": null,
    "max_daily_dose_unit": null,
    "unit": "tablet",
    "value": 1
  },
  "encounter_id": null,
  "end_date": null,
  "generic_name": null,
  "indication": null,
  "intent": "order",
  "name": "SDK Test Medication",
  "ndc_code": null,
  "notes": null,
  "pharmacy": null,
  "prescriber_name": null,
  "refills_authorized": null,
  "refills_remaining": null,
  "resource_type": "MedicationRequest",
  "route": "oral",
  "rxnorm_code": null,
  "start_date": null,
  "status": "active"
}
```

## Success responses

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

## Success response examples

### 201

```json
{
  "authored_on": "2026-08-10",
  "brand_name": "Amoxil",
  "discontinued_reason": null,
  "dosage": {
    "duration_days": 10,
    "frequency": "once_daily",
    "frequency_details": "Every morning with food",
    "instructions": "Take one tablet by mouth each morning with food.",
    "max_daily_dose": 1,
    "max_daily_dose_unit": "tablet",
    "unit": "tablet",
    "value": 1
  },
  "encounter_id": "167dd34e-1833-4260-a8b1-ea0b38229a1b",
  "end_date": "2026-08-20",
  "fhir_id": "190e6baa-28c6-41f7-99b6-7107347478c2",
  "generic_name": "amoxicillin",
  "indication": "Acute bacterial sinusitis",
  "intent": "order",
  "medication_id": "1ce998b0-0530-470f-89bd-3f722fe9bc34",
  "name": "SDK Test Medication",
  "ndc_code": "00093-2264-01",
  "notes": "Complete the full prescribed course.",
  "pharmacy": "Example Community Pharmacy",
  "prescriber_id": "provider-example-001",
  "prescriber_name": "Dr. Alex Smith",
  "problem_reference": "condition-example-001",
  "refills_authorized": 1,
  "refills_remaining": 1,
  "resource_type": "MedicationRequest",
  "route": "oral",
  "rxnorm_code": "723",
  "start_date": "2026-08-10",
  "status": "active"
}
```

## Common errors

| Status | Shape | Content type | Description |
|---|---|---|---|
| `400` | [`patient.ErrorResponse`](../models/patient.ErrorResponse.md) | application/json | Bad request — a required field is missing or invalid |
| `401` | [`patient.ErrorResponse`](../models/patient.ErrorResponse.md) | application/json | Authorization required — missing, invalid, expired, or non-patient Bearer JWT |
| `404` | [`patient.ErrorResponse`](../models/patient.ErrorResponse.md) | application/json | The authenticated patient has no FHIR Patient record |

## Error examples

### 400 — A required field is missing

```json
{
  "error": "Missing required field: 'route'"
}
```

### 401 — Missing or invalid access token

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

### 404 — Patient not found

```json
{
  "error": "Patient not found"
}
```

## NodeJS / TypeScript implementation

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

```ts
const request = {
  "authored_on": null,
  "brand_name": null,
  "discontinued_reason": null,
  "dosage": {
    "duration_days": null,
    "frequency": "once_daily",
    "frequency_details": null,
    "instructions": null,
    "max_daily_dose": null,
    "max_daily_dose_unit": null,
    "unit": "tablet",
    "value": 1
  },
  "encounter_id": null,
  "end_date": null,
  "generic_name": null,
  "indication": null,
  "intent": "order",
  "name": "SDK Test Medication",
  "ndc_code": null,
  "notes": null,
  "pharmacy": null,
  "prescriber_name": null,
  "refills_authorized": null,
  "refills_remaining": null,
  "resource_type": "MedicationRequest",
  "route": "oral",
  "rxnorm_code": null,
  "start_date": null,
  "status": "active"
};

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

## cURL

```bash
curl -X POST \
  -H 'Authorization: Bearer <ACCESS_TOKEN>' \
  -H 'Content-Type: application/json' \
  -d '{"authored_on":null,"brand_name":null,"discontinued_reason":null,"dosage":{"duration_days":null,"frequency":"once_daily","frequency_details":null,"instructions":null,"max_daily_dose":null,"max_daily_dose_unit":null,"unit":"tablet","value":1},"encounter_id":null,"end_date":null,"generic_name":null,"indication":null,"intent":"order","name":"SDK Test Medication","ndc_code":null,"notes":null,"pharmacy":null,"prescriber_name":null,"refills_authorized":null,"refills_remaining":null,"resource_type":"MedicationRequest","route":"oral","rxnorm_code":null,"start_date":null,"status":"active"}' \
  'https://dev-api-patient.health.cloud/patients/medications'
```

## Notes

- The response includes both `medication_id` (a service-internal identifier) and `fhir_id` (the FHIR resource id). Use `fhir_id` for subsequent `getMedication`/`updateMedication` calls — `medication_id` is informational only and will 404 if used as the path id. 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.