# Generate a note asynchronously ``` POST /generate-note-async ``` Creates an asynchronous task (also called asynchronous request) that will generate a structured clinical note given the transcript, then keeps the response for two hours before removing it, allowing it to be fetched using the [poll endpoint](/2026-07-01/user/get-generate-note-async.md). More details about asynchronous note generation can be found in the [best practices guide](/2026-07-01/guides/best-practices/asynchronous-note-generation.md). The generated note will be localized to the user's language and can be customized using the user's [note generation settings](/2026-07-01/user/update-note-settings.md) and template-specific [per-section customization options](/2026-07-01/user/update-note-settings-template-customization.md). Customization includes adjusting the level of detail, organizing content by problem, and other formatting preferences. ## Request[​](#request "Direct link to request") ## Responses[​](#responses "Direct link to Responses") * 200 Request received and processing started. ## Operation spec ```json { "method": "post", "path": "/generate-note-async", "operationId": "generate-note-async", "requestBody": { "required": true, "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "description": "Input for note generation.", "required": [ "transcript_items" ], "properties": { "transcript_items": { "type": "array", "description": "The transcript from which to generate the note.\n\nYou don't need to specify each item's start or end time, but make sure they are sorted. In fact, due to its asynchronous nature, our [real-time transcription API](/2026-07-01/server/transcribe-ws) does not guarantee its results order. Thus, before calling this note-generation API please **filter-out non-final items and sort them by `start_offset_ms`**.", "items": { "type": "object", "description": "A portion of the transcribed consultation.", "properties": { "text": { "type": "string", "description": "The transcribed text.", "example": "Also, I’m allergic to peanuts." }, "speaker_type": { "type": "string", "enum": [ "DOCTOR", "PATIENT", "UNSPECIFIED" ], "description": "Who said the text in this transcript item.", "example": "DOCTOR", "title": "speaker" } }, "required": [ "text", "speaker_type" ], "title": "transcript_item_request" } }, "current_note": { "description": "Optional note from a previous transcription session, to be updated using the new `transcript_items`. This is useful if you generate notes gradually to avoid accumulating a very long transcript items list.\nThe `template` and `locale` fields describe the note being passed in and do not control the output.", "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](/2026-07-01/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" }, "text": { "type": "string", "description": "Content of the note section.", "example": "Sleep disorder" } }, "required": [ "key", "title", "text" ], "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" }, "unstructured_context": { "type": "string", "description": "Some unstructured contextual information that will be used to generate the note (for example name, gender, age, pronouns, medical history). For better information processing, please prioritize passing information in a structured manner via the `structured_context` field.", "maxLength": 700 }, "structured_context": { "type": "object", "description": "Structured context about the patient and the encounter, which will be taken into account when generating the note.", "properties": { "encounter_diagnoses_coding": { "type": "array", "description": "The ICD-10 coding for the patient's active encounter diagnoses. If the template used for the note generation contains an `ASSESSMENT_AND_PLAN` section, these diagnoses will be used for the \"by problem\" structuration of this section if they are discussed 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": { "type": "object", "description": "A source note used as input to follow-up note generation. The list of accepted section kinds depends on the target template — see the template introspection endpoint's `supported_source_note_section_kinds` field.", "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", "text" ], "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" }, "text": { "type": "string", "description": "The raw text content of the section." } }, "title": "source_note_section" } } }, "title": "source_note" } }, "title": "structured_context_request" }, "encounter_date": { "type": "string", "format": "date", "description": "The date of the encounter in YYYY-MM-DD format. It is recommended to always provide this field to improve the quality of the generated note. When provided, this date grounds relative temporal references (e.g., \"last year\") in the generated note. Defaults to today's date when omitted.", "example": "2026-03-24" } }, "title": "generate_note_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_note_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 generated note along with suggested Dot Phrases if applicable.", "required": [ "note" ], "properties": { "note": { "type": "object", "description": "The generated note.", "properties": { "title": { "type": "string", "description": "Title of the note.", "example": "Fever and strong headache" }, "sections": { "type": "array", "description": "Content of the note structured in multiple sections.", "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](/2026-07-01/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" }, "text": { "type": "string", "description": "Content of the note section.", "example": "Sleep disorder" } }, "required": [ "key", "title", "text" ], "example": [ { "key": "CHIEF_COMPLAINT", "title": "Chief complaint", "text": "Fatigue and headaches" }, { "key": "SYMPTOMS", "title": "Symptoms", "text": "- Tiredness all day long\n- Mild headaches on the right side" } ], "title": "note_section" } }, "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" }, "suggested_dot_phrases": { "type": "array", "description": "A collection of Dot Phrases that were successfully matched to the encounter's transcript, given the Dot Phrases defined on the calling user. Will be null in the context of a Server API call (i.e. no calling user).\nThis functionality enriches the generated note by expanding concise key sentences (triggers) into a more detailed format following the given Dot Phrase definition. Thus, enhancing the depth and utility of the note and facilitating a comprehensive review of patient assessments in a structured and conventional manner.", "items": { "type": "object", "description": "Suggested Dot Phrase.", "required": [ "text_to_insert" ], "properties": { "dot_phrase": { "type": "object", "description": "Dot phrase, also referred to as EHR (Electronic Health Record) macro, is a concise abbreviation (`trigger`) that unfolds into a predefined, extended text (`replacement`).", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique identifier of the Dot Phrase." }, "title": { "type": "string", "description": "A user-friendly title for the Dot Phrase. Does not impact the matching logic.", "example": "Normal physical exam" }, "trigger": { "type": "string", "description": "The text which, if present in the transcript, will prompt the suggestion of this Dot Phrase.", "example": "Your physical exam is normal" }, "content_auto_update_enabled": { "type": "boolean", "description": "If true, whenever this dot phrase is suggested, the replacement text will be automatically updated based on the encounter discussion.", "example": false }, "replacement": { "type": "string", "description": "The replacement text for this Dot Phrase. If the Dot Phrase's trigger is detected, this text will be suggested in the note generation's response.", "example": "- Heart Examination: Normal, with regular rate and rhythm, no murmurs. - Lung Assessment: Normal breath sounds, no wheezes, crackles, or rhonchi. - Abdominal Evaluation: Normal, no tenderness, masses, or hepatosplenomegaly." }, "created_at": { "type": "string", "format": "date-time", "description": "The creation date of this object, in ISO 8601 format.", "example": "2022-03-10T19:16:23.456Z", "title": "created_at" }, "updated_at": { "type": "string", "format": "date-time", "description": "The last update date of this object, in ISO 8601 format.", "example": "2022-03-10T19:16:23.456Z", "title": "updated_at" } }, "required": [ "id", "title", "trigger", "content_auto_update_enabled", "replacement", "created_at", "updated_at" ], "title": "dot_phrase" }, "note_section": { "type": "object", "description": "The key and the title of the section in the note where this Dot Phrase is suggested to go. There are three possible scenarios:\n\n • No suggested section: Given the Dot Phrase's content, we found no appropriate section to suggest. You should decide for a default (for instance: any kind of \"free text\" area you might have).\n\n • Suggested section already present in the note: We recommend you append the Dot Phrase's suggested `text_to_insert` to the section's content.\n\n • Suggested section is not present in the note: Add a new section to the note with the provided key and title and use the Dot Phrase's suggested `text_to_insert` as the section's content.", "required": [ "key", "title" ], "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](/2026-07-01/guides/note-templates/note-templates-sections) for possible values.", "example": "CHIEF_COMPLAINT", "title": "note_section_key" }, "title": { "type": "string", "description": "Section title.", "example": "Assessment & Plan." } }, "title": "dot_phrase_section" }, "text_to_insert": { "type": "string", "description": "The actual suggested content, to be inserted in the corresponding note section. Please note that the content might be different from the replacement in the original Dot Phrase definition. In fact, the `text_to_insert` takes into account the contextual information of the encounter and might change the original Dot Phrase replacement text, for instance to include exceptions.", "example": "- Heart Examination: Normal, with regular rate and rhythm, no murmurs.\n- Lung Assessment: Normal breath sounds, no wheezes, crackles, or rhonchi.\n- Abdominal Evaluation: Normal, no tenderness, masses, or hepatosplenomegaly.\n" } }, "title": "suggested_dot_phrase" }, "title": "suggested_dot_phrases" } }, "title": "async_note_generation_succeeded_payload" } }, "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 generated note along with suggested Dot Phrases if applicable.", "required": [ "note" ], "properties": { "note": { "type": "object", "description": "The generated note.", "properties": { "title": { "type": "string", "description": "Title of the note.", "example": "Fever and strong headache" }, "sections": { "type": "array", "description": "Content of the note structured in multiple sections.", "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](/2026-07-01/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" }, "text": { "type": "string", "description": "Content of the note section.", "example": "Sleep disorder" } }, "required": [ "key", "title", "text" ], "example": [ { "key": "CHIEF_COMPLAINT", "title": "Chief complaint", "text": "Fatigue and headaches" }, { "key": "SYMPTOMS", "title": "Symptoms", "text": "- Tiredness all day long\n- Mild headaches on the right side" } ], "title": "note_section" } }, "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" }, "suggested_dot_phrases": { "type": "array", "description": "A collection of Dot Phrases that were successfully matched to the encounter's transcript, given the Dot Phrases defined on the calling user. Will be null in the context of a Server API call (i.e. no calling user).\nThis functionality enriches the generated note by expanding concise key sentences (triggers) into a more detailed format following the given Dot Phrase definition. Thus, enhancing the depth and utility of the note and facilitating a comprehensive review of patient assessments in a structured and conventional manner.", "items": { "type": "object", "description": "Suggested Dot Phrase.", "required": [ "text_to_insert" ], "properties": { "dot_phrase": { "type": "object", "description": "Dot phrase, also referred to as EHR (Electronic Health Record) macro, is a concise abbreviation (`trigger`) that unfolds into a predefined, extended text (`replacement`).", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique identifier of the Dot Phrase." }, "title": { "type": "string", "description": "A user-friendly title for the Dot Phrase. Does not impact the matching logic.", "example": "Normal physical exam" }, "trigger": { "type": "string", "description": "The text which, if present in the transcript, will prompt the suggestion of this Dot Phrase.", "example": "Your physical exam is normal" }, "content_auto_update_enabled": { "type": "boolean", "description": "If true, whenever this dot phrase is suggested, the replacement text will be automatically updated based on the encounter discussion.", "example": false }, "replacement": { "type": "string", "description": "The replacement text for this Dot Phrase. If the Dot Phrase's trigger is detected, this text will be suggested in the note generation's response.", "example": "- Heart Examination: Normal, with regular rate and rhythm, no murmurs. - Lung Assessment: Normal breath sounds, no wheezes, crackles, or rhonchi. - Abdominal Evaluation: Normal, no tenderness, masses, or hepatosplenomegaly." }, "created_at": { "type": "string", "format": "date-time", "description": "The creation date of this object, in ISO 8601 format.", "example": "2022-03-10T19:16:23.456Z", "title": "created_at" }, "updated_at": { "type": "string", "format": "date-time", "description": "The last update date of this object, in ISO 8601 format.", "example": "2022-03-10T19:16:23.456Z", "title": "updated_at" } }, "required": [ "id", "title", "trigger", "content_auto_update_enabled", "replacement", "created_at", "updated_at" ], "title": "dot_phrase" }, "note_section": { "type": "object", "description": "The key and the title of the section in the note where this Dot Phrase is suggested to go. There are three possible scenarios:\n\n • No suggested section: Given the Dot Phrase's content, we found no appropriate section to suggest. You should decide for a default (for instance: any kind of \"free text\" area you might have).\n\n • Suggested section already present in the note: We recommend you append the Dot Phrase's suggested `text_to_insert` to the section's content.\n\n • Suggested section is not present in the note: Add a new section to the note with the provided key and title and use the Dot Phrase's suggested `text_to_insert` as the section's content.", "required": [ "key", "title" ], "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](/2026-07-01/guides/note-templates/note-templates-sections) for possible values.", "example": "CHIEF_COMPLAINT", "title": "note_section_key" }, "title": { "type": "string", "description": "Section title.", "example": "Assessment & Plan." } }, "title": "dot_phrase_section" }, "text_to_insert": { "type": "string", "description": "The actual suggested content, to be inserted in the corresponding note section. Please note that the content might be different from the replacement in the original Dot Phrase definition. In fact, the `text_to_insert` takes into account the contextual information of the encounter and might change the original Dot Phrase replacement text, for instance to include exceptions.", "example": "- Heart Examination: Normal, with regular rate and rhythm, no murmurs.\n- Lung Assessment: Normal breath sounds, no wheezes, crackles, or rhonchi.\n- Abdominal Evaluation: Normal, no tenderness, masses, or hepatosplenomegaly.\n" } }, "title": "suggested_dot_phrase" }, "title": "suggested_dot_phrases" } }, "title": "async_note_generation_succeeded_payload" } }, "required": [ "id", "status" ], "title": "async_note_generation_succeeded" } } }, "title": "async_note_generation" } } } } } } ```