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
Responses
- 200
The orders suggested from the note.
Operation spec
{
"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](/next/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"
}
}
}
}
}
}