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

# Connectors and EHR

## Connector System Overview

The connector system links supported external systems with the workspace's [world model](/data/world-model.md). It ingests data from EHR platforms, FHIR stores, REST sources, files, and webhooks; preserves source confidence and provenance; and delivers eligible events to configured destinations.

Data sources and sync behavior are configured through the Platform API and the Developer Console rather than a separate connector API. The system supports multiple connector types - each producing raw records that pass through a unification engine before entering the world model as events.

## How Connectors Work

External healthcare systems are unreliable in ways that are difficult to predict. EHR APIs go down for maintenance without warning. FHIR stores enforce rate limits that change between environments. Some systems only accept inbound writes during business hours. A write that succeeds today may be silently rejected tomorrow.

The connector system combines push-based and scheduled ingestion with connector-specific checkpoints and deduplication. Checkpointed polling paths can recover eligible inbound changes on a later poll. Outbound delivery has different semantics: the standard automated path is at-most-once and reports a failed write without automatic reconciliation, while approved proposals for the idempotent FHIR sink types can be retried under their separate delivery policy.

**Inbound** data arrives through two mechanisms depending on the source system's capabilities:

* **Scheduled sync** - The connector checks external systems on the cadence configured for that source. Incoming data is deduplicated by content hash - if the same record is returned twice, no duplicate event is created.
* **Real-time webhooks** - Supported integrations can receive push notifications as changes happen. Request verification, duplicate handling, and whether the path fetches a full resource before mapping are connector-specific.

Both paths feed into the same entity resolution and enrichment pipeline. Source-specific adapters handle quirks such as business-hour gating, incremental sync, reference data handling, and rate limit management.

**Outbound** write-back first requires an eligible source and destination scope. The unattended path also applies its confidence threshold; a review-configured destination instead stages the source-eligible event at any confidence for an explicit decision. Both paths pass the event payload to connector-specific validation and mapping without rebuilding the entity projection at delivery time. A workspace can target multiple external systems, and a failure at one destination does not block evaluation for another.

There is also a throughput problem. Agents may generate scheduling requests, insurance checks, and record updates faster than an external system can accept them. The world model preserves the patient interaction and requested change, while the connector reports the outcome of each eligible delivery rather than presenting an unconfirmed write as complete.

## Connector Types

| Connector      | Inbound | Outbound | Push-Based        | Scheduled Sync | Auth                           |
| -------------- | ------- | -------- | ----------------- | -------------- | ------------------------------ |
| **EHR**        | Yes     | Yes      | Where supported   | Fallback       | Per adapter                    |
| **FHIR Store** | Yes     | Yes      | Via Subscriptions | Primary        | API key or service credentials |
| **SMART FHIR** | Yes     | Yes      | Via Subscriptions | Primary        | SMART Backend Services         |
| **REST API**   | Yes     | No       | No                | Primary        | Configurable                   |
| **File Drop**  | Yes     | No       | No                | Primary        | Managed credentials            |
| **Webhook**    | Yes     | No       | Yes               | No             | Signature verification         |

**EHR connectors** use dedicated, EHR-specific adapters. Each adapter handles the target system's authentication, FHIR resource mapping, rate limits, and data format translation. Where the EHR supports event notifications, the adapter receives change events as they happen.

**FHIR Store connectors** connect directly to FHIR R4 stores with typed configuration. Outbound write-back uses optimistic locking to prevent lost updates.

**SMART FHIR connectors** use the same FHIR R4 capabilities as FHIR Store connectors, but authenticate via SMART Backend Services - the standard machine-to-machine auth flow for healthcare APIs. Use this type when the EHR system requires SMART App Launch authentication.

**REST connectors** read HTTP endpoints on a schedule with multiple pagination strategies, configurable authentication, and circuit breaker protection. Content-hash deduplication prevents duplicate events from unchanged data.

**File Drop connectors** watch a cloud storage location for new files. They parse CSV, NDJSON, FHIR Bundles, and raw JSON - useful for bulk data imports where a partner drops a file on a schedule.

For supported cloud-folder sources, the connector also ingests cloud-native documents, spreadsheets, presentations, and drawings by exporting them to retrieval-ready text or PDF. File shortcuts resolve to their targets, folder shortcuts are traversed safely, and the exported filename reflects the format the intake pipeline actually receives. Unsupported native file types are skipped rather than published as empty documents.

**Webhook connectors** receive supported inbound HTTP notifications from external systems. Signature or secret validation, retry behavior, resource fetching, and duplicate suppression vary by connector. Integrations should preserve the sender's stable event identifier when one is available and tolerate repeated notifications.

Reliability controls vary by connector and operation. Supported paths can use source checkpoints, content-hash deduplication, bounded retries, circuit breakers, or failure records, but integrations should rely only on the behavior documented for their selected connector.

### Unification Engine

The unification engine is not a connector itself. It is the transformation layer that supported inbound connectors feed into. Raw records can be mapped to world model events using configurable rules with dot-path field extraction for nested source data. Generic sources may need only connector configuration and mapping rules; a new vendor protocol or operation can still require adapter code.

### Data Freshness

How quickly data appears in the world model depends on the connector type and configuration:

* **Webhook and push-based EHR connectors** - Usually lower latency than polling, but timing still depends on the source, queueing, mapping, and asynchronous world-model projection.
* **Scheduled connectors (REST and supported FHIR or EHR sources)** - Determined by the source configuration.
* **File drop** - Depends on when the file is deposited and processed.

Supported connector ingestion paths attach source-specific confidence and provenance when data enters the world model. Agents and projections can then distinguish stronger source classes from less certain observations without hiding either source.

<figure><img src="/files/E9JWnP2X3jBjNEJF3ym8" alt="Connector data flow: external systems through connector types to unification engine to world model"><figcaption></figcaption></figure>

## EHR Integration

Clinical data flows in both directions: external records enter the world model so the agent has context, and eligible world-model events can be delivered to configured destinations. Information captured during a conversation remains a source-attributed observation unless an outbound policy selects it for delivery. The agent reads projected entity state, while outbound connectors receive the eligible event payload and report the destination outcome separately.

### FHIR R4 and SMART Authentication

Both the `fhir_store` and `smart_fhir` connector types share the same underlying FHIR R4 capabilities - the difference is the authentication method. For EHR systems that implement the SMART App Launch specification, the connector supports SMART Backend Services authentication: the standard machine-to-machine auth flow for healthcare APIs.

The platform handles token acquisition, caching, and renewal automatically. Per-resource scoping (e.g., `system/*.read`, `system/Patient.write`) controls which resources the connector can access.

SMART FHIR data sources can be created and managed entirely through the Developer Console or the Platform API. When you provide a private key during setup, the platform automatically provisions it to secure storage and stores only a reference - the key value is never persisted in the data source configuration or returned in API responses.

The FHIR API supports patient search, resource CRUD with entity cross-referencing, resource history with field-level change tracking, bundle import, and scoped sync failure investigation. 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 still depends on the connector type, destination capabilities, 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 connector 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.

### Vendor-Specific Adapters

For EHR systems with non-standard FHIR implementations or proprietary authentication requirements, the connector includes purpose-built adapters that handle vendor-specific quirks transparently. These adapters manage authentication flows, non-standard pagination schemes, adaptive rate limiting, and resource type tiering by change frequency - while feeding into the same world model pipeline as all standard FHIR connectors.

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

### Handling External System Limitations

Real-world EHR integrations face problems that no API specification can solve. **Checkpointed inbound polling** can resume from committed source progress on a later poll. **Outbound failures** remain visible and are not assumed to have reconciled automatically. **Stale or conflicting data** is resolved through the world model's confidence-based projection. **Partial failures** in supported multi-step workflows are reported per step. **Inconsistent data formats** are normalized into a consistent entity representation. Browser-only systems are outside the general connector contract and require a separately validated integration.

## Outbound Write-Back

When the connector receives an outbound event, source eligibility, test-event exclusion, and entity-type scope apply before unattended delivery or proposal staging. The unattended path also applies its confidence threshold. A review-configured destination stages an otherwise eligible event at any confidence instead of calling the target immediately. The connector uses the event payload rather than rereading the entity projection at delivery time.

Outbound mapping uses connector-specific payload transforms and deterministic matching rules. For example, supported insurance workflows can match a stated carrier against a practice payer list using aliases, substring matching, and bounded fuzzy matching. An unmatched or invalid value is reported according to the operation's failure behavior rather than sent through a model-based fallback.

### Outbound Authorization Paths

Unattended writes and human-reviewed writes use different authorization paths. A review decision is not an extra confidence gate: source and destination eligibility apply before staging, while approval of the specific proposal replaces the unattended confidence check at delivery.

| Check                            | Applies To                             | What It Checks                                                                                                 |
| -------------------------------- | -------------------------------------- | -------------------------------------------------------------------------------------------------------------- |
| **Source eligibility**           | Both paths, before staging or delivery | Is the event from an allowed source? Events originating from external sync are excluded to prevent echo loops. |
| **Confidence threshold**         | Unattended writes                      | Does the event meet the destination's unattended write threshold?                                              |
| **Human approval**               | Review-gated writes                    | Did an authorized reviewer approve this specific payload and target?                                           |
| **Schema and dependency checks** | Both paths                             | Are required fields, referenced entities, and operation prerequisites valid?                                   |
| **External verification**        | Supported operations                   | Does the target acknowledge the change or show it on read-back?                                                |

On the unattended path, dependency checks can also apply confidence thresholds. For example, a patient dependency below the destination threshold is treated as failed rather than pending.

{% hint style="danger" %}
Conversation-derived data remains subject to the destination's outbound policy. Recording the patient's intent is not the same as confirming that the external system accepted a write.
{% endhint %}

### Delivery Failure Semantics

The standard automated write path reports a failed delivery but does not promise automatic reconciliation after a transient error. Human-approved proposals use a separate delivery policy: the `fhir_store` and `smart_fhir` sink types can retry their idempotent writes, while other sink types receive at most one automatic vendor call. An ambiguous non-idempotent failure is left visible for investigation or manual reconciliation rather than retried automatically.

### 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. If outbound policy selects the event and the configured destination supports patient creation, the connector validates and submits the mapped payload. The connector does not independently discover a new patient or create a record without an initiating write.

## External Write Review

External write review is a private-preview connector path available only in enabled workspaces and environments. When an eligible event targets a destination configured to require review, the connector does not send the mutation immediately. It creates an [external write proposal](/data/review-queue.md) with the target, payload, entity, and provenance. An authorized reviewer approves or rejects that proposal, and only an approved proposal enters the separate delivery path. This review step is separate from world-model confidence scoring and does not intercept every integration call or world-model event.

## Entity Resolution

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.

## Outbound Dispatch

The connector system also handles scheduled outbound interactions. When the system needs to contact a patient, each outbound task carries the patient context, interaction purpose, and priority. The platform evaluates which tasks are due and initiates interactions with the relevant patient context pre-loaded.

Outbound tasks are stored as entities in the world model. They are created by scheduling rules, follow-up workflows, or manual triggers, and their projections track status, priority, attempt count, retry timing, and call outcome.

## Gap Scanner

The gap scanner proactively identifies missing data across entities and creates [surfaces](/channels/surfaces.md) to collect it. It checks entity state against configurable requirements (for example, "patients with upcoming appointments must have insurance information") and generates data collection forms for any gaps found.

Appointment detection reads current event state directly, so appointment updates such as cancellations and rescheduling are reflected without waiting for stale data to age out.

Gap scanning is configured per workspace through the Platform API. See [Surfaces - Automated Gap Detection](/channels/surfaces.md#automated-gap-detection) for details.

## Console Views

The Developer Console gives operations teams a visual layer over the connector pipeline described above.

### Data Sources Dashboard

The Developer Console Data Sources page provides an operational overview of all external systems feeding data into a workspace. The page opens with a visual pipeline summary showing three stages: source systems (clinical and operational connectors), the normalize-and-map layer (FHIR resources, file uploads, and unification rules), and the world model output that agents and operators consume.

Summary metrics display the number of connected sources, healthy connector count, and recent sync activity. The connected sources table shows individual connector status and recent event throughput.

### Facility Location Mapping

When location, facility, or place entities are synced 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 connector system tracks operational health across data source connections. Operations teams get visibility into pipeline status without waiting for sync failures to surface.

| Metric                     | What It Tracks                                                                                                                     |
| -------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
| **Overall status**         | Whether the pipeline is healthy, degraded, or starting up                                                                          |
| **Per-source sync health** | Recent sync time, duration, event count, errors, and connection status for each data source                                        |
| **Pipeline states**        | Current state of source polling, entity resolution, and outbound processing                                                        |
| **Connection health**      | Consecutive error tracking per source - a source is marked unhealthy after repeated failures and recovers automatically on success |

### Data Source Freshness

Each data source connection reports a freshness category 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, not from how recently the connector checked the source. A source with no new data therefore reports freshness based on the last event that actually arrived. This reflects whether data is flowing, not merely whether the connector is running.

Per-source ingestion rates (events per minute, per hour, and over the last 24 hours) give operations teams a quantitative view of throughput alongside the categorical freshness indicator.

### Sensing-to-Action Latency

The platform measures the end-to-end time from when a data change is detected in a source system to when the agent acts on it. This is the latency a patient experiences between, say, a lab result being posted in the EHR and the agent calling the patient about it.

The latency distribution is presented as an hourly sparkline with count and median values, so operations teams can spot degradation trends before they affect patient experience. A spiky latency profile often indicates external system slowdowns or queue backups, while a gradually rising profile suggests growing data volume outpacing processing capacity.

The Platform API exposes pipeline observability through read-only endpoints that power the pipeline dashboard: pipeline status, source listing with live health, source event history, outbound summaries, entity resolution metrics, and throughput time series. If live connector status is temporarily unavailable, stored event and source history remain distinguishable from live health data.

{% hint style="info" %}
Pipeline health data feeds the analytics dashboard. 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.amigo.ai/developer-guide/platform-api/data-world-model/connector-runner) and [FHIR](https://docs.amigo.ai/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 dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.amigo.ai/data/connectors-and-ehr.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.