# Generate suggested orders from a note ``` POST /generate-suggested-orders ``` Generate suggested orders from a Nabla-generated clinical note. The endpoint extracts the orders explicitly mentioned in the note — laboratory tests, imaging studies, medications, procedures, referrals, immunizations and durable medical equipment — and returns them as a flat list of suggestions discriminated by `category`, each with a short `description` and optional `details`. `MEDICATION` orders additionally carry the prescription fields extracted from the note (`action`, `dose_value`, `dose_unit`, `prn`, `frequency_times_per_period`, `frequency_period_length`, `frequency_period_unit`, `route`), summarized in their `details`. Suggested orders are meant to be reviewed by the provider before being placed in the EHR. ## Request[​](#request "Direct link to request") ## Responses[​](#responses "Direct link to Responses") * 200 The orders suggested from the note. ## Operation spec ```json { "method": "post", "path": "/generate-suggested-orders", "operationId": "generate-suggested-orders", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "description": "Input for suggested orders generation.", "properties": { "note": { "description": "The Nabla-generated clinical note to extract suggested orders from.", "type": "object", "properties": { "title": { "type": "string", "description": "Title of the note.", "example": "Fever and strong headache" }, "sections": { "type": "array", "description": "Sections of the note.", "items": { "type": "object", "description": "A note section.", "properties": { "key": { "type": "string", "description": "A key identifying a section of a note.\nThe set of possible keys depend on the template that is used. Check [Note template](/core-api/guides/note-templates/note-templates-sections) for possible values.", "example": "CHIEF_COMPLAINT", "title": "note_section_key" }, "title": { "type": "string", "description": "The section title.", "example": "Chief complaint" }, "content": { "oneOf": [ { "title": "TEXT", "type": "object", "description": "Plain-text note section content.", "required": [ "type", "text" ], "properties": { "type": { "type": "string", "enum": [ "TEXT" ] }, "text": { "type": "string", "description": "Content of the note section." } } }, { "title": "SUBSECTIONS", "type": "object", "description": "Structured note section content as subsections.", "required": [ "type", "subsections" ], "properties": { "type": { "type": "string", "enum": [ "SUBSECTIONS" ] }, "subsections": { "type": "array", "minItems": 1, "description": "Structured subsections. Allowed only on the Assessment & Plan section of A&P-merged templates. Order is significant.", "items": { "type": "object", "description": "A subsection of a note section. Currently only used on the Assessment & Plan section of A&P-merged templates.", "properties": { "id": { "description": "Stable identifier for this subsection. Echoed on normalized conditions via `subsection_id`.", "type": "string", "format": "uuid", "example": "98FCE1EF-DBCA-41EF-8BC7-4D1621AC07C6", "title": "uuid" }, "title": { "type": "string", "description": "Short subsection title (typically a clinical problem name). May be absent (e.g. subsections appended by dot phrase auto-apply)." }, "text": { "type": "string", "description": "Free-text content of the subsection. May be absent if the subsection only carries a title." } }, "required": [ "id" ], "title": "note_section_subsection_request" } } } } ], "discriminator": { "propertyName": "type", "mapping": { "TEXT": { "type": "object", "description": "Plain-text note section content.", "required": [ "type", "text" ], "properties": { "type": { "type": "string", "enum": [ "TEXT" ] }, "text": { "type": "string", "description": "Content of the note section." } }, "title": "note_section_content_text_request" }, "SUBSECTIONS": { "type": "object", "description": "Structured note section content as subsections.", "required": [ "type", "subsections" ], "properties": { "type": { "type": "string", "enum": [ "SUBSECTIONS" ] }, "subsections": { "type": "array", "minItems": 1, "description": "Structured subsections. Allowed only on the Assessment & Plan section of A&P-merged templates. Order is significant.", "items": { "type": "object", "description": "A subsection of a note section. Currently only used on the Assessment & Plan section of A&P-merged templates.", "properties": { "id": { "description": "Stable identifier for this subsection. Echoed on normalized conditions via `subsection_id`.", "type": "string", "format": "uuid", "example": "98FCE1EF-DBCA-41EF-8BC7-4D1621AC07C6", "title": "uuid" }, "title": { "type": "string", "description": "Short subsection title (typically a clinical problem name). May be absent (e.g. subsections appended by dot phrase auto-apply)." }, "text": { "type": "string", "description": "Free-text content of the subsection. May be absent if the subsection only carries a title." } }, "required": [ "id" ], "title": "note_section_subsection_request" } } }, "title": "note_section_content_subsections_request" } } }, "title": "note_section_content_request" } }, "required": [ "key", "title", "content" ], "title": "note_section_request" } }, "locale": { "type": "string", "description": "Locale of the note.", "enum": [ "ENGLISH_US", "ENGLISH_UK", "FRENCH_FR" ], "example": "ENGLISH_US", "title": "note_locale" }, "template_key": { "type": "string", "description": "Human-readable identifier for the note template used to generate this note." } }, "required": [ "sections", "locale", "template_key" ], "title": "note_request" }, "encounter_diagnoses_coding": { "type": "array", "description": "The ICD-10 coding for the patient's active encounter diagnoses. Used as additional context to suggest orders relevant to the diagnoses addressed during the encounter.", "items": { "type": "object", "description": "An ICD-10 entry.", "properties": { "system": { "type": "string", "description": "The used coding system, only ICD-10 is supported for now.", "enum": [ "http://hl7.org/fhir/sid/icd-10-cm" ] }, "code": { "type": "string", "example": "G44.8", "description": "Code of the [ICD-10](https://www.icd10data.com/ICD10CM/Codes) entry." }, "display": { "type": "string", "example": "Other specified headache syndromes.", "description": "Description of the [ICD-10](https://www.icd10data.com/ICD10CM/Codes) entry." } }, "required": [ "code", "display", "system" ], "title": "icd10_entry_request" } }, "patient_demographics": { "type": "object", "description": "Demographic details about the patient.", "properties": { "name": { "type": "string", "description": "The patient's name." }, "birth_date": { "type": "string", "format": "date", "description": "The patient's birthdate (YYYY-MM-DD format).", "example": "1996-03-21" }, "gender": { "type": "string", "enum": [ "MALE", "FEMALE", "OTHER" ], "description": "The patient's gender.", "title": "gender" }, "pronouns": { "type": "string", "enum": [ "HE_HIM", "SHE_HER", "THEY_THEM" ], "description": "The patient's pronouns.", "title": "pronouns" } }, "required": [ "name" ], "title": "patient_demographics" }, "source_note": { "description": "The note used as a starting point for the encounter (e.g. the provider's draft or the patient's last signed note). Its `ASSESSMENT_AND_PLAN` section is used as additional context to distinguish new orders from pre-existing ones. Only the `ASSESSMENT_AND_PLAN` section is used: sections of other kinds (e.g. separate `ASSESSMENT` and `PLAN` sections) do not contribute to the suggestions. The source note is still validated as a whole, with the same rules as for note generation: each `kind` may appear at most once, `ASSESSMENT_AND_PLAN` cannot be combined with `ASSESSMENT` or `PLAN`, and `content.type: \"SUBSECTIONS\"` is only accepted on `ASSESSMENT_AND_PLAN`. Invalid source notes are rejected with a `400` error.", "type": "object", "required": [ "type", "sections" ], "properties": { "type": { "type": "string", "enum": [ "DRAFT", "LAST_SIGNED" ], "description": "Nature of the source note. `DRAFT` is the provider's in-progress note for the current encounter; `LAST_SIGNED` is the patient's most recent signed note from a previous encounter." }, "sections": { "type": "array", "description": "Semantic sections taken as a starting point for follow-up note generation. Each `kind` may appear at most once.", "items": { "type": "object", "description": "A semantic section of a source note used as input to follow-up note generation.", "required": [ "kind", "content" ], "properties": { "kind": { "type": "string", "enum": [ "ASSESSMENT_AND_PLAN", "ASSESSMENT", "PLAN" ], "description": "The semantic meaning of a section. This is independent of the template's section layout and identifies what kind of clinical content the section carries (e.g. an Assessment & Plan combined section, or a standalone Assessment or Plan).\nThe kinds listed here are subject to change: new values can be added independently of API versions. Keep your client tolerant to new enum values.", "title": "semantic_section_kind" }, "content": { "description": "Content of the section. `SUBSECTIONS` is additionally accepted on the `ASSESSMENT_AND_PLAN` kind, one subsection per clinical problem.", "oneOf": [ { "title": "TEXT", "type": "object", "description": "Plain-text note section content.", "required": [ "type", "text" ], "properties": { "type": { "type": "string", "enum": [ "TEXT" ] }, "text": { "type": "string", "description": "Content of the note section." } } }, { "title": "SUBSECTIONS", "type": "object", "description": "Structured note section content as subsections.", "required": [ "type", "subsections" ], "properties": { "type": { "type": "string", "enum": [ "SUBSECTIONS" ] }, "subsections": { "type": "array", "minItems": 1, "description": "Structured subsections. Allowed only on the Assessment & Plan section of A&P-merged templates. Order is significant.", "items": { "type": "object", "description": "A subsection of a note section. Currently only used on the Assessment & Plan section of A&P-merged templates.", "properties": { "id": { "description": "Stable identifier for this subsection. Echoed on normalized conditions via `subsection_id`.", "type": "string", "format": "uuid", "example": "98FCE1EF-DBCA-41EF-8BC7-4D1621AC07C6", "title": "uuid" }, "title": { "type": "string", "description": "Short subsection title (typically a clinical problem name). May be absent (e.g. subsections appended by dot phrase auto-apply)." }, "text": { "type": "string", "description": "Free-text content of the subsection. May be absent if the subsection only carries a title." } }, "required": [ "id" ], "title": "note_section_subsection_request" } } } } ], "discriminator": { "propertyName": "type", "mapping": { "TEXT": { "type": "object", "description": "Plain-text note section content.", "required": [ "type", "text" ], "properties": { "type": { "type": "string", "enum": [ "TEXT" ] }, "text": { "type": "string", "description": "Content of the note section." } }, "title": "note_section_content_text_request" }, "SUBSECTIONS": { "type": "object", "description": "Structured note section content as subsections.", "required": [ "type", "subsections" ], "properties": { "type": { "type": "string", "enum": [ "SUBSECTIONS" ] }, "subsections": { "type": "array", "minItems": 1, "description": "Structured subsections. Allowed only on the Assessment & Plan section of A&P-merged templates. Order is significant.", "items": { "type": "object", "description": "A subsection of a note section. Currently only used on the Assessment & Plan section of A&P-merged templates.", "properties": { "id": { "description": "Stable identifier for this subsection. Echoed on normalized conditions via `subsection_id`.", "type": "string", "format": "uuid", "example": "98FCE1EF-DBCA-41EF-8BC7-4D1621AC07C6", "title": "uuid" }, "title": { "type": "string", "description": "Short subsection title (typically a clinical problem name). May be absent (e.g. subsections appended by dot phrase auto-apply)." }, "text": { "type": "string", "description": "Free-text content of the subsection. May be absent if the subsection only carries a title." } }, "required": [ "id" ], "title": "note_section_subsection_request" } } }, "title": "note_section_content_subsections_request" } } }, "title": "note_section_content_request" } }, "title": "source_note_section" } } }, "title": "source_note" } }, "required": [ "note" ], "title": "generate_suggested_orders_request" } } } }, "responses": { "200": { "description": "The orders suggested from the note.", "content": { "application/json": { "schema": { "type": "object", "description": "The orders suggested from the clinical note.", "properties": { "orders": { "type": "array", "description": "The suggested orders, across all categories.", "items": { "description": "An order suggested from the clinical note. The `category` discriminates the concrete order type.", "oneOf": [ { "title": "LABORATORY", "type": "object", "description": "A laboratory test order (e.g. CBC, HbA1c).", "properties": { "category": { "type": "string", "enum": [ "LABORATORY" ] }, "description": { "type": "string", "description": "A short description of the order.", "example": "Complete blood count (CBC) with differential" }, "details": { "type": "string", "nullable": true, "description": "Additional details about the order, as mentioned in the note (e.g. clinical indication, priority, laterality). `null` when there are none.", "example": "Rule out anemia; fatigue and pallor on exam" } }, "required": [ "category", "description" ] }, { "title": "RADIOLOGY_IMAGING", "type": "object", "description": "An imaging study order (e.g. X-ray, CT, MRI).", "properties": { "category": { "type": "string", "enum": [ "RADIOLOGY_IMAGING" ] }, "description": { "type": "string", "description": "A short description of the order.", "example": "X-ray chest, 2 views" }, "details": { "type": "string", "nullable": true, "description": "Additional details about the order, as mentioned in the note (e.g. clinical indication, priority, laterality). `null` when there are none.", "example": "Persistent cough for 3 weeks, evaluate for pneumonia" } }, "required": [ "category", "description" ] }, { "title": "MEDICATION", "type": "object", "description": "A medication order. The prescription fields are extracted from the note and are `null` when the note does not mention them.", "properties": { "category": { "type": "string", "enum": [ "MEDICATION" ] }, "description": { "type": "string", "description": "A short description of the medication, typically its name, strength and form.", "example": "Metformin 500 mg tablet" }, "details": { "type": "string", "nullable": true, "description": "A human-readable summary of the prescription fields below, e.g. `(new) - 500 mg - 2 times per 1 day - route: oral`. `null` when none of them is set.", "example": "(new) - 500 mg - 2 times per 1 day - route: oral" }, "action": { "nullable": true, "type": "string", "description": "The action to take on the medication. - `NEW`: start a new medication. - `REORDER`: renew an existing medication as is. - `CHANGE`: change an existing medication (e.g. its dose or frequency). - `DISCONTINUE`: stop an existing medication.", "enum": [ "NEW", "REORDER", "CHANGE", "DISCONTINUE" ], "example": "NEW", "title": "suggested_order_medication_action" }, "dose_value": { "type": "number", "nullable": true, "description": "The numeric part of the dose.", "example": 500 }, "dose_unit": { "type": "string", "nullable": true, "description": "The dose unit, as a UCUM code.", "example": "mg" }, "prn": { "type": "boolean", "nullable": true, "description": "Whether the medication is to be taken as needed (_pro re nata_).", "example": false }, "frequency_times_per_period": { "type": "integer", "nullable": true, "description": "The number of administrations per period, e.g. `2` in \"2 times per 1 day\".", "example": 2 }, "frequency_period_length": { "type": "integer", "nullable": true, "description": "The length of the period, e.g. `1` in \"2 times per 1 day\".", "example": 1 }, "frequency_period_unit": { "type": "string", "nullable": true, "description": "The unit of the period, as a UCUM code (e.g. `d`, `wk`, `h`).", "example": "d" }, "route": { "type": "string", "nullable": true, "description": "The route of administration.", "example": "Oral" } }, "required": [ "category", "description" ] }, { "title": "PROCEDURE", "type": "object", "description": "A procedure order (e.g. skin lesion excision, colonoscopy).", "properties": { "category": { "type": "string", "enum": [ "PROCEDURE" ] }, "description": { "type": "string", "description": "A short description of the order.", "example": "Colonoscopy" }, "details": { "type": "string", "nullable": true, "description": "Additional details about the order, as mentioned in the note (e.g. clinical indication, priority, laterality). `null` when there are none.", "example": "Screening, family history of colorectal cancer" } }, "required": [ "category", "description" ] }, { "title": "REFERRAL", "type": "object", "description": "A referral to another provider or specialty.", "properties": { "category": { "type": "string", "enum": [ "REFERRAL" ] }, "description": { "type": "string", "description": "A short description of the order.", "example": "Cardiology referral" }, "details": { "type": "string", "nullable": true, "description": "Additional details about the order, as mentioned in the note (e.g. clinical indication, priority, laterality). `null` when there are none.", "example": "Evaluate exertional chest tightness" } }, "required": [ "category", "description" ] }, { "title": "IMMUNIZATION", "type": "object", "description": "A vaccine order.", "properties": { "category": { "type": "string", "enum": [ "IMMUNIZATION" ] }, "description": { "type": "string", "description": "A short description of the order.", "example": "Influenza vaccine, seasonal" }, "details": { "type": "string", "nullable": true, "description": "Additional details about the order, as mentioned in the note (e.g. clinical indication, priority, laterality). `null` when there are none.", "example": "Annual flu shot, patient agrees" } }, "required": [ "category", "description" ] }, { "title": "DURABLE_MEDICAL_EQUIPMENT", "type": "object", "description": "A durable medical equipment order (e.g. CPAP, wheelchair).", "properties": { "category": { "type": "string", "enum": [ "DURABLE_MEDICAL_EQUIPMENT" ] }, "description": { "type": "string", "description": "A short description of the order.", "example": "CPAP machine" }, "details": { "type": "string", "nullable": true, "description": "Additional details about the order, as mentioned in the note (e.g. clinical indication, priority, laterality). `null` when there are none.", "example": "Moderate obstructive sleep apnea confirmed by sleep study" } }, "required": [ "category", "description" ] } ], "discriminator": { "propertyName": "category", "mapping": { "LABORATORY": { "type": "object", "description": "A laboratory test order (e.g. CBC, HbA1c).", "properties": { "category": { "type": "string", "enum": [ "LABORATORY" ] }, "description": { "type": "string", "description": "A short description of the order.", "example": "Complete blood count (CBC) with differential" }, "details": { "type": "string", "nullable": true, "description": "Additional details about the order, as mentioned in the note (e.g. clinical indication, priority, laterality). `null` when there are none.", "example": "Rule out anemia; fatigue and pallor on exam" } }, "required": [ "category", "description" ], "title": "suggested_order_laboratory" }, "RADIOLOGY_IMAGING": { "type": "object", "description": "An imaging study order (e.g. X-ray, CT, MRI).", "properties": { "category": { "type": "string", "enum": [ "RADIOLOGY_IMAGING" ] }, "description": { "type": "string", "description": "A short description of the order.", "example": "X-ray chest, 2 views" }, "details": { "type": "string", "nullable": true, "description": "Additional details about the order, as mentioned in the note (e.g. clinical indication, priority, laterality). `null` when there are none.", "example": "Persistent cough for 3 weeks, evaluate for pneumonia" } }, "required": [ "category", "description" ], "title": "suggested_order_radiology_imaging" }, "MEDICATION": { "type": "object", "description": "A medication order. The prescription fields are extracted from the note and are `null` when the note does not mention them.", "properties": { "category": { "type": "string", "enum": [ "MEDICATION" ] }, "description": { "type": "string", "description": "A short description of the medication, typically its name, strength and form.", "example": "Metformin 500 mg tablet" }, "details": { "type": "string", "nullable": true, "description": "A human-readable summary of the prescription fields below, e.g. `(new) - 500 mg - 2 times per 1 day - route: oral`. `null` when none of them is set.", "example": "(new) - 500 mg - 2 times per 1 day - route: oral" }, "action": { "nullable": true, "type": "string", "description": "The action to take on the medication. - `NEW`: start a new medication. - `REORDER`: renew an existing medication as is. - `CHANGE`: change an existing medication (e.g. its dose or frequency). - `DISCONTINUE`: stop an existing medication.", "enum": [ "NEW", "REORDER", "CHANGE", "DISCONTINUE" ], "example": "NEW", "title": "suggested_order_medication_action" }, "dose_value": { "type": "number", "nullable": true, "description": "The numeric part of the dose.", "example": 500 }, "dose_unit": { "type": "string", "nullable": true, "description": "The dose unit, as a UCUM code.", "example": "mg" }, "prn": { "type": "boolean", "nullable": true, "description": "Whether the medication is to be taken as needed (_pro re nata_).", "example": false }, "frequency_times_per_period": { "type": "integer", "nullable": true, "description": "The number of administrations per period, e.g. `2` in \"2 times per 1 day\".", "example": 2 }, "frequency_period_length": { "type": "integer", "nullable": true, "description": "The length of the period, e.g. `1` in \"2 times per 1 day\".", "example": 1 }, "frequency_period_unit": { "type": "string", "nullable": true, "description": "The unit of the period, as a UCUM code (e.g. `d`, `wk`, `h`).", "example": "d" }, "route": { "type": "string", "nullable": true, "description": "The route of administration.", "example": "Oral" } }, "required": [ "category", "description" ], "title": "suggested_order_medication" }, "PROCEDURE": { "type": "object", "description": "A procedure order (e.g. skin lesion excision, colonoscopy).", "properties": { "category": { "type": "string", "enum": [ "PROCEDURE" ] }, "description": { "type": "string", "description": "A short description of the order.", "example": "Colonoscopy" }, "details": { "type": "string", "nullable": true, "description": "Additional details about the order, as mentioned in the note (e.g. clinical indication, priority, laterality). `null` when there are none.", "example": "Screening, family history of colorectal cancer" } }, "required": [ "category", "description" ], "title": "suggested_order_procedure" }, "REFERRAL": { "type": "object", "description": "A referral to another provider or specialty.", "properties": { "category": { "type": "string", "enum": [ "REFERRAL" ] }, "description": { "type": "string", "description": "A short description of the order.", "example": "Cardiology referral" }, "details": { "type": "string", "nullable": true, "description": "Additional details about the order, as mentioned in the note (e.g. clinical indication, priority, laterality). `null` when there are none.", "example": "Evaluate exertional chest tightness" } }, "required": [ "category", "description" ], "title": "suggested_order_referral" }, "IMMUNIZATION": { "type": "object", "description": "A vaccine order.", "properties": { "category": { "type": "string", "enum": [ "IMMUNIZATION" ] }, "description": { "type": "string", "description": "A short description of the order.", "example": "Influenza vaccine, seasonal" }, "details": { "type": "string", "nullable": true, "description": "Additional details about the order, as mentioned in the note (e.g. clinical indication, priority, laterality). `null` when there are none.", "example": "Annual flu shot, patient agrees" } }, "required": [ "category", "description" ], "title": "suggested_order_immunization" }, "DURABLE_MEDICAL_EQUIPMENT": { "type": "object", "description": "A durable medical equipment order (e.g. CPAP, wheelchair).", "properties": { "category": { "type": "string", "enum": [ "DURABLE_MEDICAL_EQUIPMENT" ] }, "description": { "type": "string", "description": "A short description of the order.", "example": "CPAP machine" }, "details": { "type": "string", "nullable": true, "description": "Additional details about the order, as mentioned in the note (e.g. clinical indication, priority, laterality). `null` when there are none.", "example": "Moderate obstructive sleep apnea confirmed by sleep study" } }, "required": [ "category", "description" ], "title": "suggested_order_durable_medical_equipment" } } }, "title": "suggested_order" } } }, "required": [ "orders" ], "title": "suggested_orders" } } } } } } ```