ChartHero Developer Docs
API ReferenceOpenAPI JSON
Get Started

Core Concepts

AuthenticationScopesPagination

Guides

Fetch encountersFetch documentsFetch transcript and audioReceive webhooksVerify webhook signatures
API ReferenceWebhooksErrorsChangelog

Guide

Fetch encounters

List encounters and read encounter details for an approved partner organization.

When to use this

Use GET /external/v1/encounters to discover encounters available to the caller organization. The list response is intended for integration sync jobs and workflow selection, not broad exploratory search.

Use GET /external/v1/encounters/{encounter_id} when you already have an encounter ID from the list route or an approved webhook follow-up.

The encounter list supports limit, offset, sort_order, start_at, and end_at. Pagination is offset-based and is not snapshot-consistent across repeated calls. See Pagination for parameter limits and unsupported-filter behavior.

Required scopes

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

The caller organization must also be enabled for encounter routes.

Request

List available encounters:

cURL
curl "https://api.example.test/external/v1/encounters?limit=25&offset=0&sort_order=desc" \
  -H "Authorization: Bearer ch_sk_example_123"

Use start_at and end_at when you only want encounters created in a time window. Use timezone-aware ISO datetimes, for example 2026-05-01T00:00:00Z.

Read one encounter:

cURL
curl "https://api.example.test/external/v1/encounters/enc_9YpJvK2" \
  -H "Authorization: Bearer ch_sk_example_123"

Encounter detail does not accept query parameters. Authorized callers receive unsupported_filter for any query key on this route.

Response

List response:

JSON
{
  "items": [
    {
      "encounter_id": "enc_9YpJvK2",
      "organization_id": "org_7Df4",
      "encounter_type": "ambient",
      "status": "completed",
      "created_at": "2026-05-25T14:00:00Z",
      "updated_at": "2026-05-25T15:00:00Z",
      "date_of_service": "2026-05-25T14:00:00Z",
      "patient": {
        "patient_id": "pat_3Qn8",
        "first_name": "Jane",
        "last_name": "Doe",
        "date_of_birth": "1970-01-01"
      },
      "documents": [
        {
          "document_id": "doc_Ambient1",
          "schema_type": "ambient_transcript",
          "title": "Ambient transcript",
          "status": "completed",
          "workflow_variant": "ambient",
          "audio_duration_seconds": 842.4
        }
      ]
    }
  ],
  "limit": 25,
  "offset": 0,
  "total": 1
}

Encounter detail response:

JSON
{
  "encounter": {
    "encounter_id": "enc_9YpJvK2",
    "organization_id": "org_7Df4",
    "encounter_type": "clinical_documentation",
    "status": "completed",
    "created_at": "2026-05-25T14:00:00Z",
    "updated_at": "2026-05-25T15:00:00Z",
    "date_of_service": "2026-05-25T14:00:00Z",
    "patient": {
      "patient_id": "pat_3Qn8",
      "first_name": "Jane",
      "last_name": "Doe",
      "date_of_birth": "1970-01-01"
    },
    "documents": [
      {
        "document_id": "doc_Note1",
        "schema_type": "document",
        "title": "Progress note",
        "status": null,
        "workflow_variant": null,
        "audio_duration_seconds": null
      }
    ]
  }
}

Path IDs are opaque ChartHero IDs. Do not infer organization, patient, timestamp, or storage information from their format.

Common errors

HTTP status Reason code What it means
400 unsupported_filter The request includes a query parameter that this route does not support.
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 or organization_not_allowlisted The route is not enabled for the caller organization.
403 cross_organization_denied or demo_training_denied The requested encounter is not available to this API key.
404 encounter_not_found The encounter was not found for the caller organization.
422 invalid_limit, invalid_offset, invalid_sort, or invalid_query A supported pagination, sort, or date parameter is invalid on the list route.
503 digest_key_unavailable API-key verification is temporarily unavailable.

Authentication, partner route enablement, and scope checks run before query validation. Resource lookup happens after unsupported-query handling.

Next step

Use the documents array in an encounter response to select a clinical document, then follow Fetch documents. See the encounter endpoints in the API Reference for the generated endpoint contracts.

Next steps

Fetch documents

Read a selected clinical document from an encounter.