FHIR API Integration: How It Works End to End

Integrating with a FHIR API follows a predictable sequence regardless of whether the server is an EHR, a payer platform or your own FHIR server:

1. Discover the server's capabilities and security endpoints.
2. Register your client and obtain credentials.
3. Request an access token.
4. Read and search resources, following references and pages.
5. Write data back, if the use case and server allow it.
6. Handle errors, throttling and retries.
7. Test against sandboxes, validators and, finally, production.

The examples below use FHIR R4 and a placeholder base URL of https://fhir.example.org/r4. If FHIR concepts such as resources and Bundles are new to you, read What is FHIR? first.

Every conformant FHIR server publishes a CapabilityStatement at [base]/metadata. It lists the FHIR version, supported resource types, interactions (read, search-type, create, update), search parameters, operations and the profiles the server claims to support. Read it before you write code; it is the closest thing to an authoritative contract.

GET /r4/metadata HTTP/1.1
Host: fhir.example.org
Accept: application/fhir+json

For servers that implement SMART, also fetch [base]/.well-known/smart-configuration. It returns the authorization and token endpoints, supported scopes and the client authentication methods the server accepts. Note that a CapabilityStatement says what the software can do; the scopes granted to your client and the server's data may still limit what you actually receive.

FHIR itself does not define security, but the SMART App Launch implementation guide is the standard approach. Choose the flow by who is using the integration:

• SMART App Launch (authorization code) for apps used by a patient or clinician, launched standalone or from inside the EHR. See the SMART on FHIR guide.
• SMART Backend Services for system-to-system integrations with no user present, such as nightly syncs, analytics pipelines or Bulk Data export.

With Backend Services, you register a public key (usually as a JWK Set URL) with the server operator. To get a token, your service signs a short-lived JWT with its private key (RS384 or ES384) and posts it to the token endpoint using the OAuth 2.0 client credentials grant:

POST /oauth2/token HTTP/1.1
Host: auth.example.org
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials
&scope=system/Patient.rs system/Observation.rs
&client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer
&client_assertion=eyJhbGciOiJSUzM4NCIsImtpZCI6IjEifQ...

The response contains an access_token and expires_in. Cache the token, reuse it until shortly before expiry, then request a new one. SMART v2 scopes use the .rs (read and search) style shown above; older servers may only accept v1 scopes such as system/Patient.read. Our FHIR security guide covers key management and scope design.

Most integration traffic is search. Search parameters are defined per resource type, and servers support different subsets, so check the CapabilityStatement. Useful patterns include token searches (code=http://loinc.org|4548-4), date prefixes (date=ge2026-01-01), reference chaining (subject:Patient.identifier=...) and result-control parameters such as _count, _sort, _lastUpdated, _elements and _summary.

Use _include and _revinclude to pull related resources in a single round trip. For example, fetching a patient's active medication requests together with the referenced Medication resources:

GET /r4/MedicationRequest?patient=004512&status=active&_include=MedicationRequest:medication&_count=50 HTTP/1.1
Host: fhir.example.org
Accept: application/fhir+json
Authorization: Bearer eyJhbGciOi...

{
  "resourceType": "Bundle",
  "type": "searchset",
  "link": [
    { "relation": "self", "url": "https://fhir.example.org/r4/MedicationRequest?patient=004512&status=active&_include=MedicationRequest:medication&_count=50" },
    { "relation": "next", "url": "https://fhir.example.org/r4?_getpages=8c1f2e&_getpagesoffset=50&_count=50" }
  ],
  "entry": [
    {
      "fullUrl": "https://fhir.example.org/r4/MedicationRequest/mr-1",
      "resource": { "resourceType": "MedicationRequest", "id": "mr-1", "status": "active", "intent": "order", "medicationReference": { "reference": "Medication/med-9" }, "subject": { "reference": "Patient/004512" } },
      "search": { "mode": "match" }
    },
    {
      "fullUrl": "https://fhir.example.org/r4/Medication/med-9",
      "resource": { "resourceType": "Medication", "id": "med-9" },
      "search": { "mode": "include" }
    }
  ]
}

Note search.mode: "match" entries satisfy your query, "include" entries came along because of _include. When a next link is present, follow it exactly as given; page URLs are opaque and server-specific. Bundle.total is optional and often omitted for performance, so do not rely on it to know when you are done. For very large datasets, switch to the Bulk Data $export operation instead of paging through millions of results.

Write access is where EHR integrations differ most. Many EHR FHIR APIs are read-heavy, with write support limited to specific resources and workflows, so confirm write capabilities early. Good practice when writing:

• Validate resources against the target profiles before sending.
• Use conditional create (If-None-Exist header) to avoid duplicates when retrying.
• Use ETags with If-Match on updates to prevent overwriting someone else's change; the server returns 412 Precondition Failed on a version conflict.
• Use a transaction Bundle when several resources must be created together or not at all.

FHIR servers report problems with an HTTP status code and, usually, an OperationOutcome resource describing each issue with a severity, a code and human-readable diagnostics:

HTTP/1.1 422 Unprocessable Entity
Content-Type: application/fhir+json

{
  "resourceType": "OperationOutcome",
  "issue": [
    {
      "severity": "error",
      "code": "required",
      "diagnostics": "Observation.status: minimum required = 1, but only found 0",
      "expression": ["Observation.status"]
    }
  ]
}

Rate limits are set by each server operator, not by the FHIR specification, and EHR vendors document their own policies. Build a client-side throttle, prefer fewer and richer queries (with _include and _elements) over many small ones, and schedule heavy jobs off-peak.

A sound test plan uses several layers:

• Public sandboxes and reference servers, such as a local HAPI FHIR instance, for early development.
• Vendor sandboxes for the specific EHRs you target, since behavior differs; see the Epic and Oracle Health integration pages.
• The HL7 FHIR Validator to check resources against profiles, and Inferno to exercise US Core and SMART behavior.
• Production-like data volumes to surface paging, timeout and throttling issues before go-live.

If you would rather hand this work to specialists, the FHIR API development service page explains what to expect, and the FHIR API development companies directory lists firms that offer it.