> For the complete documentation index, see [llms.txt](https://docs.concurrence.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.concurrence.com/data/connectors-and-ehr.md).

# Connectors and EHR

How source data reaches the world model through FHIR import and dataset intake, and how agents read and change EHR data through integrations.

Source data reaches a workspace's [world model](/data/world-model.md) through FHIR import and authenticated [dataset intake](/data/customer-data-intake.md). During a conversation, an agent reads or changes an external system, such as an EHR, through the integration endpoints its state offers. The world model records observations with source provenance; it does not send them to external systems.

## Data Sources <a href="#connector-types" id="connector-types"></a>

A data-source record names an external system for a workspace. The data-source create contract accepts `ehr`, `fhir_store`, and `snowflake`. The platform stores the record and returns it on read, along with its stored sync history and event counts. It does not poll the source or send writes to it, so load the source's records through one of the ingestion paths below.

Generic `smart_fhir`, `rest_api`, `file_drop`, and `webhook` data-source types are not supported. A `webhook` sync strategy is a stored configuration value; it does not create a webhook receiver.

For HL7v2 ADT/SIU feeds or outbound hospital messages, use [Healthcare Interoperability](/data/healthcare-interoperability.md) to scope the required integration and its evidence. These capabilities are not implied by a FHIR data source or by a catalog label.

## Ingestion Paths

| Path                                                                                           | Use it for                                                                                      | Freshness                                                 |
| ---------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------- | --------------------------------------------------------- |
| [FHIR import](https://docs.concurrence.com/developer-guide/platform-api/data-world-model/fhir) | FHIR R4 bundles from an EHR or FHIR store                                                       | Depends on when you submit and on asynchronous projection |
| [Dataset intake](/data/customer-data-intake.md)                                                | Files against a registered dataset contract, uploaded or discovered from a mapped intake source | Depends on submission and processing                      |

Supported ingestion paths attach source-specific confidence and provenance when data enters the world model. Agents and projections can then distinguish higher-ranked from lower-ranked source observations without hiding either source. This ranking is not a calibrated probability that an observation is correct.

Accepted input is not the same as agent-visible state. Confirm mapping, projection, and the read path the agent uses before a workflow depends on the data.

## EHR Integration

During a conversation, the agent reads or changes EHR data through the [integration endpoints](https://docs.concurrence.com/developer-guide/platform-api/integrations) that its current state offers. An endpoint call's result is the evidence of what the destination accepted. Information captured during a conversation stays a source-attributed observation in the world model; it is not written to the EHR unless the agent calls an endpoint that writes it.

### FHIR R4 and SMART Authentication

FHIR resource access, backend authentication, and EHR app launch are separate capabilities.

SMART Backend Services signing and token-exchange utilities are part of the platform, but there is no generic `smart_fhir` data-source type. Do not infer an active Epic integration from a catalog entry, signing endpoint, or stored configuration. Confirm the supported integration and enrollment with the implementation owner. Backend authentication does not establish EHR-context launch for a user-facing application.

The FHIR API supports patient search, resource CRUD with entity cross-referencing, resource history with field-level change tracking, and bundle import. It serves a broad set of clinical resource types - including Observation, MedicationStatement, FamilyMemberHistory, and QuestionnaireResponse - and supports patient-scoped filtering. Actual read and write availability depends on the resource type, credentials, and granted scopes.

### Custom Token Exchange

Some APIs use a non-standard token-exchange flow instead of OAuth or static keys. The API requires a workspace-level secret and one or more dynamic, per-request parameters (such as a user identifier) to mint a short-lived bearer token for each call. This pattern is common in healthcare platforms where each API call must be scoped to a specific end user or tenant, but the token issuance mechanism does not follow the OAuth specification.

The `custom_token_exchange` auth type handles this automatically. At configuration time, the operator provides the exchange endpoint URL, a workspace secret, and a mapping of which request parameters feed which exchange-call headers or body fields. At runtime, the platform mints a fresh bearer token from the workspace secret plus the per-request identifiers for each call.

Exchange URLs are validated at both configuration time and runtime to prevent requests from reaching internal networks, and secret templates are restricted to prevent injection.

### Systems Without a Supported API

The Platform API does not provide a browser or computer-use integration tier. Systems without a supported API require a separately designed integration path; do not assume that file deduplication, source identity, or authorization semantics transfer unchanged to portal automation.

### Handling External System Limitations

Each external system has its own availability, rate limits, update cadence, and acceptance rules. Check each integration call's result and reconcile an ambiguous outcome at the destination before retrying it. Supported projections resolve competing observations using their source-ranking rules, but a higher-ranked record can still be stale or incomplete. Validate required fields, relationships, and freshness at the consuming workflow.

### Agent-Initiated Record Creation

An agent can invoke the patient-creation tool when the authored workflow has collected the required fields. That tool creates a workspace entity and emits a `patient.created` event; it does not create a record in an external system. To create the patient in an EHR, the agent calls an integration endpoint that does.

{% hint style="danger" %}
Recording the patient's intent is not the same as confirming that the external system accepted a write.
{% endhint %}

## Entity Resolution

### Automatic External Identity Binding

An opted-in data source can create external-user bindings for eligible patients and guardians after their entities become available in the serving view. The binding lets a supported external identity resolve to the corresponding workspace entity at conversation start.

Binding runs through periodic reconciliation, not during the initial entity-resolution fold. An accepted source record or resolved identifier therefore does not mean that login recognition is ready immediately. Both projection and binding must complete.

**How it works:**

* The source explicitly enables automatic binding and identifies the external integration to use. Its canonical source identifier must yield the same subject key that the external application supplies at login.
* Reconciliation selects eligible, materialized person entities from that source within the workspace.
* It binds the source's external subject key to the resolved entity without substituting a display name or assuming that a medical-record number is the login key.
* Transient binding failures can be retried on a later pass. A key already bound to a different entity is left unchanged and reported for investigation.

This automatic path covers patient and guardian/caregiver records; practitioner records are excluded. It does not assign clinical roles or replace the separately configured external-principal authorization policy.

The feature is available only where the required serving data and identity integration are provisioned. Validate recognition with the actual external subject key before launching a workflow that depends on it.

Current FHIR entity resolution maps supported resource types and references to source-scoped identifiers. This keeps repeated events from the same source attached to the same entity and creates explicit FHIR-derived relationships between related resources.

The current Platform pipeline does not perform fuzzy patient matching or write new cross-source `same_as` merge edges. Existing graph and duplicate APIs can still return historical `same_as` edges created by an earlier resolver. Treat those records as historical evidence, not proof that active connectors currently merge people by phone, email, name, or date of birth.

Caller recognition is a separate path. Customer applications can use verified external-user bindings, and supported channel flows can use scoped identifiers such as a caller phone number. An unmatched caller remains anonymous until the workflow resolves or creates an entity explicitly.

## Console Views

### Facility Location Mapping

When location, facility, or place entities are loaded from clinical systems, the Data Insights dashboard renders their geographic distribution on a live map. Entities with direct coordinates (latitude and longitude) are plotted immediately. Entities that carry street addresses but no coordinates are geocoded on demand. This gives operations teams a visual picture of facility coverage without requiring manual coordinate entry.

## Pipeline Observability

The Platform API provides read-only pipeline endpoints over stored data: pipeline totals, source listing, source event history, outbound summaries, entity resolution metrics, and throughput time series. They report stored data, not live polling or sync state.

### Data Source Freshness

The per-source connector-health operation reports a freshness category for each source, based on how recently it last ingested data:

| Category  | Meaning                                                                                       |
| --------- | --------------------------------------------------------------------------------------------- |
| **Fresh** | Data arrived within the last five minutes. The source is actively producing events.           |
| **Stale** | Last ingestion was between five and sixty minutes ago. The source may be experiencing delays. |
| **Quiet** | No data in over an hour. The source may be down, or there may simply be no new records.       |
| **Never** | No data has ever been ingested from this source.                                              |

Freshness is computed from the timestamp of the most recent ingested event, so it reflects whether data is flowing. Per-source ingestion rates (events per minute, per hour, and over the last 24 hours) accompany the category.

### Sensing-to-Action Latency

Pipeline latency metrics describe the timestamps available to the instrumented path. They do not automatically include time between an upstream clinical event and its detection. For an end-to-end freshness claim, preserve the source event timestamp and verify each boundary through agent-visible state and the external outcome, as described in [Healthcare Interoperability](/data/healthcare-interoperability.md#design-for-measured-freshness).

The loop-latency operation reports hourly pair counts and median values. Use changes in that distribution to select periods for investigation, then inspect source health, processing failures, and workload. The shape of a latency chart alone does not identify the cause.

{% hint style="info" %}
See [Data Quality Analytics](/intelligence-and-analytics/intelligence.md) for the dashboard metrics. For API endpoints and integration details, see the [Connector Runner](https://docs.concurrence.com/developer-guide/platform-api/data-world-model/connector-runner) and [FHIR](https://docs.concurrence.com/developer-guide/platform-api/data-world-model/fhir) sections of the developer guide.
{% endhint %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.concurrence.com/data/connectors-and-ehr.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.