---
title: "Create a medication"
method: POST
path: "/api/2026-01-01/medical-record/medications"
tags: ["Medications"]
---

# Create a medication

`POST /api/2026-01-01/medical-record/medications`

## Request

- Base URL: `https://jdpdocsdemo.jane.qa`
- URL: `https://jdpdocsdemo.jane.qa/api/2026-01-01/medical-record/medications`
- Auth: OAuth 2
  - Authorization code: `https://login.id.janeapp.com/realms/jane_partner_sandbox/protocol/openid-connect/auth?response_type=code&resource=https://jdpdocsdemo.jane.qa&prompt=consent`
  - Token URL: `https://login.id.janeapp.com/realms/jane_partner_sandbox/protocol/openid-connect/token` scopes: `medications:create`

Create a new medication record for a patient

## Request body

- CreateMedicationRequest
  - `data` MedicationEditableProperties, required: Common editable properties for medication create and update operations
    - `encounter_id` string, uuid, nullable: Reference to the encounter where medication was prescribed
    - `medication_code` MedicationCode
      - `coding` object[], nullable: Array of coded values for the medication (optional — manually added meds won't have formal codes)
        - `display` string, required: Human-readable display name
        - `code` string, required: The medication code
        - `system` string, required: The coding system (e.g., 'http://snomed.info/sct')
      - `text` string, required: Plain text representation of the medication name
    - `ingredients` Ingredient[], nullable: Array of ingredient objects (optional — not all medications have detailed ingredient info)
      - `name` string, nullable: Name of the ingredient
      - `strength` union: Strength or amount of the ingredient
        - string
        - number
      - `strength_unit` string, nullable: Unit of measurement for the strength (e.g., mg, mL, %)
    - `dose_form` string, nullable: Pharmaceutical form (tablet, capsule, suspension, etc.)
    - `route` string, nullable: Route of administration (oral, IV, topical, etc.)
    - `frequency` string, nullable: Textual frequency (daily, bid, etc.)
    - `quantity` integer, nullable: Number of units (e.g., tablets, capsules) dispensed
    - `period_start` string, date, nullable: When the medication course starts
    - `period_end` string, date, nullable: Planned end date (if any)
    - `instructions` string, nullable: Free-text administration instructions for the patient
    - `status` 'active' | 'inactive': Lifecycle state of the medication
    - `source` 'patient_reported' | 'external_provider' | 'clinic_practitioner': Origin of record – patient_reported (self-reported), external_provider (prescribed by outside clinic/doctor), or clinic_practitioner (recommended by the clinician)
    - `external_provider_type` 'family_doctor_gp' | 'specialist' | 'pharmacist' | 'nd' | 'other' | 'null', nullable: Type of external provider; required when source is external_provider, must be absent otherwise
    - `change_reason` string, nullable: Selected reason for status change (e.g., adverse_reaction, completed, patient_request)
    - `prescription_valid_until` string, date, nullable: Expiry date after which repeats aren't valid
    - `prescription_refills` integer, nullable: Allowed refill count
    - `prescription_days_supply` integer, nullable: Number of days that the dispensed medication is intended to last
    - `prescription_reason` string, nullable: Clinical indication or problem being treated
    - `document_ids` string[]: Array of document upload IDs to attach to the medication. All documents must exist and be verified.

## Response `201`

The medication was created

- Medication
  - `id` string, uuid, required: UUIDv7 identifier for the medication
  - `patient_id` string, uuid, required: Reference to the patient
  - `practitioner_id` string, uuid, nullable: Reference to the practitioner
  - `practitioner_name` string, nullable: Full name of the documenting practitioner; null when no staff is associated
  - `encounter_id` string, uuid, nullable: Reference to the encounter where medication was prescribed (optional)
  - `medication_code` MedicationCode, required
    - `coding` object[], nullable: Array of coded values for the medication (optional — manually added meds won't have formal codes)
      - `display` string, required: Human-readable display name
      - `code` string, required: The medication code
      - `system` string, required: The coding system (e.g., 'http://snomed.info/sct')
    - `text` string, required: Plain text representation of the medication name
  - `ingredients` Ingredient[], nullable: Array of ingredient objects (optional — not all medications have detailed ingredient info)
    - `name` string, nullable: Name of the ingredient
    - `strength` union: Strength or amount of the ingredient
      - string
      - number
    - `strength_unit` string, nullable: Unit of measurement for the strength (e.g., mg, mL, %)
  - `dose_form` string, nullable: Pharmaceutical form (tablet, capsule, suspension, etc.) (optional)
  - `route` string, nullable: Route of administration (oral, IV, topical, etc.) (optional)
  - `frequency` string, nullable: Textual frequency (daily, bid, etc.) (optional)
  - `quantity` integer, nullable: Number of units (e.g., tablets, capsules) dispensed
  - `period_start` string, date, nullable: When the medication course starts (optional)
  - `period_end` string, date, nullable: Planned end date (if any) (optional)
  - `instructions` string, nullable: Free-text administration instructions for the patient (optional)
  - `status` 'active' | 'inactive' | 'pending', required: Lifecycle state of the medication
  - `source` 'prescribed' | 'patient_reported' | 'external_provider' | 'clinic_practitioner', required: Origin of record – prescribed (from practitioner), patient_reported (self-reported), external_provider (prescribed by outside clinic/doctor), or clinic_practitioner (recommended by the clinician)
  - `external_provider_type` 'family_doctor_gp' | 'specialist' | 'pharmacist' | 'nd' | 'other' | 'null', nullable: Type of external provider; present when source is external_provider
  - `change_reason` string, nullable: Selected reason for status change (e.g., adverse_reaction, completed, patient_request)
  - `prescription_valid_until` string, date, nullable: Expiry date after which repeats aren't valid (optional)
  - `prescription_refills` integer, nullable: Allowed refill count (optional)
  - `prescription_days_supply` integer, nullable: Number of days that the dispensed medication is intended to last (optional)
  - `prescription_reason` string, nullable: Clinical indication or problem being treated (optional)
  - `created_at` string, date-time, required: When the medication record was created
  - `updated_at` string, date-time, required: When the medication record was last updated
  - `documents` object[], required: Array of document upload objects (each containing an id) currently attached to the medication.
    - `id` string, uuid, required

## Other responses

- `400`: The medication was not created - validation error
- `401`: Unauthorized
- `403`: Forbidden - insufficient permissions
- `404`: Patient not found

## Changes

- **2026-11-03** `01798f613a5e`: 3 breaking, 4 warning, 8 info
  - removed the enum value `prescribed` of the request property `data/allOf[subschema #1: Medication Editable Properties]/source`
  - the response property `practitioner_id` became nullable for the status `201`
  - the response property `practitioner_id` became optional for the status `201`
  - removed the optional property `object` from the response with the `400` status
  - …11 more

[Operation history](https://skmtc.dev/jane/apis/jdp-api/changes/api/2026-01-01/medical-record/medications/post.md)

---

[API](https://skmtc.dev/jane/apis/jdp-api.md) - [All operations](https://skmtc.dev/jane/apis/jdp-api/llms.txt) - [OpenAPI document](https://skmtc.dev/jane/apis/jdp-api/revisions/01798f613a5e?raw)