Listen — From audio file asynchronously

POST 
/listen_async

Generate a transcript and a structured clinical note from an audio file. Only audio/* mime types are supported. The maximum duration is 60 minutes. The result of the request is posted to the callback URL once available.

Request

application/json

Body

required

output_objectslisten_output_object (string)[]required

Specifies which items you want us to send you back. In other words, which feature(s) you want to use, transcription and/or note generation.

Possible values: [transcript_item, note]

languagecopilot_language (string)required
Language spoken in the audio ('fr' and 'en' are deprecated, and correspond to 'fr-FR' and 'en-US' respectively. Generating a note in 'es-ES' and 'es-MX' is not supported and will be soon removed).
Possible values: [fr, en, en-US, en-GB, fr-FR, es-ES, es-MX]
Example: en-US
split_by_sentenceboolean
Indicates whether to segment transcription results at sentence boundaries. Default is false, meaning that a single transcript item may encompass multiple sentences, provided they are not delineated by pauses (silence) in the audio.
Default value: false
section_stylecopilot_section_style (string)
Choose a desired style for note sections:
• paragraphs: Prioritizes generating paragraphs;
• bullet_points: Prioritizes structuring content using bullet points.
• auto: Automatically picks the most natural formatting option.
Default is auto.
Possible values: [auto, paragraphs, bullet_points]
Example: paragraphs
split_by_problemcopilot_split_by_problem (boolean)
Flag to structure the content of the note sections according to distinct clinical problems or topics addressed during the consultation.
When this flag is enabled, the text within some sections of the clinical note is organized into subsections, each corresponding to a specific problem or topic. This format aims to enhance the clarity and organization of the clinical note, making it easier to read and understand the different issues discussed during the consultation.
Important: Currently, the application of this flag is limited to the HISTORY_OF_PRESENT_ILLNESS and SOAP_SUBJECTIVE sections and is only effective when the language is set to English (US or GB).
Default value: false
note_templatecopilot_note_template (string)
The desired template of the generated note.
Some templates are only available in specific languages. Check Note template for details.
Possible values: [GENERAL_MEDICINE, GENERAL_MEDICINE_AP_MERGED, CARDIOLOGY, PSYCHIATRY, DIET, PSYCHOLOGY, SOAP, GENERAL_MEDICINE_WCC, SOAP_WCC, GENERAL_MEDICINE_EMERGENCY, SOAP_EMERGENCY]
Example: GENERAL_MEDICINE
file_urlstringrequired

The URL of the audio file to download & listen to.

callback_urlstringrequired

Once we are done processing the input and generating the transcript & note, we will call you back with a 'POST' on this URL and a Json body respecting exactly the same schema as the response of the synchronous equivalent endpoint (i.e. /copilot/listen).

client_request_idcopilot_client_request_id (string)

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.

Note: this id must be different for every request. It is recommended to use a randomly generated UUID.

Possible values: <= 128 characters

Responses

200

Request received and processing started.

application/json

Schema

Schema

request_iduuidrequired
The id of the request you just created.
Example: 98FCE1EF-DBCA-41EF-8BC7-4D1621AC07C6
client_request_idstring

The provided client_request_id.

Example (from schema)

{
  "request_id": "98FCE1EF-DBCA-41EF-8BC7-4D1621AC07C6",
  "client_request_id": "string"
}

299

Here's the schema of the Json payload that will be sent **asynchronously** to the URL you provided. (299 is not a possible response code — only a way here to document the asynchronous payload schema).

application/json

Schema

Schema

oneOf
success
request_iduuidrequired
The id of the async request.
Example: 98FCE1EF-DBCA-41EF-8BC7-4D1621AC07C6
client_request_idstring
The client_request_id provided in the request.
transcript
object[]
Transcript items from the audio file.
Array [
textstringrequired
The transcribed text.
Example: Also, I’m allergic to peanuts.
speakercopilot_speaker (string)required
Who said the text in this transcript item.
Possible values: [doctor, patient, unspecified]
Example: doctor
start_offset_msintegerrequired
Start time of this transcription item as the offset, in milliseconds, from the start of the audio file.
Example: 65100
end_offset_msintegerrequired
End time of this transcription item as the offset, in milliseconds, from the start of the audio file. Equals the start_time_ms plus the duration of the related transcribed audio portion.
Example: 69300
]
note
object
The generated note.
titlestring
Title of the note.
Example: Fever and strong headache
sections
object[]
required
Array [
keycopilot_note_section_key (string)required
A key identifying a section of a note. The set of possible keys depend on the template that is used. Check Note template for possible values.
Possible values: [ALLERGIES, APPOINTMENTS, ASSESSMENT, ASSESSMENT_AND_PLAN, CARDIOVASCULAR_RISKS, CHIEF_COMPLAINT, CURRENT_MEDICATIONS, DIET_APPOINTMENTS, DIET_CHIEF_COMPLAINT, DIET_HABITS, DIET_LIFESTYLE, DIET_MEDICAL_HISTORY, DIET_OBJECTIVES, DIET_VITALS, FAMILY_HISTORY, HISTORY_OF_PRESENT_ILLNESS, IMAGING_RESULTS, IMMUNIZATIONS, LAB_RESULTS, MENTAL_HEALTH_EXAM, MENTAL_HEALTH_HISTORY, PAST_MEDICAL_HISTORY, PAST_OBSTETRIC_HISTORY, PAST_SURGICAL_HISTORY, PHYSICAL_EXAM, PLAN, PRESCRIPTION, PSYCHOLOGY_HISTORY_OF_COMPLAINT, SOAP_ASSESSMENT, SOAP_OBJECTIVE, SOAP_PLAN, SOAP_SUBJECTIVE, SOCIAL_HISTORY, VITALS, WELL_CHILD_CARE]
Example: CHIEF_COMPLAINT
titlestringrequired
The section title.
Example: Chief complaint
textstringrequired
Content of the note section.
Example: Sleep disorder
]
error
request_iduuidrequired
The id of the async request.
Example: 98FCE1EF-DBCA-41EF-8BC7-4D1621AC07C6
client_request_idstring
The client_request_id provided in the request.
error_codeintegerrequired
Example: 422
error_messagestring
Example: We can't generate the note when the transcript is too short.