Synchronous generation transcribes a recording and generates a note using the selected template. The HTTP response contains both results after processing completes.
Endpoint
POST /aiservices/clinical_notes/generate
Authenticate with your Zoom AI Services credentials. The examples on this page send a token in the Authorization: Bearer header.
Input
Provide a downloadable HTTPS or S3 URI in a JSON request, or upload a recording in the multipart file part.
| Field | Type | Required | Description |
|---|---|---|---|
file | string or multipart file | Yes | Downloadable HTTPS or S3 URI to the recording, or the uploaded file. |
template | string | No | SOAP, GENERAL_MEDICINE, or GENERAL_BEHAVIORAL_HEALTH. Defaults to GENERAL_MEDICINE when omitted or empty. An unknown template returns HTTP 400. |
reference_id | string | No | Optional client-supplied reference. |
Provide exactly one recording input. If transcription or note generation fails, the whole request fails.
| Limit | Value |
|---|---|
| Supported formats | .wav, .mp3, .m4a, .mp4, and .webm |
| Maximum duration | 2 hours |
| Maximum file size | 300 MB for uploads; 2 GB for URLs |
Example request (cURL)
This example uploads a recording and selects the SOAP template.
curl -X POST "https://api.zoom.us/v2/aiservices/clinical_notes/generate" \
-H "Authorization: Bearer $TOKEN" \
-F "file=@consultation.wav;type=audio/wav" \
-F "template=SOAP"
For an HTTPS recording URL, send JSON instead:
curl -X POST "https://api.zoom.us/v2/aiservices/clinical_notes/generate" \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{
"file": "https://example.com/consultation.wav",
"template": "SOAP"
}'
Output
A successful request returns HTTP 200 and a JSON object with these fields.
| Field | Type | Description |
|---|---|---|
request_id | string | Request identifier. |
transcript.text_display | string | Complete transcript text. |
transcript.duration_sec | number | Audio duration in seconds. Included only when a duration is available. |
transcript.segments | object[] | Time-aligned transcript segments, in order. Can be empty when segment data is unavailable. |
transcript.segments[].id | string | Segment identifier. |
transcript.segments[].start | number | Segment start time in seconds. |
transcript.segments[].end | number | Segment end time in seconds. |
transcript.segments[].channel | integer | Audio channel index. |
transcript.segments[].speaker | string | Speaker label. Can be empty when unavailable. |
transcript.segments[].text | string | Recognized segment text. |
transcript.segments[].words | object[] | Word-level details. Can be empty. |
transcript.segments[].language | string or null | Language identified for the segment. Can be null when unavailable. |
clinical_notes.full_note | string | Complete note formatted as Markdown. |
clinical_notes.sections | object[] | Ordered note sections. |
clinical_notes.sections[].title | string | Section heading. |
clinical_notes.sections[].content | string | Generated content for the section. |
clinical_notes is an object containing full_note and sections. Use the section array when your application displays headings and content separately.
Display the transcript
- Use
transcript.segmentsto display the transcript as time-aligned segments, using each segment'stext,start, andend. - Fall back to
transcript.text_displaywhensegmentsis empty. - An empty
speakerorwordsarray does not prevent transcript display. - Use
transcript.duration_secto display the audio duration when it is present. A missingduration_secdoes not mean the recording has zero length.
Example response
This response comes from a SOAP request that uses a synthetic clinical encounter. Generated content depends on the recording.
{
"request_id": "a99d32b7-87bf-44cc-a144-464fba16a592",
"transcript": {
"text_display": "Doctor, good morning. What brings you in today? Patient, I've had a sore throat and a fever or about 101 for three days. Doctor, any cough or trouble swallowing? Patient, some trouble swallowing, no cough. Doctor, your throat is red with swollen tonsils. A rapid strep test is positive. I'll prescribe amoxicillin 500 milligrams twice daily for 10 days. Drink fluids and follow up, if not better in 3 days.",
"segments": [
{
"id": "utt_0000",
"start": 0,
"end": 10.944,
"channel": 0,
"speaker": "",
"text": "Doctor, good morning. What brings you in today? Patient, I've had a sore throat and a fever or about 101 for three days. Doctor, any cough or trouble swallowing?",
"words": [],
"language": null
},
{
"id": "utt_0001",
"start": 10.944,
"end": 29.564,
"channel": 0,
"speaker": "",
"text": "Patient, some trouble swallowing, no cough. Doctor, your throat is red with swollen tonsils. A rapid strep test is positive. I'll prescribe amoxicillin 500 milligrams twice daily for 10 days. Drink fluids and follow up, if not better in 3 days.",
"words": [],
"language": null
}
],
"duration_sec": 29.564
},
"clinical_notes": {
"full_note": "**Subjective**\n\nPatient presents with a sore throat and a fever of about 101 for three days. They report some trouble swallowing. They deny cough.\n\n**Objective**\n\n- **Exam:** Throat is red with swollen tonsils.\n- **Testing:** Rapid strep test is positive.\n\n**Assessment**\n\nStreptococcal pharyngitis, supported by sore throat, fever of about 101 for three days, trouble swallowing, red throat with swollen tonsils on exam, and positive rapid strep test.\n\n**Plan**\n\n- **Streptococcal pharyngitis:** Prescribed amoxicillin 500 milligrams twice daily for 10 days.\n- **Streptococcal pharyngitis/supportive care:** Advised to drink fluids.\n- **Streptococcal pharyngitis/follow-up:** Follow up if not better in 3 days.",
"sections": [
{
"title": "Subjective",
"content": "Patient presents with a sore throat and a fever of about 101 for three days. They report some trouble swallowing. They deny cough."
},
{
"title": "Objective",
"content": "- **Exam:** Throat is red with swollen tonsils.\n- **Testing:** Rapid strep test is positive."
},
{
"title": "Assessment",
"content": "Streptococcal pharyngitis, supported by sore throat, fever of about 101 for three days, trouble swallowing, red throat with swollen tonsils on exam, and positive rapid strep test."
},
{
"title": "Plan",
"content": "- **Streptococcal pharyngitis:** Prescribed amoxicillin 500 milligrams twice daily for 10 days.\n- **Streptococcal pharyngitis/supportive care:** Advised to drink fluids.\n- **Streptococcal pharyngitis/follow-up:** Follow up if not better in 3 days."
}
]
}
}
Unsupported media
A recording URI without a supported file extension returns HTTP 400 with reason set to UNSUPPORTED_MEDIA. This includes a malformed URI that has no file extension.
{
"code": 400,
"reason": "UNSUPPORTED_MEDIA",
"message": "File extension \".jpg\" is not supported. Supported extensions: .m4a, .mp3, .mp4, .wav, .webm",
"metadata": {}
}
Request errors
If the request fails, the API returns one of these HTTP error codes.
| HTTP status | Reason | Condition |
|---|---|---|
400 | VALIDATION_MISSING_FIELD | A JSON request does not include file. |
400 | INVALID_INPUT | A multipart request does not include a file part. |
400 | INVALID_INPUT | The template name is unknown. |
400 | INVALID_INPUT | The recording can't be downloaded from the URI. |
400 | UNSUPPORTED_MEDIA | The recording URI does not have a supported media extension. |
429 | — | Too many requests. Retry after the time in the Retry-After header. |
500 | — | Transcription or note generation failed. |
503 | — | The service is temporarily unavailable. |
Authentication errors
Missing or invalid authentication returns HTTP 401. Authentication errors are separate from Clinical Notes application errors. Their response body uses a different shape, for example {"code": 124, "message": "Invalid Access token"}, and does not include reason.
See Get credentials for authentication requirements.