Receive webhooks
Use notifications before fetching document resources.
Guide
Fetch transcript and audio
Fetch finalized transcript turns and request short-lived audio URLs.
When to use this
Use GET /external/v1/encounters/{encounter_id}/documents/{document_id} for finalized transcript turns from an ambient transcript document. The same document detail route also returns clinical, billing, and encounter-checklist document variants when those IDs are selected.
Use GET /external/v1/encounters/{encounter_id}/documents/{document_id}/audio to request a short-lived URL for recording-backed audio when audio is available for that ambient transcript document.
Required scopes
| Route | Required scopes |
|---|---|
GET |
encounters:read, patients:read, documents:read |
GET |
encounters:read, documents:read, recordings:read |
Transcript and phone-call call-log access are governed by documents:read. Audio URL access requires document route access plus the additional recordings:read scope.
Request
Fetch finalized transcript turns:
curl "https://api.charthero.ai/external/v1/encounters/enc_synthetic_001/documents/doc_synthetic_transcript_001" \
-H "Authorization: Bearer <api_key>"
Transcript document detail accepts only include=encounters,patients,activities,actors. No includes are returned by default.
Request a short-lived audio URL:
curl "https://api.charthero.ai/external/v1/encounters/enc_synthetic_001/documents/doc_synthetic_transcript_001/audio" \
-H "Authorization: Bearer <api_key>"
The audio route accepts no query parameters.
Response
Ambient transcript document response:
{
"document": {
"document_id": "doc_synthetic_transcript_001",
"encounter_id": "enc_synthetic_001",
"schema_type": "ambient_transcript",
"status": "completed",
"workflow_variant": "ambient",
"created_at": "2026-05-25T14:00:00Z",
"updated_at": "2026-05-25T15:00:00Z",
"transcript": {
"provider": "deepgram",
"audio_duration_seconds": 842.4,
"turns": [
{
"speaker": "clinician",
"start_seconds": 0.0,
"end_seconds": 1.6,
"text": "Synthetic clinician sample."
},
{
"speaker": "patient",
"start_seconds": 1.8,
"end_seconds": 3.1,
"text": "Synthetic patient sample."
}
]
}
}
}
No-audio phone-call document response:
{
"document": {
"document_id": "doc_synthetic_phone_call_001",
"encounter_id": "enc_synthetic_001",
"schema_type": "ambient_transcript",
"status": "completed",
"workflow_variant": "phone_call",
"created_at": "2026-05-25T14:10:00Z",
"updated_at": "2026-05-25T14:20:00Z",
"recording": {
"availability": "not_available"
},
"phone_call": {
"active_call_leg_id": "call_leg_synthetic_001",
"outcome": "left_voicemail",
"call_legs": [
{
"call_leg_id": "call_leg_synthetic_001",
"to_e164": "+15555550100",
"from_e164": "+15555550199",
"state": "ended",
"started_at": "2026-05-25T14:10:00Z",
"ended_at": "2026-05-25T14:12:00Z",
"recording_consent": {
"status": "declined"
}
}
],
"documentation_plan": {
"action": "generate_call_log"
},
"call_log": {
"format": "markdown",
"text": "Left voicemail. No recording available.",
"generated_at": "2026-05-25T14:20:00Z",
"generated_by": "ai"
}
},
"transcript": null
}
}
Audio URL response:
{
"audio_url": "https://media.charthero.example/signed-recording.wav?token=example",
"expires_at": "2026-05-25T15:15:00Z"
}
Audio URLs are temporary access artifacts. Do not store signed URLs as durable identifiers, put them in client-visible logs, or use them after expiration.
For translated phone-call transcripts, document.transcript_language identifies
the original spoken language, document.transcript contains the
English-normalized transcript, and document.source_transcript contains the
original-language transcript with the same transcript object shape. Default
English transcripts omit transcript_language and source_transcript.
For phone-call ambient documents, document.phone_call may include call-leg phone numbers, public call-leg IDs, an outcome, nested recording consent metadata, a documentation plan, and a markdown call_log. No-audio phone-call documents can return transcript: null while still returning phone_call.call_log. Audio URLs are never embedded in document detail responses.
Common errors
| HTTP status | Reason code | What it means |
|---|---|---|
400 |
unsupported_filter |
The request includes a query parameter that this route does not support. |
400 |
unsupported_document_type |
The selected document is not supported by the requested route. |
400 |
audio_not_available_for_document |
Audio is not available for the selected document. |
401 |
missing_bearer, api_keys_disabled, test_prefix_not_allowed, malformed_token, invalid_key, disabled_key, revoked_key, or expired_key |
API-key authentication failed. Branch on the exact reason_code. |
403 |
org_scope_only_required |
Organization-scoped API keys are required. |
403 |
missing_scope |
The API key is missing encounters:read, patients:read, or documents:read for transcript; audio requires encounters:read, documents:read, and recordings:read. |
403 |
route_not_allowed |
The route is not enabled. |
403 |
cross_organization_denied or demo_training_denied |
The encounter is not available to this API key. |
404 |
encounter_not_found, document_not_found, transcript_not_found, or audio_not_found |
The requested resource is not available to the caller organization. |
503 |
digest_key_unavailable or audio_storage_unavailable |
API-key verification or audio storage is temporarily unavailable. |
Next steps
Review errors
Handle document, transcript, audio, and availability failures.
Open API Reference
Inspect generated document and audio contracts.