Written by Technical Team | Last updated 09.01.2026 | 10 minute read
Developed by TPP, SystmOne supports healthcare organisations across primary, community and secondary care, enabling providers to share and access patient data securely. For innovators looking to build interoperable solutions, understanding how XML messaging works within SystmOne integration is essential. XML, or Extensible Markup Language, forms the backbone of communication between your application and the SystmOne client, ensuring data can be exchanged accurately, securely and efficiently.
At the heart of SystmOne integration is the ability to send and receive patient data in real time. XML messaging provides a structured and universally recognised way to transmit this information. Unlike simple text or proprietary formats, XML ensures that data exchanged between your application and SystmOne remains consistent, readable, and machine-interpretable. This is especially important in healthcare, where the accuracy of information can directly affect patient outcomes.
For digital health innovators, XML messaging allows for seamless communication without needing direct database access, which enhances both security and compliance. The structured nature of XML ensures that whether you are retrieving patient demographics, uploading new clinical information, or accessing historical records, your application communicates with SystmOne in a predictable and reliable way.
Beyond structure, XML also enables strict validation. Every request sent to SystmOne must conform to defined XML schemas (XSDs), which ensures malformed or incomplete data cannot be processed. This validation layer is critical in clinical systems, where incorrect or ambiguous data could have serious downstream consequences.
The SystmOne Client Integration API operates over a TCP socket, enabling third-party applications to open a connection with the SystmOne client installed on a local machine. Once the connection is established, all communication takes place through XML documents terminated with a newline character.
Your application sends a function request in XML, which the SystmOne client interprets. If additional data is needed, the client retrieves this securely from the SystmOne server before returning an XML response. This design ensures that data is always current while avoiding direct access to the underlying database.
Each XML request follows a consistent structure, including mandatory elements such as APIKey, DeviceID, RequestUID, Function name, and FunctionVersion. This consistency allows SystmOne to authenticate the calling application, audit every interaction, and maintain backward compatibility as the API evolves.
XML messaging within SystmOne is not asynchronous or event-driven. Instead, it follows a strict request-response model. Every request results in either a valid response or a structured error message, making error handling deterministic and auditable.
Key takeaway for SystmOne integrations: All communication with the SystmOne Client Integration API must use strictly structured XML over a local TCP connection, with every request validated against defined XSD schemas. Designing your XML messaging to respect throttling limits, filtering rules, and the LeaveRecordOpen behaviour is essential for building a reliable, compliant, and high-performance SystmOne integration that works seamlessly in live NHS environments.
One unique aspect of the SystmOne XML integration model is the use of Device IDs. When an application first connects to the SystmOne client, it does not yet have a DeviceID. By sending an XML request with an empty DeviceID element, the SystmOne client prompts the user to approve or block the connection.
Once approved, SystmOne generates a unique DeviceID for that installation. This DeviceID must be persisted and reused for all future requests. Doing so avoids repeated approval prompts and establishes a trusted relationship between the application and the SystmOne client.
From a security perspective, this mechanism ensures that integrations are both user-authorised and traceable. Every XML message sent is linked to a specific DeviceID, forming part of the SystmOne audit trail.
The SystmOne Client Integration API exposes a broad set of XML functions that enable discovery, retrieval, and modification of clinical data.
Discovery functions such as GetFunctions and GetOrganisationMetaData allow applications to dynamically understand what capabilities are available and retrieve contextual information about users, sites, clinics, and appointment slot types.
Patient-focused functions such as PatientSearch, GetCurrentActivity, and GetCurrentSelection allow applications to respond intelligently to what a clinician is currently doing within SystmOne. This makes it possible to build context-aware tools that adapt to the user’s workflow.
More advanced XML messaging functions, such as GetPatientRecord and UpdatePatientRecord, allow structured access to clinical data. These functions support granular filtering, enabling applications to retrieve only the data they need rather than entire patient records.
When building a SystmOne integration, success often comes down to choosing the right API function for the job and designing around the platform’s real-world constraints. The SystmOne Client Integration API uses XML messaging over a local TCP socket, with strict request formatting and schema validation, so understanding what each function is best suited for will help you build more reliable workflows.
The table below summarises common SystmOne Client Integration API functions, what they’re used for, and the key implementation considerations developers should factor in early (including throttling, filtering opportunities, and record handling behaviour).
| API function | What it enables | Typical XML inputs | Key constraint or best-practice |
|---|---|---|---|
| GetFunctions | Discovers supported functions and versions so your integration can remain compatible as the API evolves. | Function name + FunctionVersion with minimal FunctionParameters. | Use this during startup or diagnostics to confirm which function versions are available before sending requests. |
| GetOrganisationMetaData | Retrieves organisation context such as sites, users, clinic types, slot types, and teams. | Optional LoggedOnUserOnly parameter. | Use this to populate clinician/site pickers and to validate usernames, clinic types, and slot types used in appointment-related messages. |
| GetCurrentActivity | Detects what the user is doing in SystmOne and whether a patient record is open. | No additional parameters beyond baseline request fields. | Ideal for context-aware tools; always handle the case where no patient Identity is returned. |
| PatientSearch | Searches the organisation patient list by demographics such as name, DOB, postcode, telephone, and gender. | At least two search constraints in FunctionParameters. | Design UI/logic to enforce the “two constraints minimum” rule and handle valid searches that return zero results. |
| GetPatientRecord | Extracts all or part of a patient record, optionally filtered by dates and data categories. | Identity plus optional Filter fields like Demographics, ClinicalCodes, Medication, Results, Min/MaxEntryDate. | Highly sensitive to performance: it is throttled to 1 request per 30 seconds except for demographics-only or last-day entry-date filtered requests; always filter aggressively to reduce payload size. |
| UpdatePatientRecord | Adds new data to the patient record (clinical codes, medication, attachments, tasks, visits, appointments). | Identity plus Demographics and/or Clinical Event and/or NonClinical blocks. | Only send fields you intend to change; decide early whether LeaveRecordOpen should be used (interactive workflow) or omitted (background workflow with immediate commit). |
| GetDocument | Exports an attached document referenced in the record to a directory path you provide. | Identity, DocumentUID, and WriteTo directory. | Validate that WriteTo exists and is accessible to the client; handle cases where multiple files may be output depending on document format. |
| DeleteFromPatientRecord | Deletes data previously inserted by your software (not data entered by other sources). | Identity, Reason, and one or more UIDs (EventUID, AppointmentUID, TaskUID, VisitUID). | Reason must be populated; design for “all-or-nothing” behaviour when deleting multiple items in one request. |
| GetAppointmentSlots | Finds available appointment slots so your system can book appointments into real, pre-created SystmOne slots. | MinDateTime, MaxDateTime and optional UserName, SiteName, ClinicType, SlotType. | Use SlotType and ClinicType values returned by organisation metadata; do not assume free slots exist without checking. |
| GetDiary | Retrieves upcoming appointments and visits linked to patients (not “text-only” entries). | Date/time range plus optional filters by UserName and SiteName. | Useful for workload views and integrations that need to reconcile planned activity; handle that visits are not site-linked in the same way as appointments. |
All patient-related XML messaging in SystmOne is built around a robust identity model. Patients are uniquely identified by NHS number, or by a pseudo-number where an NHS number does not exist. In addition, responses include a StrategicReportingIdentifier, which aligns directly with SystmOne’s Strategic Reporting datasets.
This design allows innovators to combine real-time XML integrations with batch reporting extracts, enabling advanced analytics, population health insights, and longitudinal reporting across systems.
Importantly, the StrategicReportingIdentifier is response-only and must never be supplied in XML requests. This ensures that patient identification remains controlled and consistent.
One of the most powerful features of SystmOne XML messaging is the ability to filter data retrieval. The GetPatientRecord function supports extensive filtering by data type, effective date, entry date, and recording user.
This is not merely a convenience feature; it is essential for performance. A full patient record can be several megabytes in size when serialised into XML. By requesting only demographics, recent observations, or specific numeric readings, applications can reduce payload sizes dramatically.
The API also enforces throttling to protect system stability. Most XML functions are limited to one request per second, while GetPatientRecord is restricted to one request every thirty seconds unless narrowly filtered. Designing integrations with intelligent caching and request scheduling is therefore essential.
XML messaging within SystmOne is not limited to data retrieval. The UpdatePatientRecord function enables applications to add clinical codes, medications, attachments, appointments, tasks, and visits directly into the patient record.
Crucially, the same XML structures used for retrieval are reused for updates. This symmetry reduces complexity for developers and ensures consistency between read and write operations.
The API also introduces the LeaveRecordOpen mechanism, which determines whether changes are committed immediately or require a clinician to save the record manually. This distinction allows integrations to support both background automation and interactive clinical workflows safely.
Every XML message sent to SystmOne is audited. The Client Integration Message Audit screen allows administrators to view timestamps, message identifiers, and outcomes, as well as inspect full XML payloads.
Error responses follow a standard XML format, including a human-readable error message and a PermanentError flag. This allows applications to distinguish between transient issues, such as throttling, and permanent configuration problems that require intervention.
Some scenarios, such as throttled requests, may result in no response at all. Robust integrations must therefore implement timeout handling and retry logic.
Before deploying to live clinical environments, developers are expected to test their XML integrations using the SystmOne Demo environment. This environment mirrors live functionality while using fictitious patient data, allowing full validation of XML schemas, workflows, and performance constraints.
The availability of XML templates and the GetXSDFiles function further supports development by enabling schema validation and automated testing.
In some cases, rather than writing data directly via XML, it is preferable to invoke native SystmOne user interface workflows. The LaunchFunctionality function allows applications to open prescribing, coding, or attachment dialogs with data pre-selected.
This approach is particularly useful where clinical judgement or confirmation is required, ensuring that responsibility for final decisions remains with the clinician.
For digital health innovators, mastering XML messaging within SystmOne integration is more than a technical requirement—it is a strategic capability. XML provides a secure, auditable, and highly structured way to integrate advanced digital tools into real-world clinical workflows.
Whether enabling remote monitoring, automating administrative tasks, or delivering intelligent clinical decision support, XML messaging allows solutions to integrate deeply with SystmOne while respecting safety, governance, and performance constraints.
By fully understanding the SystmOne Client Integration API and designing XML interactions thoughtfully, innovators can build solutions that are scalable, compliant, and genuinely impactful in improving patient care.
Is your team looking for help with SystmOne integration? Click the button below.
Get in touch