Public API

What you can build

ChartHero exposes a public API for approved partners who need secure, server-side access to clinical workflow data. Use it to list actors, list encounters, fetch encounter details, read supported documents with finalized transcript data inline, read AI evaluations of your staff's conversations, and receive activated webhook notifications.

The API is designed for partner workflows such as syncing completed encounters into downstream systems, pulling clinical documents into an internal workflow, bringing conversation evaluations into quality reporting, or acting on transcript-ready and evaluation-completed notifications.

Looking for adapters?

Use the public API when your server calls ChartHero to read ChartHero resources. Use Adapters when ChartHero needs to launch from your system, verify patient or appointment context against your system, or map ChartHero users to upstream providers.

If you are building launch links or partner endpoints that ChartHero calls, start with the Adapter Quickstart and the Adapter Reference.

Implementation checklist

Use this checklist for a first implementation pass:

1. Confirm the environment, base URL, API key, enabled routes, and required scopes.
2. Store the API key in server-side secret storage and send it only from server-side code.
3. Make a first list request, then add pagination, filters, and include values intentionally.
4. Handle standard errors by reason_code and treat successful empty pages as a normal state.
5. If you receive webhooks, verify the signature before any follow-up fetch.
6. Keep API keys, signed audio URLs, PHI-bearing response bodies, raw webhook bodies, transcripts, document content, evaluation summaries and evidence, and patient demographics out of logs, analytics events, screenshots, and support tickets.

Base URL

The current API version is v1. Public REST routes live under /external/v1.

ChartHero currently publishes two shared public API hosts. Use the host that matches the environment for your API key.

The OpenAPI JSON artifact is published with these docs at /openapi/v1/openapi.json.

Authentication

API requests use an API key in the Authorization header with the Bearer scheme.

Authorization: Bearer <api_key>

Keep API keys on your servers. Do not place them in browser code, mobile apps, logs, analytics events, screenshots, or support tickets.

Treat clinical API responses as PHI-bearing when they contain patient, encounter, document, transcript, audio, billing, checklist, evaluation, or phone-call data. Redact those values from application logs and operational tooling unless your own compliance program explicitly allows them.

Before sending traffic, confirm that you are using the right key for the selected environment in Environments.

Make your first request

Start by listing encounters available to your approved partner organization.

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

Use query parameters such as limit, offset, sort_order, start_at, and end_at when you are ready to page or filter results.

A successful response with items: [] means the request was authorized, but no records matched the selected route, filters, offset, and current access. Check the environment, key, filters, offset, and whether resources have been made available to the API key before treating it as an error.

Example response

The response below uses synthetic identifiers and contains no real patient data.

{
  "items": [
    {
      "encounter_id": "enc_example_001",
      "organization_id": "org_example_001",
      "created_at": "2026-05-20T14:30:00Z",
      "updated_at": "2026-05-20T15:05:00Z",
      "date_of_service": "2026-05-20T14:30:00Z",
      "encounter_type": "ambient",
      "status": "completed",
      "patient_id": "pat_example_001",
      "activity_ids": ["act_example_001"],
      "document_ids": ["doc_example_001"],
      "external_ids": [
        {
          "source": "partner_ehr",
          "type": "appointment_id",
          "value": "visit-12345"
        }
      ]
    }
  ],
  "limit": 50,
  "offset": 0,
  "total": 1
}