Stable machine-readable error code. Use letters, numbers, '.', '_', ':', or '-'.

Error Code

Message

Retryable

Optional safe field-level details. Use at most 8 entries; keys are 64 characters or fewer, values are 256 characters or fewer.

Validation Details

AdapterErrorResponse

Actor Type

Role

AppointmentParticipant

CompactJweProtectedHeader

Organization-level external identifier source alias. Send this even when the adapter has one default source.

Source

Identifier kind, such as `patient_id` or `appointment_id`; this is not the patient or encounter object itself.

Type

Value

EncounterExternalIdentifier

Timezone-aware appointment end time. When present, it must not be before start_at.

End At

Stable identifiers for one upstream encounter. Each source/type tuple may appear at most once for that subject.

External Ids

Participants

Timezone-aware appointment start time. Use an explicit offset or Z.

Start At

EncounterPreview

Optional top-level actor evidence for the ChartHero user expected to resolve the launch.

Expiration time as a NumericDate. It must be after iat and no more than five minutes after iat.

Unique replay-protected launch identifier.

Required adapter-owned JSON object. Use small opaque workflow handles or correlation ids; do not include raw PHI, secrets, clinical content, documents, transcripts, or setup defaults.

Launch State

EncryptedLaunchPayload

Optional launch-access evidence for the ChartHero user expected to resolve the launch link. Provide `actor_id` when your system stores the ChartHero public user id, `email` when your system knows the verified ChartHero user email, and `external_ids` when provider linking is enabled and your system has durable provider/user identifiers. If multiple criteria are present, every provided criterion must match; direct actor fields do not override conflicting external IDs.

ChartHero public actor identifier for the user expected to resolve this launch link. When supplied, it must match the authenticated ChartHero user's public actor id.

Actor Id

Email for the ChartHero user expected to resolve this launch link. ChartHero normalizes and compares this case-insensitively against a verified ChartHero identity.

Email

External provider identifiers for the user expected to resolve this launch link. When present, every supplied identifier must match the resolved ChartHero actor linkage. These identifiers are preferred when the partner system has a stable provider/user id.

EncryptedLaunchProviderIdentifierSubject

The only successful diagnostics acknowledgement.

Status

ErrorDiagnosticAcknowledgement

The six direct HTTP-boundary observations eligible for a diagnostic.

ErrorDiagnosticCode

One failure ChartHero observed at the Custom Adapter HTTP boundary while calling a source endpoint. The body carries no PHI, no partner response content, and no ChartHero source request identifier.

ChartHero-minted correlation value. It equals the X-ChartHero-Diagnostic-Id header on this callback and the same header on every transport attempt of the source call.

Diagnostic Id

Fixed catalog guidance for this endpoint, code, and status combination. ChartHero call sites cannot supply arbitrary text.

Timezone-aware UTC completion time of the final selected source attempt.

Occurred At

Received HTTP status, or null for transport_timeout and transport_error, including read failures after response headers were received.

Response Status

Registered adapter source endpoint path ChartHero was calling. It is never a full URL and never the diagnostics path itself.

Source Endpoint

ErrorDiagnosticRequest

Authenticated ChartHero actor for this callback. Present when provider linking is required or when ChartHero has a valid actor context to send. This is enriched ChartHero user context, not the raw encrypted-launch actor object.

Validated launch jti from the encrypted launch payload.

Launch Id

Opaque JSON object copied from the encrypted launch payload. Adapters own its meaning; ChartHero does not interpret it.

LaunchContextRequest

Encounter or appointment context ChartHero should open. Required for encounter launches and mutually exclusive with top-level patient.

Patient-only launch context. Return when the launch is not tied to an encounter or appointment. ChartHero creates a new local encounter for each newly minted patient-only launch. Omit when returning encounter context.

LaunchContextResponse

Launch keys. Exactly one key must have status active.

Keys

Version

LaunchKeyset

LaunchKeysetEntry

Optional setup defaults. If the object is present, at least one setup default field is required. First-level null values are treated as omitted. Non-null phone_call may only be combined with mode=phone_call.

Mode

ChartHero core template id provisioned as selectable for the launching user.

Template Id

LaunchSetupDefaults

To E164

LaunchSetupPhoneCallDefaults

Ethnicity

Stable identifiers for one upstream patient. Each source/type tuple may appear at most once for that subject.

First Name

Last Name

Middle Name

Phone Cell E164

Phone Home E164

Phone Work E164

Race

Suffix

Patient

PatientExternalIdentifier

Required for provider directory and verified-email responses.

Active

Display Name

Stable identifiers for one upstream provider. Each source/type tuple may appear at most once for that subject.

ProviderActor

ProviderDirectoryProvider

Configured provider identifier source alias.

External provider identifier type. MVP supports provider_id.

ProviderExternalIdentifier

ChartHero actor context sent to partner adapter endpoints. `actor_type` uses the same discriminator vocabulary as the public External API actor resource and is currently always `user` for launch-context adapter calls. `actor_id` is the ChartHero public actor identifier; `email`, name, specialty, and role fields describe the authenticated ChartHero user in the launching organization; `external_ids` contains partner provider/user identifiers only when provider linking exists.

Whether the ChartHero user actor is active in the launching organization. Uses the same active-state meaning as public External API user actors.

Stable ChartHero public actor identifier.

Actor discriminator. Currently always `user` for adapter calls.

Verified ChartHero user email when available.

Partner/provider identifiers mapped to this ChartHero actor when provider linking exists for the installation.

Functional Roles

Governance Role

Specialty

ProviderIdentifierSubject

Limit

Offset

ProviderSearchPaginationRequest

Has More

Omit or return null when has_more is false.

Next Offset

ProviderSearchPaginationResponseComplete

Required and greater than offset when has_more is true.

ProviderSearchPaginationResponseHasMore

Active Only

Updated Since

ProviderSearchQuery

ProviderSearchRequest

Pagination

Providers

ProviderSearchResponse

ResolvedExternalUser

Verified ChartHero user email. Partner lookup should treat email case-insensitively and return one active external user or an error.

Purpose

UserResolveByEmailRequest

UserResolveByEmailResponse

ValidateConnectionRequest

ValidateConnectionResponse

ChartHero sends the saved adapter credential verbatim as the Authorization header value, for example `Bearer abc123`, `ApiKey abc123`, or a bare token.

Authorization

Contract for partner-implemented adapter endpoints that ChartHero calls. ChartHero-hosted public API routes are intentionally excluded.

ChartHero Adapter Contract

Optional receiver for ChartHero-observed adapter failures. It is sent only when an organization enables error diagnostics for the installation, and ChartHero reuses the configured base URL and `Authorization` value. ChartHero reports only failures observed at the HTTP boundary of a source call: transport timeouts, transport errors, non-2xx statuses, oversized responses, non-JSON content types, and successful responses that are not one JSON object. It does not report semantic validation of an otherwise valid JSON response, ChartHero-local failures, or diagnostics delivery failures.

Correlate the callback with the source call using `X-ChartHero-Diagnostic-Id`, which is identical on the source attempts and on this callback. `X-ChartHero-Request-Id` on this callback identifies only the callback request; it is never the source request identifier.

Respond with exactly `{"status":"accepted"}` and HTTP 200. ChartHero makes one delivery attempt per eligible failure and never retries it, so treat a missed diagnostic as expected rather than as a gap to reconcile. Log the diagnostic ID and code; the body intentionally carries no PHI, credentials, or source request content.

Adapter contract version ChartHero expects for this request.

X-ChartHero-Contract-Version

Opaque request identifier for partner logs and support.

X-ChartHero-Request-Id

ChartHero-minted diagnostic identifier. It must equal the request body `diagnostic_id`; return `400 invalid_request` when they differ.

X-ChartHero-Diagnostic-Id

invalid_request, unsupported_contract_version

Resolve adapter-owned launch_state into the patient plus optional encounter and setup defaults ChartHero should open.

Sent only when error diagnostics is enabled for the installation. The same value is repeated on every ChartHero retry of this call and is the correlation value for any resulting diagnostics callback. Log it; do not require it.

Return provider directory rows for reviewed mapping and provider linking. This endpoint is not actor-scoped.

Optional helper for creating provider links from a verified ChartHero user email to stable partner external identifiers.

Lightweight non-PHI connectivity health check. ChartHero sends an empty JSON body and expects a strict `{"status":"ok"}` response.

Example partner-configured adapter base URL

Endpoint	Summary
`POST /v1/checklist-recommendations/fetch`	Fetch checklist recommendations
`POST /v1/diagnostics/errors`	Report error diagnostic
`POST /v1/launch/context`	Get launch context
`POST /v1/providers/search`	Search providers
`POST /v1/users/resolve-by-email`	Resolve user by verified email
`POST /v1/validate-connection`	Validate connection

Adapter Reference

Partner base URL

Authentication

OpenAPI JSON

Adapter endpoints

Validate connection

Launch context

Provider directory

Checklist recommendations

Verified-email lookup

Error diagnostics

ChartHero Adapter Contract

Next steps

Adapter Reference

Partner base URL

Authentication

OpenAPI JSON

Adapter endpoints

Validate connection

Launch context

Provider directory

Checklist recommendations

Verified-email lookup

Error diagnostics

ChartHero Adapter Contract

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%;}Adapter quickstart

Launch flow

Testing checklist

Adapter quickstart