Generate suggested orders from a note asynchronously
POST/generate-suggested-orders-async
Start an asynchronous job to generate suggested orders from a Nabla-generated clinical note.
The job 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.
Poll the status and results using the GET /generate-suggested-orders-async/{id} endpoint with the returned id. The result is kept for two hours.
If your organization has set up webhooks, a generate_suggested_orders_async.succeeded or generate_suggested_orders_async.failed event is also sent when the job completes.
Request
Responses
- 200
Request received and processing started.
Operation spec
{
"method": "post",
"path": "/generate-suggested-orders-async",
"operationId": "generate-suggested-orders-async",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"allOf": [
{
"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"
},
{
"type": "object",
"properties": {
"client_request_id": {
"type": "string",
"maxLength": 128,
"description": "An optional unique client-made id for this request. When specified, this id is included in the Json payload that will be sent asynchronously. This can help clients both guarantee idempotency and correlate asynchronous responses with their requests.\n\n_Note_: this id must be different for every request. It is recommended to use a randomly generated UUID.",
"title": "client_request_id"
}
}
}
],
"title": "generate_suggested_orders_async_request"
}
}
}
},
"responses": {
"200": {
"description": "Request received and processing started.",
"content": {
"application/json": {
"schema": {
"oneOf": [
{
"title": "ONGOING",
"type": "object",
"properties": {
"id": {
"description": "The id of the asynchronous request.",
"type": "string",
"format": "uuid",
"example": "98FCE1EF-DBCA-41EF-8BC7-4D1621AC07C6",
"title": "uuid"
},
"client_request_id": {
"type": "string",
"maxLength": 128,
"description": "An optional unique client-made id for this request. When specified, this id is included in the Json payload that will be sent asynchronously. This can help clients both guarantee idempotency and correlate asynchronous responses with their requests.\n\n_Note_: this id must be different for every request. It is recommended to use a randomly generated UUID.",
"title": "client_request_id"
},
"status": {
"type": "string",
"enum": [
"ONGOING",
"FAILED",
"SUCCEEDED"
],
"title": "async_request_status"
}
},
"required": [
"id",
"status"
]
},
{
"title": "FAILED",
"type": "object",
"properties": {
"id": {
"description": "The id of the asynchronous request.",
"type": "string",
"format": "uuid",
"example": "98FCE1EF-DBCA-41EF-8BC7-4D1621AC07C6",
"title": "uuid"
},
"client_request_id": {
"type": "string",
"maxLength": 128,
"description": "An optional unique client-made id for this request. When specified, this id is included in the Json payload that will be sent asynchronously. This can help clients both guarantee idempotency and correlate asynchronous responses with their requests.\n\n_Note_: this id must be different for every request. It is recommended to use a randomly generated UUID.",
"title": "client_request_id"
},
"status": {
"type": "string",
"enum": [
"ONGOING",
"FAILED",
"SUCCEEDED"
],
"title": "async_request_status"
},
"payload": {
"type": "object",
"properties": {
"error_code": {
"type": "integer",
"example": 422
},
"error_message": {
"type": "string",
"example": "We can't generate the note when the transcript is too short."
}
},
"required": [
"error_code"
],
"title": "async_request_failed_payload"
}
},
"required": [
"id",
"status",
"payload"
]
},
{
"title": "SUCCEEDED",
"type": "object",
"properties": {
"id": {
"description": "The id of the asynchronous request.",
"type": "string",
"format": "uuid",
"example": "98FCE1EF-DBCA-41EF-8BC7-4D1621AC07C6",
"title": "uuid"
},
"client_request_id": {
"type": "string",
"maxLength": 128,
"description": "An optional unique client-made id for this request. When specified, this id is included in the Json payload that will be sent asynchronously. This can help clients both guarantee idempotency and correlate asynchronous responses with their requests.\n\n_Note_: this id must be different for every request. It is recommended to use a randomly generated UUID.",
"title": "client_request_id"
},
"status": {
"type": "string",
"enum": [
"ONGOING",
"FAILED",
"SUCCEEDED"
],
"title": "async_request_status"
},
"payload": {
"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"
}
},
"required": [
"id",
"status"
]
}
],
"discriminator": {
"propertyName": "status",
"mapping": {
"ONGOING": {
"type": "object",
"properties": {
"id": {
"description": "The id of the asynchronous request.",
"type": "string",
"format": "uuid",
"example": "98FCE1EF-DBCA-41EF-8BC7-4D1621AC07C6",
"title": "uuid"
},
"client_request_id": {
"type": "string",
"maxLength": 128,
"description": "An optional unique client-made id for this request. When specified, this id is included in the Json payload that will be sent asynchronously. This can help clients both guarantee idempotency and correlate asynchronous responses with their requests.\n\n_Note_: this id must be different for every request. It is recommended to use a randomly generated UUID.",
"title": "client_request_id"
},
"status": {
"type": "string",
"enum": [
"ONGOING",
"FAILED",
"SUCCEEDED"
],
"title": "async_request_status"
}
},
"required": [
"id",
"status"
],
"title": "async_request_ongoing"
},
"FAILED": {
"type": "object",
"properties": {
"id": {
"description": "The id of the asynchronous request.",
"type": "string",
"format": "uuid",
"example": "98FCE1EF-DBCA-41EF-8BC7-4D1621AC07C6",
"title": "uuid"
},
"client_request_id": {
"type": "string",
"maxLength": 128,
"description": "An optional unique client-made id for this request. When specified, this id is included in the Json payload that will be sent asynchronously. This can help clients both guarantee idempotency and correlate asynchronous responses with their requests.\n\n_Note_: this id must be different for every request. It is recommended to use a randomly generated UUID.",
"title": "client_request_id"
},
"status": {
"type": "string",
"enum": [
"ONGOING",
"FAILED",
"SUCCEEDED"
],
"title": "async_request_status"
},
"payload": {
"type": "object",
"properties": {
"error_code": {
"type": "integer",
"example": 422
},
"error_message": {
"type": "string",
"example": "We can't generate the note when the transcript is too short."
}
},
"required": [
"error_code"
],
"title": "async_request_failed_payload"
}
},
"required": [
"id",
"status",
"payload"
],
"title": "async_request_failed"
},
"SUCCEEDED": {
"type": "object",
"properties": {
"id": {
"description": "The id of the asynchronous request.",
"type": "string",
"format": "uuid",
"example": "98FCE1EF-DBCA-41EF-8BC7-4D1621AC07C6",
"title": "uuid"
},
"client_request_id": {
"type": "string",
"maxLength": 128,
"description": "An optional unique client-made id for this request. When specified, this id is included in the Json payload that will be sent asynchronously. This can help clients both guarantee idempotency and correlate asynchronous responses with their requests.\n\n_Note_: this id must be different for every request. It is recommended to use a randomly generated UUID.",
"title": "client_request_id"
},
"status": {
"type": "string",
"enum": [
"ONGOING",
"FAILED",
"SUCCEEDED"
],
"title": "async_request_status"
},
"payload": {
"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"
}
},
"required": [
"id",
"status"
],
"title": "async_suggested_orders_generation_succeeded"
}
}
},
"title": "async_suggested_orders_generation"
}
}
}
}
}
}