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. Workflow builds on the base Transactional API: the same authentication and base URL apply.
Two workflows are covered today:
- Investigation report filing: list a patient's unfiled reports, fetch one's full detail, optionally list their unfulfilled investigation requests to offer as fulfillable, then file the report.
- Patient intake and inbound referrals: create (or find) a patient's Medicus record from their NHS number, fetch the tenant's referral metadata, then create the referral and clinical case together. Today this is used by mental health provider integrations, but the endpoints aren't mental-health-specific.
Retrieve Confidential Care Record
Retrieves the patient's structured care record, including confidential items (allergies, medication, consultations, problems, immunisations, investigations, referrals, diary entries and uncategorised data), via [GP Connect Access Record: Structured](https://digital.nhs.uk/developer/api-catalogue/gp-connect-access-record-structured-fhir). The patient must have an NHS number. Returns a FHIR STU3 Bundle.
List Unfiled Investigation Reports
Returns all PENDING investigation reports that have been matched to a patient. Reports that contain any free-text result values are excluded, as those cannot be automatically filed.
Get Investigation Report
Returns the full detail of a single PENDING investigation report.
List Unfulfilled Investigation Requests
Returns all UNFULFILLED investigation request items for a patient, grouped by their parent investigation request.
File Investigation Report
Files a PENDING investigation report by resolving the associated review task. Optional filing comments may be provided for specific groups or results. Investigation request items may be marked as fulfilled.
Create Patient Contact
Adds a contact (next of kin, emergency contact, etc.) to a patient record. User-restricted only.
List Collection Locations
Returns all active dispensing collection locations with their identifier and name, for use as preferredCollectionLocationId on register-permanent-nhs-patient.
Register Permanent NHS Patient
Registers a new GMS permanent registration for a patient, the same effect as a receptionist completing GMS registration in Medicus. User-restricted only: the calling staff member must have a CIS2 identity with the B0825 (Amend Patient Demographics) RBAC activity code. Place of birth is not accepted here: for an NHS Number patient it is sourced from the PDS record, not from the request.
Register Patient Without NHS Number
Registers a new GMS permanent registration for a patient who has no NHS number yet (not yet traced, non-UK arrival, private-only, etc), the same effect as a receptionist completing the 'without NHS number' GMS registration in Medicus. User-restricted only. **Do not use this endpoint if the patient has an NHS number** - use register-permanent-nhs-patient instead, which registers via PDS and keeps the patient's NHS number correctly linked. This endpoint never checks whether one exists, and registers the patient without one regardless.
Update EPS Nominated Pharmacy
Sets or replaces the patient's EPS nominated pharmacy. Omit or send an empty pharmacyOdsCode to remove the nomination instead. User-restricted only.
Update Patient Address
Sets the patient's address of the given type, removing any existing address of that type first. User-restricted only.
Update Patient Email Address
Sets the patient's email address of the given type, removing any existing address of that type first. User-restricted only.
Update Patient Official Name
Sets the patient's official (legal) name. Changing this while the patient has an active NHS permanent registration sends an NHS GP Amendment message via NHAIS. User-restricted only.
Update Patient Preferred Name
Sets the name the patient prefers to be called, separate from their official name. Has no NHAIS side effect. User-restricted only.
Update Patient Telephone Number
Sets the patient's telephone number of the given type, removing any existing number of that type first. User-restricted only.
Update Summary Care Record Consent
Sets the patient's consent preference for their Summary Care Record and pushes the change to Spine. User-restricted only: the calling staff member must have a CIS2 identity with the B0020 (Control Consent Status) RBAC activity code.
Create Patient Record
Looks up the given NHS number in the NHS Personal Demographics Service and creates a Medicus patient record from the returned demographics. If a patient with this NHS number already exists, their existing Medicus ID is returned. Does not create a GP registration.
Get Inbound Referral Metadata
Returns the active commissioned services for this tenant and the fixed list of valid MHSDS referral reasons, plus the active clinical case types. Use the returned IDs/values when calling the create-inbound-referral endpoint. Clinical case types include a flag indicating whether a commissioned service must be provided.
Create Inbound Referral
Atomically creates an inbound referral and a clinical case for the given patient. The referral is always created with ACCEPTED status. If a `commissionedServiceId` is provided, the case will be included in MHSDS extracts; include `reasonForReferral` to populate the MHSDS referral reason field.