Integrating With The SystmOne Patient Facing Services API – A Technical Overview

For digital health innovators with patient facing services operating within the NHS ecosystem, integration with clinical systems is pivotal. TPP’s SystmOne Patient Facing Services (PFS) API provides a gateway for approved third-party applications to interact directly with primary care services, empowering patients with greater control over their health data and facilitating better communication with their GP practice. This article offers a technical walkthrough for integrating with the PFS API, highlighting its architecture, message handling protocols, authentication flow, core functionalities, and implementation considerations.

The SystmOne PFS API is as a secure, XML-based web service available over the NHS HSCN network. It uses HTTPS with TLS 1.2 encryption and mutual authentication to ensure that only certified parties can access the service. TPP provides client-side certificates and a secret provider ID upon registration. Requests and responses use UTF-8 encoded XML payloads and include custom HTTP headers to maintain session integrity.

The API architecture is synchronous, meaning the client sends a request and waits for an immediate response. Each session is uniquely identified by a suid, which must be included in all subsequent requests following successful authentication.

Before any technical integration can begin, a digital health supplier must register as a provider with TPP. This pairing process results in the issuance of a certificate and a unique provider ID, both of which are essential for API communication. Only registered and approved providers are allowed access to patient-facing services via this API.

SystmOne PFS API Authentication and Session Flow

Integration begins with account linking and user authentication. This is a multi-step process designed to secure patient data and manage access accurately:

• LinkAccount – This message is sent once per user to establish the link between their GP online account and the third-party application. The request includes patient credentials such as account ID, linkage passphrase, date of birth, and practice ODS code.
• Authenticate – Once the account is linked, this message is sent at the start of every session. It uses the secure passphrase returned from the LinkAccount reply. Upon success, it returns user and patient metadata.
• PatientSelected – If a user has access to multiple patients (e.g., carers or parents), this message specifies which patient is the focus for the session.
• Logoff – This message ends a session and invalidates the session ID (suid). It is good practice to explicitly send this message to ensure security and clean session management.

All requests must include a type header indicating the message being sent and a suid header once a session has been established. The suid is sensitive and must never be exposed to end-users. Each response from the server also contains a suid, which the client must persist for the duration of the session.

SystmOne PFS API Functional Capabilities

The SystmOne PFS API supports a broad range of operations designed to give patients agency over their healthcare interactions. Below is an outline of key functionality.

Appointment Management

• ListSlots – Retrieve bookable slots over a defined time range.
• BookAppointment – Schedule an appointment in a selected slot.
• ViewAppointments – Fetch both upcoming and past appointments.
• CancelAppointment – Remove a scheduled appointment.

These operations require detailed input, including patient and ROSU (Registered Online Service User) IDs, session and appointment details, and optionally, user notes.

Record Access

• RequestPatientRecord – Retrieve a comprehensive, event-driven summary of the patient’s medical history.
• TestResultsView: Access lab results and diagnostic reports.
• ListRecordAccesses – Review audit logs of who accessed the patient record and when.
• ViewPatientOverview – Retrieve a snapshot of patient data including medications, allergies, and sensitivities.

All returned data is unstructured and should be displayed as-is, avoiding transformations or parsing that may alter clinical meanings.

Medication Management

• ListRepeatMedication / ListAcuteMedication – Fetch currently prescribed medications.
• RequestMedication: Submit repeat or acute medication requests.
• AmendPrescriptionRequest – Modify or cancel an existing request.
• GetPrescriptionRequests – Review outstanding or recently actioned requests.

The API enforces request integrity by requiring the most recent medication list to be fetched before submission, thus reducing errors and ensuring clinical accuracy.

Messaging and Communication

• MessageCreate / MessagesView – Enables two-way communication between patients and clinicians.
• UnreadMessageCount / MessageMarkAsRead / MessageDelete – Manage communication states.
• MessageRecipients – Query permissible recipients for patient-clinician messages.

Attachments in standard formats (e.g., PDF, JPG) can be included in messages. It is the provider’s responsibility to perform virus scanning prior to submission.

Demographic and Preference Management

• ChangeDemographics / RetrieveDemographics – Submit and retrieve patient or user contact details.
• RequestCommunityPharmacy / UpdateCommunityPharmacy – View and manage nominated pharmacies.
• RequestAccountInformation / ResetOnlineAccount – Manage online user account settings and third-party associations.

SystmOne PFS API Data Standards, Security, and Error Handling

All communication utilises XML with strict data formatting rules. Dates are specified in the format YYYY-MM-DDTHH:MM:SS.0Z, and boolean fields are represented by y (yes) or the absence of a tag (no).

The API also defines standard tags such as Address, PersonName, and TelephoneNumbers, which must be used consistently across all messages to ensure data compatibility and schema compliance.

When an error occurs, the API returns an error response with the following fields:

• errorCode – A numeric code for internal diagnostics.
• userFriendlyMessage – A safe-to-display explanation for end-users.
• technicalMessage – Additional context for debugging, if available.

Integrators are encouraged to gracefully handle all possible errors, displaying informative messages to users and logging technical details for support teams.

Security is enforced via:

• TLS 1.2 with mutual authentication: Both server and client validate each other using certificates.
• Encrypted session management: All active sessions are tokenised using suid, which must be protected.
• Granular patient access: Practices maintain full control over which features are available to users and which patient records they can access.

No patient-identifiable information should be stored or logged outside the constraints of the API specifications unless explicitly allowed by applicable GDPR regulations and local IG (Information Governance) policies.

SystmOne PFS API Development Environment

Upon request, TPP provides access to a test environment, enabling end-to-end development and validation without accessing live patient data. The CheckVersion message can be used to verify supported API versions, ensuring compatibility over time.

Providers must ensure their application is tested thoroughly in this environment before requesting production credentials. Automated tests should cover all message types, session flows, and error conditions.

SystmOne PFS API Integration Recommendations

To ensure a smooth and maintainable integration, it is recommended that product teams:

• Abstract API interactions into a dedicated service layer within your application.
• Implement comprehensive logging (excluding sensitive data) for debugging and auditing purposes.
• Build user-friendly interfaces that mask the complexity of session handling and error resolution.
• Provide clear and secure mechanisms for patients to input their linkage credentials during the initial LinkAccount step.
• Implement robust retry mechanisms and timeouts to handle network or server-side issues gracefully.
• Always send a Logoff message when the session is no longer required.

Conclusion

Integrating with the SystmOne PFS API offers digital health innovators powerful access to patient services and clinical workflows. While the technical implementation is quite complicated, adhering to TPP’s specification ensures secure, efficient, and clinically safe operations. By thoroughly understanding the messaging flow, authentication model, and XML structures, technical teams can build reliable and impactful integrations that align with NHS transformation goals.

Are you thinking about integrating with the SystmOne Patient Facing Services API? Contact 6B for support.