FHIR integration

FHIR R4 endpoints, authentication, supported resources, operations, search parameters, and request examples.

Xenrad exposes a FHIR R4 JSON API for site-scoped clinical data. Authentication uses a site-scoped Xenrad API key in the X-API-Key header. There is no separate FHIR user; the key is bound to a site and resolves to its owning user.

Standards

FHIR version: R4 (normative 4.0.1 in the capability statement)
Format: application/fhir+json (JSON). This guide uses that format in examples.
Auth: X-API-Key header with an active site-scoped Xenrad API key.

Before you start

Create an API key for the site in the Xenrad app.
Store the revealed key securely; it is shown once.
Send it as X-API-Key on FHIR requests.

Base URL — https://fhir.integrations.xenrad-staging-app.xyz/fhir (for example https://fhir.integrations.xenrad-staging-app.xyz/fhir/Patient). Capability metadata: GET https://fhir.integrations.xenrad-staging-app.xyz/fhir/metadata.

Step 1 — Verify capability metadata

Capability statement: GET /fhir/metadata on the FHIR host. Confirms the server supports the listed resource types and interactions.
Interactive reference: open /api/documentation on the same FHIR host when enabled for your environment.

DELETE is not supported for the clinical resources listed below.

Step 2 — Call FHIR

Send:

X-API-Key: <api_key>
Accept: application/fhir+json
Content-Type: application/fhir+json   # for POST/PUT

URL patterns

Operation	Method	Path
Search	`GET`	`/fhir/{ResourceType}?{search}`
Read	`GET`	`/fhir/{ResourceType}/{id}`
Create	`POST`	`/fhir/{ResourceType}`
Update	`PUT`	`/fhir/{ResourceType}/{id}`

The server resolves the API key to a site and executes the request inside that site boundary.

Supported resources and typical use

Resource	Use cases
Patient	Master demographics, identifiers, contact points.
Condition	Problem list, clinical status, coded conditions.
AllergyIntolerance	Allergies, clinical and verification status.
Observation	Lab or clinical observations coded or textual.
Procedure	Documented procedures.
DiagnosticReport	Read structured radiology or clinical reports (backed by internal `reports`).
DocumentReference	Document metadata (and content pointers your mapping supports).

Search parameters (implemented)

The server’s search support is intentionally lean; it covers common filters. Parameters below are the ones the implementation recognizes.

Patient — `GET /fhir/Patient?…`

Parameter	Matches
`identifier`	Internal business identifier (maps to the patient’s identifier field for the site).
`name`	Case-insensitive substring of patient name.
`birthdate`	Date of birth (exact match to stored value for the field).
`gender`	Administrative gender.

If no query parameters are present, the search returns all patients in the site attached to the API key.

Condition — `GET /fhir/Condition?…`

Parameter	Notes
`patient`	Reference, for example `Patient/{uuid}`. The id is the Xenrad id.
`clinical-status`	Filter by stored clinical status text/code path your deployment uses.
`code`	Filter on coded `code` field.

AllergyIntolerance — `GET /fhir/AllergyIntolerance?…`

Same style as conditions: patient, clinical-status, code.

Observation / Procedure

Parameter	Notes
`patient`	`Patient/{id}`
`code`	Coded field filter

DocumentReference

Parameter	Notes
`patient`	`Patient/{id}`
`type`	Document type code (`doc_type_code` path internally).

DiagnosticReport

Parameter	Notes
`patient`	Resolves to reports whose study belongs to the patient.
`status`	Use `final` to map to completed reports, other values to draft.

Bundle search responses are JSON FHIR Bundle resources with type: searchset.

Create and update semantics

POST — creates a new resource; the server assigns an id in Xenrad.
PUT — id in path must match an existing id for the site, or the server will treat according to its implementation of upsert (for patients, a body without id creates when permitted).

Patient JSON mapping highlights for writes:

name[0].text for display name
identifier[0].value for the business identifier
telecom for phone/email by system
address[0] for text, state, country, postalCode
gender, birthDate ISO

Other resources expect references like Patient/{id} in subject / patient fields consistent with your payload examples; follow validation errors the API returns in OperationOutcome.

Create or select a site API key.
GET {your FHIR host}/fhir/Patient?name=smith with X-API-Key: … (see Endpoints reference).

HL7 — v2 events that may feed the same patient data.
MPPS — procedure-step session ingest.
Endpoints reference — which host to call in each environment.
API keys — creating and revoking keys.