Provider Linking

Provider linking modes

Most patient + appointment adapter workflows use disabled — read on only if you need ChartHero to map the launching user to your upstream provider identity.

Each adapter installation chooses one provider-linking mode.

Authorized users configure provider linking from the Custom Adapter installation detail page in ChartHero organization settings. First, configure and enable the provider external identifiers needed by the approved linking flows in the External Identifiers section. Then, in Identity & Directory, choose disabled, optional, or required, and enable provider directory or verified-email lookup only when those flows are approved.

The provider external identifier source is not inferred from the provider-linking mode. It is the enabled provider binding shown in External Identifiers. Your adapter must use the exact provider source and type shown there for provider external_ids[]. The currently published provider directory and verified-email helper contract uses type: "provider_id".

When linking is required, ChartHero resolves the authenticated ChartHero user to a mapped external actor before affected partner calls. If no provider identifier binding is enabled for the adapter, activation fails. If a runtime flow needs one canonical provider actor source, exactly one enabled provider source/type tuple must be configured; zero or multiple tuples fail closed as configuration errors. If no valid link exists at runtime and no approved auto-link path can repair it, ChartHero fails closed before calling the partner endpoint.

Choose the mode based on the launch and authorization model:

For optional mode, document the fallback during onboarding. Common fallbacks include allowing patient context without mapped provider identifiers for a narrow adapter workflow or limiting setup defaults until a provider link exists.

Choose a linking path

Use the least restrictive mode that still matches the partner authorization model.

Endpoint labels:

Launch actor evidence

Encrypted launch links may include top-level actor to state which ChartHero user is expected to open the link. This actor is validation evidence, not the final provider link itself.

{
  "actor": {
    "actor_id": "11111111-1111-4111-8111-111111111111",
    "email": "clinician@example.com",
    "external_ids": [
      {
        "source": "provider_acme_care_prod",
        "type": "provider_id",
        "value": "prov-456"
      }
    ]
  }
}

Use actor_id when your system stores the ChartHero public user id. Use email when your system only knows the verified ChartHero user email. Use external_ids[] when provider linking is enabled and your system has durable provider/user identifiers. When provider linking is optional or required and more than one field is present, all provided criteria must match the authenticated ChartHero user. Email matching is case-insensitive after normalization and requires a matching verified ChartHero identity. Direct fields such as actor_id and email do not override conflicting external_ids[] when provider linking is enabled.

When provider linking is disabled, omit actor.external_ids[]; ChartHero does not use provider identifiers for disabled provider-linking installations. If a schema-valid encrypted launch includes actor external IDs anyway, ChartHero ignores them for provider linkage instead of rejecting the launch. You may still use actor_id or verified email as direct actor validation criteria, and those direct criteria must match the authenticated ChartHero user when present. After validation, ChartHero may still send the enriched callback actor with external_ids: [] so your adapter can authorize or configure the request from ChartHero actor context.

When provider linking is required, top-level actor must include at least one of actor_id, email, or external_ids[]. If direct actor evidence matches but the provider link is missing, ChartHero may use verified-email lookup to repair the link only when user_lookup_by_email and provider_linking.auto_link_by_verified_email are approved for the installation.

Provider directory

Provider directory is the standard way to stage provider rows for reviewed mapping.

POST {base_url}/v1/providers/search

Request:

{
  "query": {
    "active_only": true,
    "updated_since": null
  },
  "pagination": {
    "limit": 100,
    "offset": 0
  }
}

Response:

{
  "providers": [
    {
      "external_ids": [
        {
          "source": "provider_acme_care_prod",
          "type": "provider_id",
          "value": "prov-456"
        }
      ],
      "email": "clinician@example.com",
      "display_name": "Dr. Chris Smith",
      "first_name": "Chris",
      "last_name": "Smith",
      "active": true
    }
  ],
  "pagination": {
    "limit": 100,
    "offset": 0,
    "next_offset": 100,
    "has_more": true
  }
}

Each provider row must include external_ids[] and active: true. Provider identifiers use source, type, and value. source is the enabled provider identifier source for the adapter installation, and the durable provider identifier type is provider_id in the currently published provider directory contract. Do not return different values for the same source/type tuple on one provider. email, display_name, first_name, and last_name are display and mapping aids. They do not replace stable external IDs. NPI is not a durable provider external ID in version 1.0; if an adapter returns NPI, ChartHero treats it only as display or evidence metadata outside external_ids[].

Pagination rules:

1. pagination.limit must be 100.
2. pagination.offset must match the requested offset.
3. When pagination.has_more is true, include pagination.next_offset and make it greater than the requested offset.
4. When pagination.has_more is false, omit pagination.next_offset or return it as null.
5. ChartHero stops provider directory sync after 500 pages with provider_directory_page_limit_exceeded.
6. ChartHero stops provider directory sync after more than 50,000 providers with provider_directory_provider_limit_exceeded.

Verified-email lookup

Verified-email lookup is optional and disabled by default.

POST {base_url}/v1/users/resolve-by-email

Request:

{
  "email": "clinician@example.com",
  "purpose": "launch_user_mapping"
}

Response:

{
  "external_user": {
    "external_ids": [
      {
        "source": "provider_acme_care_prod",
        "type": "provider_id",
        "value": "prov-456"
      }
    ],
    "active": true,
    "email": "clinician@example.com",
    "display_name": "Dr. Chris Smith"
  }
}

This helper can create a provider link only from returned stable external IDs. Returned identifiers use the enabled provider identifier source plus type: "provider_id" in the currently published helper contract, and each source/type tuple may appear at most once for the external user. The email itself is lookup input and display evidence, not the durable identity. Treat the requested email case-insensitively and return exactly one active external user, 404 external_user_not_found, or 409 email_ambiguous. A lookup response that only has NPI evidence cannot auto-link a ChartHero user in version 1.0.

Return 404 external_user_not_found when the verified email has no match. Return 409 email_ambiguous when it resolves to more than one external user.