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

CapabilityStatement: SENAITE FHIR API Capability Statement (Experimental)

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

SENAITE FHIR API Capability Statement

  • Implementation Guide Version: 0.1.0
  • FHIR Version: 5.0.0
  • Supported Formats: json, xml
  • Published on: 2026-09-09
  • Published by: Naralabs

Note 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.

FHIR RESTful Capabilities

Mode: server

SENAITE 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.

Capabilities by Resource/Profile

Summary

The summary table lists the resources that are part of this configuration, and for each resource it lists:

  • The relevant profiles (if any)
  • The interactions supported by each resource (Read, Search, Update, and Create, are always shown, while VRead, Patch, Delete, History on Instance, or History on Type are only present if at least one of the resources has support for them.
  • The required, recommended, and some optional search parameters (if any).
  • The linked resources enabled for _include
  • The other resources enabled for _revinclude
  • The operations on the resource (if any)
Resource TypeProfileRSUPCSearches_include_revincludeOperations
Bundlehttp://hl7.org/fhir/StructureDefinition/Bundle
Additional supported profiles:
  Senaite Service Request Bundle
  Senaite Bundle Response
Y
ServiceRequesthttp://hl7.org/fhir/StructureDefinition/ServiceRequest
Additional supported profiles:
  SENAITE Service Request
  Senaite ServiceRequest Revoked
YYstatus, _lastUpdated$revoke
DiagnosticReporthttp://hl7.org/fhir/StructureDefinition/DiagnosticReport
Additional supported profiles:
  SenaiteDiagnosticReport
  Senaite Results Bundle
YY_lastUpdated, _summary, identifierObservation:result
Observationhttp://hl7.org/fhir/StructureDefinition/Observation
Additional supported profiles:
  SenaiteObservation
Y
Devicehttp://hl7.org/fhir/StructureDefinition/Device
Additional supported profiles:
  Senaite Device
Yidentifier
Patienthttp://hl7.org/fhir/StructureDefinition/Patient
Additional supported profiles:
  SenaitePatient
YYYidentifier
Practitionerhttp://hl7.org/fhir/StructureDefinition/Practitioner
Additional supported profiles:
  SenaitePractitioner
YYYidentifier
Specimenhttp://hl7.org/fhir/StructureDefinition/Specimen
Additional supported profiles:
  SenaiteSpecimen
YYYidentifier
Organizationhttp://hl7.org/fhir/StructureDefinition/Organization
Additional supported profiles:
  SenaiteOrganization
YYYidentifier
Taskhttp://hl7.org/fhir/StructureDefinition/Task
Additional supported profiles:
  Senaite Worksheet Task
YYYstatus, requestedperformer-reference

Base System Profile
Bundle
Profile Conformance
SHALL
Reference Policy

Interaction summary
  • SHALL support
    create

    POST a SenaiteRequestBundle transaction to submit a lab request.

Documentation

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.

Base System Profile
ServiceRequest
Profile Conformance
SHALL
Reference Policy

Interaction summary
  • SHALL support
    read

    Retrieve a ServiceRequest by the logical id returned in the transaction response.

    search-type

    Search ServiceRequests. Used by instrument middleware to fetch and incrementally refresh the worklist.

Documentation

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; optional requisition. SenaiteServiceRequest constrains identifier to 0..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 carry requisition (0..1), the Sample Group ID: its system is fixed to https://fhir.senaite.org/NamingSystem/sample-group-id and its value is a consumer-owned label shared by the ServiceRequests of one multi-tube order, unique within the consumer. No search by requisition is 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 code element identifies the ordered panel. The orderDetail element 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).
  • orderDetail is a superset: All panel tests plus additional tests are included — the sample is created for the full panel plus the extras.
  • orderDetail is a proper subset: One or more panel tests are absent. The server rejects the request with 400 Bad Request and an OperationOutcome listing the missing test codes.

$revoke response codes: Returns 200 OK on success, 409 Conflict if results are published, 404 if not found, 422 if the current status does not permit revocation.

Search Parameters
ConformanceParameterTypeDocumentation
SHALLstatustoken

Filter by status e.g. status=active. Used by instrument middleware to fetch the worklist.

SHALL_lastUpdateddate

Filter by last updated date. Used by instrument middleware to retrieve only new or changed requests since the last poll.

 
Extended Operations
ConformanceOperationDocumentation
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.

Base System Profile
DiagnosticReport
Profile Conformance
SHALL
Reference Policy

Interaction summary
  • SHALL support
    read

    Retrieve 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-type

    Poll 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.

Documentation

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=true parameter 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 complete presentedForm.data attachment.

Per-sample and combined reports. A per-sample report is a projection of one Sample and has at most one basedOn ServiceRequest. A combined report is published by the laboratory for the Samples with a common ServiceRequest.requisition: it lists every ServiceRequest it covers in basedOn (more than one — this is the marker), carries the single combined PDF in presentedForm, 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 in specimen (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 through basedOn, so a combined report's result list 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 marked entered-in-error.

Search Parameters
ConformanceParameterTypeDocumentation
SHALL_lastUpdateddate

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_summarytoken

_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.

SHOULDidentifiertoken

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.

 
Base System Profile
Observation
Profile Conformance
SHALL
Reference Policy

Supported Profiles

SenaiteObservation

Interaction summary
  • SHALL support
    create

    POST a single SenaiteObservation. Used by instrument middleware to push individual analyte results as they arrive from the instrument.

Documentation

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.

Base System Profile
Device
Profile Conformance
SHALL
Reference Policy

Supported Profiles

Senaite Device

Interaction summary
  • SHALL support
    search-type

    GET /Device?identifier=<asset_number> to confirm device registration.

Documentation

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.

Search Parameters
ConformanceParameterTypeDocumentation
SHALLidentifiertoken

Search by asset register identifier. Used by instrument middleware at startup to confirm device registration.

 
Base System Profile
Patient
Profile Conformance
SHALL
Reference Policy

Supported Profiles

SenaitePatient

Interaction summary
  • SHALL support
    create

    Created as an entry within a SenaiteRequestBundle transaction. Standalone POST is not part of this IG.

    read

    Retrieve a Patient by the logical id returned in a transaction response.

    search-type

    Search by identifier. Required so the server can evaluate request.ifNoneExist on Patient Bundle entries.

Documentation

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.

Search Parameters
ConformanceParameterTypeDocumentation
SHALLidentifiertoken

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.

 
Base System Profile
Practitioner
Profile Conformance
SHALL
Reference Policy

Supported Profiles

SenaitePractitioner

Interaction summary
  • SHALL support
    create

    Created as an entry within a SenaiteRequestBundle transaction. Standalone POST is not part of this IG.

    read

    Retrieve a Practitioner by the logical id returned in a transaction response.

    search-type

    Search by identifier. Required so the server can evaluate request.ifNoneExist on Practitioner Bundle entries.

Documentation

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.

Search Parameters
ConformanceParameterTypeDocumentation
SHALLidentifiertoken

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.

 
Base System Profile
Specimen
Profile Conformance
SHALL
Reference Policy

Supported Profiles

SenaiteSpecimen

Interaction summary
  • SHALL support
    create

    Created as an entry within a SenaiteRequestBundle transaction. Standalone POST is not part of this IG.

    read

    Retrieve a Specimen by the logical id returned in a transaction response.

  • SHOULD support
    search-type

    Search by identifier, so the internal Sample ID can be used to identify a Specimen on read.

Documentation

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.

Search Parameters
ConformanceParameterTypeDocumentation
SHOULDidentifiertoken

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.

 
Base System Profile
Organization
Profile Conformance
SHALL
Reference Policy

Supported Profiles

SenaiteOrganization

Interaction summary
  • SHALL support
    create

    Created as an entry within a SenaiteRequestBundle transaction. Standalone POST is not part of this IG.

    read

    Retrieve an Organization by logical id. Required so a consumer can dereference and reuse the Client id returned in a transaction response.

    search-type

    Search by identifier. Required so the server can evaluate request.ifNoneExist on Organization Bundle entries.

Documentation

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.

Search Parameters
ConformanceParameterTypeDocumentation
SHALLidentifiertoken

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.

 
Base System Profile
Task
Profile Conformance
SHALL
Reference Policy

Supported Profiles

Senaite Worksheet Task

Interaction summary
  • SHALL support
    read

    Retrieve a specific worksheet Task by id. The response carries an ETag; clients supply it as If-Match on the subsequent patch.

    patch

    The 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.

  • SHOULD support
    search-type

    Poll 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).

Documentation

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.

Search Parameters
ConformanceParameterTypeDocumentation
SHOULDstatustoken

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.

SHOULDrequestedperformer-referencereference

The standard Task search parameter targeting the reference component of requestedPerformer. Filter by the instrument (Device) the worksheet is scoped to.