A FHIR API integration exchanges healthcare information through agreed resources, profiles and supported interactions, with a separate authorization and privacy design. Begin with the clinical workflow and the server’s actual capabilities. Using JSON with a resourceType field does not by itself establish interoperability or safe access.

Key takeaways

• Agree the FHIR release and implementation guide before mapping data.
• Inspect the server’s CapabilityStatement and supported operations.
• Use the appropriate SMART/OAuth pattern and least-privileged access.
• Validate patient context, identifiers, terminology and provenance.
• Keep clinical interpretation and release acceptance with qualified owners.

Resources are a shared model, not a complete agreement

Common resource types include Patient, Encounter and Observation. The integration still needs an agreed release, profiles, terminology and supported workflows. A resource from one implementation cannot be assumed interchangeable with every other system merely because both call it FHIR.

The FHIR R4 RESTful API specification defines resource interactions and requires servers to describe supported resources and interactions. This article uses R4 references for a concrete discussion; implement against the release and implementation guide agreed with the actual partner.

The CapabilityStatement specification explains how capabilities describe a server’s behavior. Review that contract along with the partner’s implementation documentation and a test environment. Do not assume every resource supports create, update, search and history.

For a fictional referral workspace, define whether the application displays existing information, submits a referral or updates a clinical record. Those actions require different validation, authority and recovery. Start with a narrow read-only pilot where appropriate.

A standards-first integration architecture

Approved user or workload + defined workflow purpose
                      ↓
Authentication and authorized resource context
                      ↓
Integration boundary
  ├─ capability/profile validation
  ├─ identifier and terminology mapping
  ├─ request/response handling and reconciliation
  └─ privacy-aware audit and provenance
                      ↓
Partner FHIR endpoint → validated information → intended application view

Clinical decision or record change → separate authorized review/action path

This is an architecture model, not a deployed clinical-system diagram. Assign ownership for each mapping and exception. The transport can succeed while the information has the wrong patient context or meaning.

Separate source-of-truth ownership from application display. If the workspace caches a view, record how freshness and corrections are handled. Do not let a stale copy silently become the authoritative clinical record.

For writes, define the supported operation, concurrency behavior and reconciliation process. A timeout can leave the outcome uncertain. Do not blindly repeat a clinical-record operation without understanding the partner’s supported semantics.

SMART App Launch and OAuth

SMART App Launch 2.2 guidance describes discovery, authorization-code flows and launch context for supported user-facing applications. Follow the agreed implementation version and registered client configuration. Distinguish an EHR-launched user application from a backend service; they are not the same authorization flow.

Negotiate the minimum needed resource access and validate the granted context. A token is not a business-level guarantee that any patient identifier supplied by the browser may be accessed. Enforce the approved resource and workflow boundary at the trusted integration layer.

Keep credentials, access tokens and patient content out of routine diagnostic logs. Use supported libraries and token-validation mechanisms, and test expiration, revocation and denied access with the partner environment.

HL7’s FHIR security guidance explicitly separates FHIR’s exchange model from the security protocols and operational controls around it. FHIR support alone does not establish privacy compliance, institutional authorization or safe clinical use.

A synthetic read example

The following request uses a reserved example host and a synthetic identifier. It was not sent to an EHR. The exact search parameters and permissions must be supported by the target server.

GET https://ehr.example.invalid/fhir/Observation?patient=example-patient&_count=20
Authorization: Bearer <authorized-access-token>
Accept: application/fhir+json

Treat a search result as a result set with the server’s supported paging behavior. Do not assume the first page represents all available information or that a requested count guarantees a particular page size.

A synthetic Patient resource for structural discussion might begin as follows:

{
  "resourceType": "Patient",
  "id": "example-patient",
  "active": true
}

This minimal illustration is not a complete resource for a particular implementation guide and contains no real patient data. Validate resources against the actual profiles and partner rules before relying on them.

Do not infer clinical meaning from the presence of a resource alone. Status, effective time, coding, units and provenance can change how information should be interpreted. Qualified domain owners must approve the application’s presentation and intended use.

Privacy boundaries and operational evidence

Document the intended audience and purpose for each data flow. Keep the application from requesting broader data merely because the endpoint makes it easy. Review caches, exports, support tooling and analytics as additional disclosure paths.

Use synthetic or appropriately governed test information. A development troubleshooting ticket should not become an uncontrolled copy of patient records. Redact or minimize diagnostic evidence while retaining correlation and error details needed for support.

Record source identifiers, resource versions where relevant, transformation decisions and processing outcomes. Separate access auditing from clinical provenance: who viewed a resource and who authored or transformed information are related but different questions.

Define retention, deletion and correction processes with the responsible organizational specialists. This technical guide does not determine legal obligations or certify a deployment.

If an AI feature is later added, create a separate approved data and evaluation boundary. A working FHIR integration does not automatically authorize sending clinical information to an external model or taking clinical action from generated text.

Implementation and acceptance checklist

1. Define the workflow, actors and source-of-truth ownership.
2. Agree FHIR release, implementation guide and supported capabilities.
3. Map identifiers, profiles, terminology and references.
4. Approve the authentication flow and minimum resource access.
5. Validate patient context and denied-access scenarios.
6. Test paging, missing fields, unsupported codes and stale information.
7. Exercise timeouts, duplicate requests and uncertain write outcomes.
8. Inspect logs, caches and exports for inappropriate disclosure.
9. Obtain domain-owner acceptance of information presentation.
10. Rehearse deployment, monitoring, support and recovery.

These are proposed acceptance tests, not reported EHR test results. Use the partner’s test environment and representative governed fixtures before deployment.

See the enterprise authentication guide for protocol distinctions and the idempotency guide for uncertain-operation recovery concepts.

Common questions

Plan healthcare integration around meaning and access

Bring the partner contract, workflow and privacy boundaries. Discuss a domain-specific AI solution grounded in a reviewed integration architecture.