Guide

Fetch documents

Read supported clinical documents after selecting an encounter document.

When to use this

Use GET /external/v1/documents to discover supported documents available to the caller organization.

Use GET /external/v1/encounters/{encounter_id}/documents/{document_id} after selecting a document from the document list, an encounter response, or a webhook follow-up fetch.

This route returns one supported document for the same caller organization as the encounter. Document variants are:

`schema_type`	Public content
`document`	Clinical markdown content plus public-safe template reference when available.
`ambient_transcript`	Finalized transcript content, optional source transcript for translated phone calls, recording metadata, target template reference, and phone-call metadata when the workflow variant is `phone_call`. No-audio phone calls may return `transcript: null` with `phone_call.call_log`.
`billing`	Selected billing codes and bounded billing context, including payer context without raw coverage payloads.
`encounter_checklist`	Materialized checklist payload state, provenance, and import lineage without dashboard planning state or event history.

Required scopes

Route	Required scopes
`GET /external/v1/documents`	`encounters:read`, `patients:read`, `documents:read`
`GET /external/v1/encounters/{encounter_id}/documents/{document_id}`	`encounters:read`, `patients:read`, `documents:read`

The API key must be organization-scoped. Document responses are limited to same-organization, real records.

Request

List supported documents:

curl "https://api.charthero.ai/external/v1/documents?limit=25&offset=0&sort_order=desc" \
  -H "Authorization: Bearer <api_key>"

The document list supports limit, offset, sort_order, and include. Use include=encounters,patients,activities,actors to request context sidecars. No includes are returned by default.

Read one document:

curl "https://api.charthero.ai/external/v1/encounters/enc_synthetic_001/documents/doc_synthetic_note_001" \
  -H "Authorization: Bearer <api_key>"

Document detail accepts only include=encounters,patients,activities,actors. Authorized callers receive unsupported_filter for any other query key on this route.

Response

List response:

{
  "items": [
    {
      "document_id": "doc_synthetic_note_001",
      "encounter_id": "enc_synthetic_001",
      "patient_id": "pat_synthetic_001",
      "schema_type": "document",
      "title": "Progress note",
      "created_at": "2026-05-25T14:30:00Z",
      "updated_at": "2026-05-25T15:00:00Z",
      "external_ids": [],
      "content": {
        "format": "markdown",
        "text": "Synthetic assessment and plan text."
      }
    },
    {
      "document_id": "doc_synthetic_transcript_001",
      "encounter_id": "enc_synthetic_001",
      "patient_id": "pat_synthetic_001",
      "schema_type": "ambient_transcript",
      "status": "completed",
      "workflow_variant": "ambient",
      "created_at": "2026-05-25T14:35:00Z",
      "updated_at": "2026-05-25T15:05:00Z",
      "external_ids": [],
      "recording": {
        "availability": "available",
        "duration_seconds": 842.4
      },
      "transcript": {
        "provider": "deepgram",
        "audio_duration_seconds": 842.4,
        "turns": [
          {
            "speaker": "clinician",
            "speaker_role": "provider",
            "start_seconds": 0.0,
            "end_seconds": 1.6,
            "text": "Synthetic clinician sample."
          }
        ]
      }
    },
    {
      "document_id": "doc_synthetic_billing_001",
      "encounter_id": "enc_synthetic_001",
      "patient_id": "pat_synthetic_001",
      "schema_type": "billing",
      "title": "Billing codes",
      "created_at": "2026-05-25T14:40:00Z",
      "updated_at": "2026-05-25T15:10:00Z",
      "external_ids": [],
      "codes": [
        {
          "code_type": "cpt",
          "code": "99213",
          "label": "Office visit"
        }
      ],
      "billing_context": {
        "encounter_type": "outpatient",
        "total_time_minutes": 18,
        "payer_context": {
          "source": "ehr_import",
          "payer_name": "Synthetic payer",
          "plan_name": "Synthetic plan"
        }
      },
      "source_document_id": "doc_synthetic_note_001"
    },
    {
      "document_id": "doc_synthetic_checklist_001",
      "encounter_id": "enc_synthetic_001",
      "patient_id": "pat_synthetic_001",
      "schema_type": "encounter_checklist",
      "title": "Visit checklist",
      "status": "active",
      "created_at": "2026-05-25T14:45:00Z",
      "updated_at": "2026-05-25T15:15:00Z",
      "external_ids": [],
      "payload": {
        "schema_version": "1.0",
        "blocks": [
          {
            "type": "workflow",
            "block_id": "block_synthetic_001",
            "workflow_id": "workflow_synthetic_001",
            "title": "Medication review",
            "provenance": {
              "source_system": "CHARTHERO_TEMPLATE",
              "source_type": "WORKFLOW_TEMPLATE",
              "captured_at": "2026-05-25T14:45:00Z"
            },
            "tasks": [
              {
                "task_id": "task_synthetic_001",
                "title": "Review medication list",
                "category": "CHRONIC_CONDITIONS",
                "task_type": "MEDICATION",
                "kind": "task",
                "status": "IN_PROGRESS",
                "priority": "HIGH",
                "provenance": {
                  "source_system": "CHARTHERO_TEMPLATE",
                  "source_type": "WORKFLOW_TEMPLATE",
                  "captured_at": "2026-05-25T14:45:00Z"
                },
                "requires_action": true,
                "status_needs_confirmation": false,
                "dismissed": false,
                "flags": [],
                "subtasks": [],
                "created_at": "2026-05-25T14:45:00Z",
                "updated_at": "2026-05-25T15:15:00Z"
              }
            ],
            "status": "IN_PROGRESS",
            "created_at": "2026-05-25T14:45:00Z",
            "updated_at": "2026-05-25T15:15:00Z"
          }
        ],
        "flags": []
      },
      "import_sources": []
    }
  ],
  "limit": 25,
  "offset": 0
}

Detail response:

{
  "document": {
    "document_id": "doc_synthetic_note_001",
    "encounter_id": "enc_synthetic_001",
    "schema_type": "document",
    "title": "Progress note",
    "created_at": "2026-05-25T14:30:00Z",
    "updated_at": "2026-05-25T15:00:00Z",
    "content": {
      "format": "markdown",
      "text": "Synthetic assessment and plan text."
    }
  }
}

Billing detail response:

{
  "document": {
    "document_id": "doc_synthetic_billing_001",
    "encounter_id": "enc_synthetic_001",
    "schema_type": "billing",
    "title": "Billing codes",
    "created_at": "2026-05-25T14:40:00Z",
    "updated_at": "2026-05-25T15:10:00Z",
    "codes": [
      {
        "code_type": "cpt",
        "code": "99213",
        "label": "Office visit"
      }
    ],
    "billing_context": {
      "encounter_type": "outpatient",
      "total_time_minutes": 18,
      "payer_context": {
        "source": "ehr_import",
        "payer_name": "Synthetic payer",
        "plan_name": "Synthetic plan"
      }
    },
    "source_document_id": "doc_synthetic_note_001"
  }
}

Checklist detail response:

{
  "document": {
    "document_id": "doc_synthetic_checklist_001",
    "encounter_id": "enc_synthetic_001",
    "schema_type": "encounter_checklist",
    "title": "Visit checklist",
    "status": "active",
    "created_at": "2026-05-25T14:45:00Z",
    "updated_at": "2026-05-25T15:15:00Z",
    "payload": {
      "schema_version": "1.0",
      "blocks": [
        {
          "type": "workflow",
          "block_id": "block_synthetic_001",
          "workflow_id": "workflow_synthetic_001",
          "title": "Medication review",
          "provenance": {
            "source_system": "CHARTHERO_TEMPLATE",
            "source_type": "WORKFLOW_TEMPLATE",
            "captured_at": "2026-05-25T14:45:00Z"
          },
          "tasks": [
            {
              "task_id": "task_synthetic_001",
              "title": "Review medication list",
              "category": "CHRONIC_CONDITIONS",
              "task_type": "MEDICATION",
              "kind": "task",
              "status": "IN_PROGRESS",
              "priority": "HIGH",
              "provenance": {
                "source_system": "CHARTHERO_TEMPLATE",
                "source_type": "WORKFLOW_TEMPLATE",
                "captured_at": "2026-05-25T14:45:00Z"
              },
              "requires_action": true,
              "status_needs_confirmation": false,
              "dismissed": false,
              "flags": [],
              "subtasks": [],
              "created_at": "2026-05-25T14:45:00Z",
              "updated_at": "2026-05-25T15:15:00Z"
            }
          ],
          "status": "IN_PROGRESS",
          "created_at": "2026-05-25T14:45:00Z",
          "updated_at": "2026-05-25T15:15:00Z"
        }
      ],
      "flags": []
    },
    "import_sources": []
  }
}

For an ambient transcript document, this route returns speaker turns and timing under document.transcript. For translated phone calls, document.transcript_language identifies the original spoken language and document.source_transcript returns the original-language transcript using the same transcript schema. The English transcript may combine source-language provider fragments into different turn boundaries, so do not align transcript.turns and source_transcript.turns by array index. Phone-call metadata uses phone_call.call_legs, phone_call.outcome, nested recording_consent, and phone_call.call_log. Use the audio route for a short-lived audio URL when available.

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 type is not supported for document detail.
`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 does not include every required scope.
`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`, or `transcript_not_found`	The encounter, document, or finalized transcript was not found for the caller organization.
`503`	`digest_key_unavailable`	API-key verification is temporarily unavailable.

Path IDs are opaque ChartHero IDs. Treat example IDs as illustrative strings only.

Fetch documents

When to use this

Required scopes

Request

Response

Common errors

Next steps

.css-1hnz6hu{position:static;}.css-1hnz6hu::before{content:'';cursor:inherit;display:block;position:absolute;top:0px;left:0px;z-index:0;width:100%;height:100%;}Fetch audio

Review required scopes

Open API Reference

Fetch audio