Transactional API

Workflow

The Workflow section of the Transactional API covers operational processes that go beyond a simple read or write: multi-step actions a clinical system carries out on a patient's behalf over the course of an integration.

All Workflow endpoints share the same authentication and error model as the rest of the Transactional API.

Investigation report filing

Four endpoints support the investigation report filing workflow:

Endpoint	Method	Purpose
List Unfiled Investigation Reports	GET	Returns all PENDING reports that can be filed via the API (excludes free-text results).
Get Investigation Report	GET	Returns full detail for a single PENDING report, including groups, results, and existing filing comments.
List Unfulfilled Investigation Requests	GET	Returns outstanding investigation request items for a patient, so they can be offered as options to mark fulfilled on filing.
File Investigation Report	POST	Files the report, optionally attaching comments to groups or results, and marking request items as fulfilled.

A typical integration follows this order:

1. List Unfiled Investigation Reports: find all reports awaiting action.
2. Get Investigation Report: fetch the full detail of a chosen report to display to the user.
3. List Unfulfilled Investigation Requests (optional): if your integration offers the option to mark investigation request items as fulfilled on filing, call this to retrieve the outstanding requests for the patient, then present them for the user to select.
4. File Investigation Report: file the report, passing any filing comments and fulfilled request item IDs.

Patient intake and inbound referrals

Bringing a patient into Medicus, then creating the referral and clinical case that starts their care. Today this is used by mental health provider integrations, but the endpoints aren't mental-health-specific.

Three endpoints support the intake workflow:

Endpoint	Method	Purpose
Create Patient Record	POST	Creates a Medicus patient record from an NHS number, or returns the existing patient's ID if one is already linked to that NHS number.
Get Inbound Referral Metadata	GET	Returns the active commissioned services for this tenant and the fixed list of valid MHSDS referral reasons, plus the active clinical case types, for use when creating a referral.
Create Inbound Referral	POST	Atomically creates an inbound referral and a clinical case for a patient. The referral is always created with ACCEPTED status.

A typical integration follows this order:

1. Create Patient Record: pass the patient's NHS number to create (or find) their Medicus patient record. Use the returned id as the patientId in later calls.
2. Get Inbound Referral Metadata: fetch the tenant's active commissioned services, the valid reasonForReferral values, and the active clinical case types, to present as options.
3. Create Inbound Referral: create the referral and clinical case, passing the patientId and the chosen clinicalCaseTypeId. Include commissionedServiceId and reasonForReferral when the case should be included in MHSDS extracts.