Configure the adapter
Confirm base URL, capabilities, credentials, and validation.
Adapter setup
Adapter Quickstart
Implement the minimum adapter pieces needed for a first patient or appointment launch.
v1.0What you are building
An adapter is the server-side contract for workflows where ChartHero launches from an external system and calls that system back for trusted context.
You are building and hosting a server, not just a link. A launch has three
partner-owned parts: (1) a backend that mints encrypted launch links, (2) a
POST /v1/validate-connection endpoint, and (3) a POST /v1/launch/context
endpoint that ChartHero calls back for the real patient or appointment context.
The link alone does nothing — ChartHero opens whatever your launch-context callback
returns, so you must stand up and host that callback at a registered base URL.
| Surface | Direction | Use it when |
|---|---|---|
| Public API | Your server calls ChartHero | You need to read ChartHero encounters, documents, transcripts, audio links, actors, or webhook follow-up resources. |
| Adapter | ChartHero calls your server | ChartHero needs to launch from your system, verify external patient or encounter identifiers, or map ChartHero users to your providers. |
Most first launches require only four pieces: a configured adapter base URL, a working validate-connection endpoint, encrypted launch links, and a working launch-context endpoint.
Required vs conditional pieces
| Piece | Label | Build when |
|---|---|---|
| Adapter base URL | Required for setup | Every adapter installation |
POST |
Required for setup | Every adapter installation |
| Encrypted launch link | Required for first launch | Your UI launches users into ChartHero |
POST |
Required for first launch | ChartHero opens patient-bearing launch state |
POST |
Conditional | Provider rows are staged for reviewed mapping |
POST |
Conditional | ChartHero requests partner-recommended encounter checklist items |
POST |
Optional approved flow | Verified-email lookup or auto-link repair is explicitly approved |
First launch path
| Step | Build | Done when |
|---|---|---|
| 1 | Create the adapter installation | An authorized organization admin adds a Custom Adapter installation with a display name. It starts suspended. |
| 2 | Configure external identifiers | The installation has the patient, encounter, and provider identifier bindings it will accept, enabled for this adapter where needed. |
| 3 | Configure connection | The installation has the adapter base URL, authorization header value, and a passing validate-connection check. |
| 4 | Configure launch | The detail page has launch context enabled, a launch alias, and a generated or imported launch keyset. |
| 5 | Create encrypted launch URLs | Your UI can send users to https://app.charthero.ai/launch/{launch_alias}?ctx=<compact-jwe> without raw PHI in query parameters. |
| 6 | Implement POST |
ChartHero can submit launch_state and receive either patient context or encounter identifiers with required embedded patient context. |
| 7 | Activate and test the flow end to end | Activation readiness passes, and expired launches, replayed launches, bad identifiers, denied access, and successful launches behave predictably. |
Keep external identifier source and type values, provider mappings, and launch
aliases stable after launch links, subject links, or provider mappings exist.
If provider linking is part of your adapter workflow, configure it in Identity & Directory:
first enable the provider external identifier in the External Identifiers section,
then choose optional or required, and enable provider directory or
verified-email lookup only for approved flows. Use the exact provider source
and type shown in ChartHero for provider external_ids[]; the published v1
provider directory and verified-email helper contract uses type: "provider_id".
Minimal endpoint set
For a first patient or encounter launch, expose these routes under the configured adapter base URL:
POST {base_url}/v1/validate-connection
POST {base_url}/v1/launch/context
If provider linking uses staged provider rows, also expose:
POST {base_url}/v1/providers/search
If encounter checklist recommendations are enabled, also expose:
POST {base_url}/v1/checklist-recommendations/fetch
If verified-email lookup is explicitly enabled, also expose:
POST {base_url}/v1/users/resolve-by-email
Validate connection first
validate-connection is a strict connectivity check. It does not prove launch context, provider directory, user lookup, or authorization behavior.
Request:
{}
Success response:
{
"status": "ok"
}
Return 200 only when the Authorization header value is valid for the adapter installation and the requested contract version is supported.
Build the launch round trip
The launch itself is a four-step round trip: you mint an encrypted link, ChartHero validates it, ChartHero calls your launch-context endpoint, and you answer with either top-level patient context or encounter context with an embedded patient in ChartHero's schema.
Launch Flow walks the whole loop with the link shape, the
launch_state scratchpad, actor validation, and the response schema inline. Then:
- Launch Links — exact JWE header rules, the full encrypted payload, and the generation checklist.
- Launch Context — the complete callback request, every response field, and all denial cases.
- Checklist Recommendations — the encounter-scoped recommendations callback, response hierarchy, and examples.
Next steps
Adapter authentication
Review Authorization header credentials and launch keysets.
Launch flow
See the complete browser-launch and callback sequence.