Configure an Adapter

Configuration model

"Custom Adapter" is the name of this installation type in ChartHero's settings UI. It is the same adapter contract described throughout these docs. After Custom Adapter access is enabled for an organization, an authorized organization admin can create a Custom Adapter installation from ChartHero organization settings. Creation only needs a display name and produces a suspended draft installation.

The suspended draft lets setup happen in pieces: external identifiers, connection, credentials, launch, and optional provider-linking behavior can be configured before the adapter is active. Activation runs readiness validation and fails closed until the active configuration has the required pieces. Partners do not configure a Custom Adapter by posting the JSON examples on this page to ChartHero.

How to read this page. The only part you actively configure is the In-app setup fields (next section), saved from the ChartHero UI. Everything after that — the stored field names and the full runtime JSON shapes — is reference for what ChartHero manages on your behalf. You never construct or POST those; they are shown only so you can reason about the runtime contract.

The form stores external identifiers, connection settings, launch settings, credentials, validation, and optional identity or directory behavior as individual fields. The version 1.0 configuration is base-url-only: your system exposes standard routes under one base URL rather than per-capability endpoint overrides. ChartHero assigns the environment label from the backend deployment. Organization admins configure the public identifier source and type values in ChartHero; send those exact values in patient, encounter, and provider external IDs. Change stable values such as identifier source keys and launch aliases only when your implementation plan already depends on specific values.

In-app setup fields

The Custom Adapter detail page groups setup into sections. Authorized users save editable fields from the ChartHero UI, and the Connection section provides the adapter validation action. Some fields are read-only or appear only when the corresponding setup surface is relevant for the installation.

Credential values are stored separately from normal settings. Do not paste authorization header values or launch key material into non-secret fields, logs, or support tickets.

The External Identifiers section is the source of truth for the source and type strings your adapter sends. source is a stable namespace key such as acme_care_prod. type is a stable identifier type within that source such as patient_id, mrn, or appointment_id. Patient and encounter type values are organization-configured tokens, not fixed ChartHero enums. For the currently published v1 provider directory and verified-email helper flows, provider identifiers use the enabled provider source with type: "provider_id".

When provider linking is enabled, ChartHero uses enabled provider identifier bindings from External Identifiers and stores the resolved provider_linking.identifier_sources[] runtime references. When a runtime flow needs one canonical provider actor source, exactly one enabled provider source/type tuple must be configured. required provider linking cannot be activated until exactly one provider identifier binding is enabled for the adapter.

Runtime reference (managed by ChartHero)

The field names below and the two JSON shapes that follow are reference only — the persisted runtime configuration ChartHero manages behind the form. They are useful when coordinating implementation details with ChartHero, but you never set or POST these values. (The Capabilities, Standard routes, Error diagnostics, and Validate connection sections further down describe what your system actually implements.)

Stored field names

These field names describe the persisted runtime configuration behind the form.

The source values shown throughout these docs — acme_care_prod for patient and encounter identifiers and provider_acme_care_prod for provider identifiers — are illustrative placeholders, not reserved keywords. Use the exact source and type values configured and enabled in ChartHero; mismatched identifier sources or types are rejected.

Appointment launch is supported: your adapter resolves an appointment from launch_state and returns it as the encounter in the launch-context response. Appointment search is a separate capability that is not yet available. The appointments_for_user capability stays off until ChartHero enables the generic appointment-search backend path, and the operation is withheld from the published contract until it ships.

Minimal patient-launch runtime shape

This is the smallest managed configuration shape for a first patient-bearing launch. It enables launch context and leaves provider linking disabled. (Here, source_type is the configured source registry type — custom — which is unrelated to the type in the {source, type, value} identifier triple your adapter sends elsewhere in these docs.)

{
  "base_url": "https://ehr.example.com/integrations/charthero",
  "contract_version": "1.0",
  "identifier_sources": [
    {
      "source": "acme_care_prod",
      "source_type": "custom",
      "allowed_identifiers": [
        {
          "subject_type": "patient",
          "type": "patient_id"
        },
        {
          "subject_type": "encounter",
          "type": "appointment_id"
        }
      ]
    }
  ],
  "outbound_auth": {
    "scheme": "authorization_header_value",
    "credential_alias": "external_api"
  },
  "capabilities": {
    "launch_context": true
  },
  "provider_linking": {
    "mode": "disabled",
    "auto_link_by_verified_email": false
  },
  "launch_profiles": {
    "encrypted": {
      "transport": "encrypted_payload",
      "route_alias": "acme-care-staging",
      "issuer": "acme-care-platform",
      "audience": "charthero",
      "keyset_credential_alias": "launch_keyset"
    }
  }
}

Minimal launch installations still need two credentials: the external_api authorization header value ChartHero sends verbatim to your adapter endpoints, and the launch_keyset credential used for encrypted launch links. Both are managed from the saved adapter detail page; the launch keyset can be generated by ChartHero or imported from partner-supplied keyset JSON.

Provider-linked runtime shape

Use this shape when your installation also stages provider rows and allows verified-email repair for missing provider links.

{
  "base_url": "https://ehr.example.com/integrations/charthero",
  "contract_version": "1.0",
  "identifier_sources": [
    {
      "source": "acme_care_prod",
      "source_type": "custom",
      "allowed_identifiers": [
        {
          "subject_type": "patient",
          "type": "patient_id"
        },
        {
          "subject_type": "encounter",
          "type": "appointment_id"
        }
      ]
    }
  ],
  "outbound_auth": {
    "scheme": "authorization_header_value",
    "credential_alias": "external_api"
  },
  "capabilities": {
    "launch_context": true,
    "provider_directory": true,
    "user_lookup_by_email": true
  },
  "provider_linking": {
    "mode": "required",
    "auto_link_by_verified_email": true,
    "identifier_sources": [
      {
        "source": "provider_acme_care_prod",
        "source_type": "custom",
        "target_kind": "provider",
        "allowed_identifiers": [
          {
            "subject_type": "provider",
            "external_object_type": "provider",
            "type": "provider_id"
          }
        ]
      }
    ]
  },
  "launch_profiles": {
    "encrypted": {
      "transport": "encrypted_payload",
      "route_alias": "acme-care-prod",
      "issuer": "acme-care-platform",
      "audience": "charthero",
      "keyset_credential_alias": "launch_keyset"
    }
  }
}

Credentials are stored separately from installation metadata. Do not embed authorization header values or launch key material in normal configuration payloads, logs, or support tickets.

Readiness and activation

New Custom Adapter installations start suspended. While suspended, setup fields can be incomplete, and validate-connection can be run once the base URL and authorization header value are saved. Suspended installations do not serve production launch traffic.

Activating the installation runs readiness checks against the current saved configuration. Readiness requires the base URL, authorization header value, enabled external identifiers needed by the configured flows, launch alias and launch keyset when launch context is enabled, and exactly one enabled provider source/type tuple when provider linking is required. Validation errors are returned as structured issues so the UI can show them next to the relevant setup fields.

Capabilities

Capability keys control which product surfaces ChartHero can use for an installation.

capabilities is an object whose keys are capability names and whose values are booleans. A capability is enabled only when its value is true; omitted or false capabilities are unavailable. validate-connection is always used for setup validation, but it is not a capability key.

Capability and route labels:

Standard routes

Expose the validate-connection health check plus the standard route for each enabled capability under the configured base URL. validate-connection is not a capability key in installation config.

POST {base_url}/v1/validate-connection
POST {base_url}/v1/launch/context
POST {base_url}/v1/providers/search
POST {base_url}/v1/users/resolve-by-email

Per-capability endpoint overrides are not part of the contract.

Error diagnostics

Error diagnostics is an optional installation setting, not a capability. When an organization enables it, ChartHero may post a small failure report to one more fixed route under the same base URL.

POST {base_url}/v1/diagnostics/errors

Rules:

1. The field is optional and off unless an organization admin turns it on. Existing installations keep the field absent and behave exactly as before.
2. There is no separate diagnostics URL or credential. ChartHero reuses the validated base_url and the external_api authorization header value.
3. It is not a capability key and is not part of capabilities. Enabling it adds the optional X-ChartHero-Diagnostic-Id header to adapter requests and allows the callback. It changes no request body, response body, route, or endpoint behavior, and your adapter needs no change to keep working.
4. Turning it off stops future diagnostics and stops sending that header on new calls. Neither setting changes the outcome of a source call, because ChartHero only delivers a diagnostic after the source result is final.

Implement and deploy the receiver before the setting is enabled. ChartHero does not probe your adapter for readiness, and enabling it against an adapter that does not serve the route only produces failed deliveries that ChartHero drops. See request IDs and errors for the request body, acknowledgement, and codes.

Validate connection

ChartHero calls POST /v1/validate-connection during setup and validation. The request body is empty JSON.

{}

A successful response is strict:

{
  "status": "ok"
}

Return 200 only when the Authorization header value is accepted for this installation and the requested contract version is supported. This endpoint is a connectivity health check. It is not a conformance test for launch context, provider directory, user lookup, schedules, or authorization policy.

Capability status

ChartHero may hide or disable product surfaces when a required capability is not configured, disabled, structurally invalid, missing credentials, or unavailable. Validation results are admin diagnostics and do not approve or block runtime operations.