Subject Linkage

A subject is anything ChartHero links by exact identifier: a patient, an encounter (your appointment or visit), or a provider. This page covers how your adapter expresses those subjects' identifiers.

External identifiers

External identifiers are the adapter primitive for exact linkage.

{
  "source": "acme_care_prod",
  "type": "patient_id",
  "value": "pat-123"
}

For patient and encounter subjects, source names the external system namespace configured for the organization. type names the identifier within that source, such as patient_id, mrn, appointment_id, or another token your organization configured. value is the stable upstream identifier. These are not ChartHero-local IDs. source is required even when the adapter has one default source.

In ChartHero organization settings, admins create or select a source, add subject bindings for patient, encounter, or provider, and enable the bindings for the Custom Adapter installation that may use them. The adapter must then send the exact source and type values shown there.

Linkable subjects

Return linkable subjects with external_ids[], even when there is only one identifier.

{
  "external_ids": [
    {
      "source": "acme_care_prod",
      "type": "appointment_id",
      "value": "apt-789"
    }
  ]
}

Common patient and encounter identifier type examples:

Provider and actor identifiers use a separate provider/actor external identifier primitive. They still use source, type, and value, but they do not identify patient or encounter subjects. The currently published provider directory and verified-email helper contract uses type: "provider_id" for provider identifiers.

Matching rules

ChartHero uses exact identifiers for adapter linkage. Do not rely on name-only matching, fuzzy demographic matching, provider role matching, specialty matching, department matching, service-line matching, or email as durable identity.

When multiple identifiers are returned for one subject, your system is asserting that they identify the same upstream subject. ChartHero does not make extra partner calls solely to prove that equivalence.

For a single patient or encounter subject, do not return conflicting values for the same resolved source/type tuple. Exact duplicate identifier triples are ignored. A single patient can carry multiple external IDs when they identify the same upstream patient.

Distinct external encounter or visit identifiers are outside the current contract unless ChartHero explicitly approves them for your installation.

Examples

Good provider identifiers:

{
  "external_ids": [
    {
      "source": "provider_acme_care_prod",
      "type": "provider_id",
      "value": "prov-456"
    }
  ]
}

Conflicting identifiers for one subject:

{
  "external_ids": [
    {
      "source": "acme_care_prod",
      "type": "patient_id",
      "value": "pat-123"
    },
    {
      "source": "acme_care_prod",
      "type": "patient_id",
      "value": "pat-999"
    }
  ]
}

Do not use email as durable identity in external_ids[]. Emails and NPI may be display or lookup evidence in approved flows, but exact provider linkage should resolve to a stable configured provider identifier such as type: "provider_id" in the current v1 provider helper contract.