0.1.0 - ci-build
SENAITEFHIRImplementationGuide - Local Development build (v0.1.0) built by the FHIR (HL7® FHIR® Standard) Build Tools. See the Directory of published versions
| Official URL: https://fhir.senaite.org/CapabilityStatement/SenaiteCapabilityStatement | Version: 0.1.0 | |||
| Draft as of 2026-09-09 | Computable Name: SenaiteCapabilityStatement | |||
FHIR R5 capability statement for the SENAITE LIMS FHIR API. SENAITE acts as the API server. External consumers and instrument middleware interact with this API to submit lab requests, revoke requests, push instrument results, and retrieve diagnostic reports.
Raw OpenAPI-Swagger Definition file | Download
json, xmlNote to Implementers: FHIR Capabilities
Any FHIR capability may be 'allowed' by the system unless explicitly marked as 'SHALL NOT'. A few items are marked as MAY in the Implementation Guide to highlight their potential relevance to the use case.
serverSENAITE exposes a FHIR R5 RESTful API supporting the Lab Request and Results workflow and the Instrument Integration workflow.
Transaction processing. Lab requests are submitted as a transaction Bundle conforming to SenaiteRequestBundle. Entry fullUrl values are urn:uuid placeholders used only to resolve references between entries in the same Bundle; they have no persistence. Resource.id SHALL be absent on POST entries — the server assigns every logical id. The response is a SenaiteBundleResponse containing one entry per request entry, in the same order; that positional correspondence is how a consumer reconciles the placeholders it sent with the ids the server assigned. A failed transaction returns no response Bundle — the server returns an HTTP 4xx or 5xx with a single OperationOutcome and creates nothing.
Conditional create. Patient, Practitioner and Organization entries may carry request.ifNoneExist, so that a repeat submission matches the existing resource (200 OK) rather than creating a duplicate (201 Created). The key takes the form identifier=\<system>|\<value> and the system is mandatory, because the identifier search parameter matches on system and value and ignores Identifier.use. Either identifier may be used: the consumer's own external ID (use = secondary), or the internal SENAITE ID (use = usual) returned by an earlier order. Using the internal ID as a match key is permitted; supplying it in the resource body is not. Multiple matches fail the whole transaction. Conditional create is a trial-use part of the FHIR specification. Resources that carry no identifier cannot be matched this way; create them once and thereafter reference them by logical id.
Multi-sample orders. A SenaiteRequestBundle carries exactly one ServiceRequest and one Specimen. An order spanning several sample types (tubes) is submitted as one transaction per tube, each ServiceRequest carrying the same requisition. Its system is fixed by this IG to the Sample Group ID namespace (https://fhir.senaite.org/NamingSystem/sample-group-id); the consumer chooses the value, which must be unique within the consumer. Consumers SHOULD submit these sequentially — the first transaction creates any Patient, Practitioner and Organization (with request.ifNoneExist) and later transactions reference the logical ids returned — because conditional create is not safe against concurrent creates. Every request sharing a requisition must be for the same Patient and the same Client: a Bundle whose Patient or Client differs from those already recorded for that value is rejected with 422 Unprocessable Entity and an OperationOutcome, and nothing is created. Transactions are atomic individually, not across tubes.
Prefer header. SenaiteBundleResponse does not honour Prefer: return=representation; the Specimen resource body described below is returned unconditionally, and no other entry ever carries one. Consumers read the assigned id for the other resources from entry.fullUrl or entry.response.location and perform a read if their body is needed.
Specimen resource body. Unlike every other entry, the Specimen entry in SenaiteBundleResponse always carries the full created SenaiteSpecimen in entry.resource. This is the only place the SENAITE-assigned internal Sample ID is available without a follow-up read, and lets the consumer confirm any Client Sample ID it supplied was preserved.
Versioning. Most resources are served with no-version: meta.versionId is not maintained, Location headers and Bundle.entry.response.location carry [base]/[type]/[id] with no /_history/[vid] suffix, and no ETag is returned. Task is the exception — see below. No vread or history interactions are offered on any resource.
The summary table lists the resources that are part of this configuration, and for each resource it lists:
_include_revincludecreatePOST a SenaiteRequestBundle transaction to submit a lab request.
POST a SenaiteRequestBundle (transaction) to submit a lab request. Returns a SenaiteBundleResponse on success or a single OperationOutcome on failure. Transactions are atomic: if any entry fails, nothing is created.
readRetrieve a ServiceRequest by the logical id returned in the transaction response.
search-typeSearch ServiceRequests. Used by instrument middleware to fetch and incrementally refresh the worklist.
ServiceRequests are created via a SenaiteRequestBundle transaction and revoked via the $revoke operation.
SENAITE holds no stored ServiceRequest object; a ServiceRequest is a projection over the AnalysisRequest created from the Bundle. The logical id returned in the transaction response is nonetheless stable and resolvable via the read interaction, and is the id supplied to $revoke.
No
identifier; optionalrequisition. SenaiteServiceRequest constrainsidentifierto0..0, so there is no identifier search on ServiceRequest. Sample identity is carried on Specimen and DiagnosticReport; a consumer supplying its own reference for one sample puts it on the Specimen entry as the Client Sample ID. A ServiceRequest may carryrequisition(0..1), the Sample Group ID: its system is fixed tohttps://fhir.senaite.org/NamingSystem/sample-group-idand its value is a consumer-owned label shared by the ServiceRequests of one multi-tube order, unique within the consumer. No search byrequisitionis offered on ServiceRequest: the combined report for an order is found by searching DiagnosticReport on the same value as an identifier. The server does not enforce that it is unique per sample.Panel and orderDetail rules: The
codeelement identifies the ordered panel. TheorderDetailelement enumerates individual test codes and follows these rules:
- Empty
orderDetail: The server creates the sample for all tests in the panel (defers to the panel definition).orderDetailis a superset: All panel tests plus additional tests are included — the sample is created for the full panel plus the extras.orderDetailis a proper subset: One or more panel tests are absent. The server rejects the request with400 Bad Requestand anOperationOutcomelisting the missing test codes.$revoke response codes: Returns
200 OKon success,409 Conflictif results are published,404if not found,422if the current status does not permit revocation.
| Conformance | Parameter | Type | Documentation |
|---|---|---|---|
| SHALL | status | token | Filter by status e.g. status=active. Used by instrument middleware to fetch the worklist. |
| SHALL | _lastUpdated | date | Filter by last updated date. Used by instrument middleware to retrieve only new or changed requests since the last poll. |
| Conformance | Operation | Documentation |
|---|---|---|
| SHALL | $revoke | Revoke a ServiceRequest. POST /ServiceRequest/{id}/$revoke with an optional Parameters body containing a reason string. Only valid for ServiceRequests in active or on-hold status. |
readRetrieve a specific DiagnosticReport by id. Returns the full resource including the base64-encoded PDF in presentedForm.data. Do not use _summary on this request.
search-typePoll for new or updated DiagnosticReports. Requires _summary=true and _lastUpdated. A single response may contain multiple DiagnosticReports if more than one Sample was completed since the last poll, and may contain both per-sample and combined reports. Use _include=Observation:result to retrieve associated Observations in the same request.
DiagnosticReports are created internally by SENAITE after results are verified and are not directly writable by external consumers.
Polling pattern: Consumers poll for new or updated reports using a GET search with
_lastUpdated,_summary=true, and_include=Observation:result. The_summary=trueparameter is required on all search requests for performance reasons —presentedForm.data(the base64 PDF payload) is excluded from summary responses.PDF retrieval: After discovering a new report via polling, consumers retrieve the full PDF by performing a direct read:
GET DiagnosticReport/{id}(without_summary). The response will include the completepresentedForm.dataattachment.Per-sample and combined reports. A per-sample report is a projection of one Sample and has at most one
basedOnServiceRequest. A combined report is published by the laboratory for the Samples with a commonServiceRequest.requisition: it lists every ServiceRequest it covers inbasedOn(more than one — this is the marker), carries the single combined PDF inpresentedForm, carries one Sample ID for each Sample it covers, a Client Sample ID for each Sample that has one, and the Sample Group ID (the requisition value) as identifiers. These lists are unordered and carry no pairing: do not infer which Client Sample ID belongs to which Sample ID from list position. The report also references the Specimen of each Sample it covers inspecimen(one on a per-sample report, one per covered Sample on a combined report); each Specimen carries its own Sample ID and Client Sample ID, so read the Specimens, or use the per-sample report, to pair them. A per-sample report carries no Sample Group ID. The two kinds coexist; a search by Sample ID returns that Sample's per-sample report and any combined report covering it. Consumers should ingest per-sample reports as the results and treat a combined report as a document. Observations always identify their own ServiceRequest throughbasedOn, so a combined report'sresultlist can be split by sample. A combined report is created only when every covered Sample is final; its membership is fixed at publication, and a correction or late tube is delivered as a new combined report with the superseded one markedentered-in-error.
| Conformance | Parameter | Type | Documentation |
|---|---|---|---|
| SHALL | _lastUpdated | date | Filter reports updated since a given datetime. Consumers should store the timestamp of the last successful fetch and pass it as the value on each subsequent poll, e.g. _lastUpdated=gt2026-01-01T00:00:00Z. |
| SHALL | _summary | token | _summary=true is required on all DiagnosticReport search requests. This excludes presentedForm.data (the PDF payload) from the response, keeping polling lightweight. To retrieve the PDF, perform a direct read by id. |
| SHOULD | identifier | token | Search by Sample ID (identifier=https://fhir.senaite.org/NamingSystem/sample-id|SAMP-SENAITE-001) or Client Sample ID to find the per-sample report (a search by either also returns any combined report covering that Sample), or by Sample Group ID (identifier=https://fhir.senaite.org/NamingSystem/sample-group-id|<value>) to find the combined report(s) for an order. A combined report carries one Sample ID, and a Client Sample ID where there is one, per covered Sample; a per-sample report carries no Sample Group ID. System and value are both required. |
createPOST a single SenaiteObservation. Used by instrument middleware to push individual analyte results as they arrive from the instrument.
POSTed individually by instrument middleware as results arrive from the instrument. Each Observation references the originating ServiceRequest via basedOn and the instrument via device. Also returned via _include in DiagnosticReport searches.
search-typeGET /Device?identifier=<asset_number> to confirm device registration.
Device records are created manually in SENAITE by a lab administrator. The instrument middleware performs a one-time GET at startup to confirm registration and retrieve the logical Device id.
| Conformance | Parameter | Type | Documentation |
|---|---|---|---|
| SHALL | identifier | token | Search by asset register identifier. Used by instrument middleware at startup to confirm device registration. |
createCreated as an entry within a SenaiteRequestBundle transaction. Standalone POST is not part of this IG.
readRetrieve a Patient by the logical id returned in a transaction response.
search-typeSearch by identifier. Required so the server can evaluate request.ifNoneExist on Patient Bundle entries.
Created as part of a SenaiteRequestBundle transaction, optionally with request.ifNoneExist so a repeat submission matches an existing Patient. Read is supported so the logical id returned in the transaction response is dereferenceable, and so a consumer that has stored the id can reference the Patient in a later Bundle without resubmitting demographics. Note that a conditional-create match discards the submitted body: demographic changes are not applied to an already-matched Patient.
| Conformance | Parameter | Type | Documentation |
|---|---|---|---|
| SHALL | identifier | token | Search by patient identifier, e.g. identifier=https://ehr.example.org/mrn|MRN-20394857 for the consumer's external ID, or identifier=https://fhir.senaite.org/NamingSystem/patient-id|PAT-001 for the internal SENAITE ID. Backs conditional create. The system is mandatory: this parameter matches on system and value regardless of Identifier.use, so the system URI is the only thing scoping a query to the consumer's own external namespace rather than SENAITE's internal one. External namespaces are agreed per-integration and default to https://fhir.senaite.org/NamingSystem/patient-mrn. |
createCreated as an entry within a SenaiteRequestBundle transaction. Standalone POST is not part of this IG.
readRetrieve a Practitioner by the logical id returned in a transaction response.
search-typeSearch by identifier. Required so the server can evaluate request.ifNoneExist on Practitioner Bundle entries.
Created as part of a SenaiteRequestBundle transaction, optionally with request.ifNoneExist so a repeat submission matches an existing Practitioner. Read is supported so the logical id returned in the transaction response is dereferenceable and reusable in later Bundles.
| Conformance | Parameter | Type | Documentation |
|---|---|---|---|
| SHALL | identifier | token | Search by practitioner identifier, e.g. identifier=https://ehr.example.org/practitioner|PRACT-DR-SULLIVAN for the consumer's external ID, or the internal SENAITE ID namespace for the server-assigned one. Backs conditional create. The system is mandatory. External namespaces are agreed per-integration and default to https://fhir.senaite.org/NamingSystem/practitioner-external-id. |
createCreated as an entry within a SenaiteRequestBundle transaction. Standalone POST is not part of this IG.
readRetrieve a Specimen by the logical id returned in a transaction response.
search-typeSearch by identifier, so the internal Sample ID can be used to identify a Specimen on read.
Created as part of a SenaiteRequestBundle transaction. Always created, never matched — request.ifNoneExist is not permitted on Specimen entries, since a specimen is never reused. Read is supported so the logical id returned in the transaction response is dereferenceable. Search by identifier is offered so that the internal Sample ID, and the Client Sample ID where one was supplied, can be used to locate a Specimen after creation.
| Conformance | Parameter | Type | Documentation |
|---|---|---|---|
| SHOULD | identifier | token | Search by the internal Sample ID, e.g. identifier=https://fhir.senaite.org/NamingSystem/sample-id|SAMP-SENAITE-001, or by the Client Sample ID where one was supplied. Both Specimen namespaces are fixed by this IG. Not used for conditional create — Specimen entries never carry request.ifNoneExist. |
createCreated as an entry within a SenaiteRequestBundle transaction. Standalone POST is not part of this IG.
readRetrieve an Organization by logical id. Required so a consumer can dereference and reuse the Client id returned in a transaction response.
search-typeSearch by identifier. Required so the server can evaluate request.ifNoneExist on Organization Bundle entries.
Represents the Client Organisation submitting the lab request. Every SenaiteRequestBundle must identify its Client via the SenaiteClient extension on the ServiceRequest, but the Organization entry itself is optional: include it when the Client may not yet exist, or omit it and reference the Client by logical id.
Organizations without an external identifier cannot be matched by request.ifNoneExist. Create such an Organization once, store the logical id from the transaction response, and reference it thereafter.
Deployments that manage Clients administratively — where a Client carries contract or pricing configuration — should provision Organizations in SENAITE directly and supply integrators with the logical id out of band, rather than allowing consumers to auto-provision their own Client on first order.
| Conformance | Parameter | Type | Documentation |
|---|---|---|---|
| SHALL | identifier | token | Search by organization identifier, e.g. identifier=https://ehr.example.org/org|ORG-RMH-MEL for the consumer's external ID, or the internal SENAITE ID namespace for the server-assigned Client ID. Backs conditional create. The system is mandatory. External namespaces are agreed per-integration and default to https://fhir.senaite.org/NamingSystem/organization-external-id. |
readRetrieve a specific worksheet Task by id. The response carries an ETag; clients supply it as If-Match on the subsequent patch.
patchThe owning instrument/middleware transitions status from ready to in-progress via PATCH once it begins acting on the worksheet. This is the only write this profile supports — no update (PUT) interaction is offered. Clients SHALL supply an If-Match header with the currently-known ETag/versionId; the server SHALL reject with 412 Precondition Failed if the Task has changed since the client's last read, and SHALL reject any transition other than ready -> in-progress with 409 Conflict.
search-typePoll for worksheets by status, e.g. status=ready&requestedperformer-reference=Device/{id} to find worksheets that have been locked into their ready state and are waiting to be claimed, or status=draft&requestedperformer-reference=Device/{id} to see worksheets still being assembled for that instrument (informational only — not yet actionable, since composition can still change).
Represents a SENAITE worksheet scoped to a single instrument. Created and, for the most part, transitioned internally by SENAITE — exposed read-only for those transitions. The exception is the transition to in-progress (from either ready or draft), which the owning instrument/middleware writes itself via patch once it begins acting on the worksheet — locking the worksheet in SENAITE as a side effect if it wasn't already locked. Complements, rather than replaces, the standard instrument worklist poll — not all instrument work arrives via a worksheet. Consumers fetch the referenced SenaiteInstrumentServiceRequest resources in Task.input directly rather than via reverse search.
| Conformance | Parameter | Type | Documentation |
|---|---|---|---|
| SHOULD | status | token | Filter by status, e.g. status=ready to find worksheets that have been locked and are safe to claim and act on, status=draft to see worksheets still being assembled (also actionable — see the patch interaction above), or the comma-separated status=ready,draft to retrieve both in one poll. |
| SHOULD | requestedperformer-reference | reference | The standard Task search parameter targeting the reference component of requestedPerformer. Filter by the instrument (Device) the worksheet is scoped to. |