The IM1 Transaction API is the real-time, professional-facing part of IM1. It lets a third-party application act on a GP clinical system while a clinician or practice user is working, searching for a patient, reading and updating their demographics, working with consultation records, and filing documents. It is the API most clinical workflow products look at first, and it is also the one most often misunderstood, because teams assume it covers more than it does. This article sets out what it does, what it leaves to other routes, and what to settle before building.

What the Transaction API is

The Transaction API is one of the IM1 API standards, alongside the Patient, Bulk, and Partner APIs. With the permission of the patient and the GP practice, a consumer application, the product being built, makes requests in real time to a provider system, the GP's core clinical system. The two foundation providers offering IM1 APIs are Optum, for EMIS Web, and TPP, for SystmOne.

The functionality offered by each provider differs. IM1 gives a common standard and a common assurance route, but each supplier publishes its own guidance in a Pairing and Integration Pack, and what is available can vary between them. NHS England advises that if the functionality you need is not yet available from a supplier, you should contact the IM1 team before starting development, who will try to establish when it is due.

What it covers

The Transaction API supports three groups of work.

Patient search and demographics. An application can search for a patient and retrieve and update their demographic details. Search is the first call in almost every workflow, and it is where identity safety is won or lost. A search that returns the wrong patient, or several patients, has to be handled deliberately, not left to the interface to resolve.

Consultation records. An application can retrieve a patient's consultation record and create a new one. This is how a third-party product captures an encounter inside the GP system rather than holding it only in its own database. A document or attachment can also be added to a consultation record, which keeps the evidence with the entry it relates to.

Documents. An application can retrieve documents already in the patient record and file documents into it. Access to free text and documents is controlled and limited to approved use cases, so a product should expect to be given only what its assured purpose needs.

What it leaves out

This is where scoping mistakes happen, so it is worth being precise.

Appointments are not a dependable part of the Transaction API. NHS England notes that appointment functionality may only be available via GP Connect. Where appointment booking and cancellation are needed against EMIS Web, the Partner API offers them, and that API applies only to the EMIS Web GP module for practices in England. A product that needs bookable slots across suppliers should plan on GP Connect Appointment Management, and our guide to that capability covers the build.

The Transaction API is also not a bulk or analytics route. The Bulk API exists for scheduled extracts, and its data can be up to 24 hours old, which is why NHS England does not recommend it for direct care. Equally, a product built on Transaction calls should not be treated as a data warehouse feed.

Some functions that appear in third-party descriptions of the API, such as prescribing a drug, are not in NHS England's published Transaction API functionality. If a product depends on prescribing, or on any capability not listed, confirm it with the IM1 team and the provider supplier before committing to a design.

What real time means for the design

Real time here means each request is answered by the live GP system when it is made. It does not mean state is kept in step across systems for you. A change made in the GP system is not pushed to your application, and a change you file is subject to the provider's validation and to the practice's own workflow.

That has design consequences. Do not hold clinical data longer than the task needs, and treat anything cached as potentially stale. Re-read before you update, so you do not overwrite a record changed in the practice since you last looked. Make writes idempotent, so a retried request cannot create a duplicate consultation or document. And design the interface to show what has been confirmed by the GP system, not what has merely been sent.

The route to integration

Integration runs through an onboarding process managed by NHS England.

First, complete the IM1 prerequisites form, which establishes that the application meets clinical and information governance requirements. Next comes a compatibility assessment of the consumer system against the provider's API. Once compatibility is confirmed, a Model Interface Licence is executed with each provider supplier, which gives access to a test environment. Development and testing follow, with testing carried out alongside the GP system provider. Finally, the solution is assured by NHS England, and on a successful outcome it is rolled out to live practices.

The Supplier Conformance Assessment List sits through this process, and it is worth treating as a working document from the first week rather than a form to complete at the end.

What to settle before building

• Identity and matching. Decide what counts as a strong enough match before any write, an NHS number with date of birth for example, and design for no match and multiple matches as normal outcomes.
• Consent and permission. Both the patient's consent and the practice's approval are needed before data is accessed or updated, and the product has to show that it holds them.
• Supplier differences. Plan for variation between Optum and TPP from the start, with a normalised internal model and a mapping for each supplier, rather than discovering the differences after the first connector is written.
• Audit. Record who did what, to which patient, when, and with what outcome, because an integration that touches a clinical record will be asked to explain itself.
• Standards. Alignment with wider standards, NHS login, the Spine, and FHIR-based APIs such as GP Connect, keeps the product from becoming a dead end as national interfaces move.

Where this connects to build work

The Transaction API is most useful when it is the last step in a carefully controlled path: search for the patient, retrieve demographics, let a user review them, then write back only what has been approved. The closest work we have delivered is a primary care integration where clinicians enter an NHS number and date of birth, the system retrieves verified demographics from the NHS Spine, the user reviews and edits the record, and approved data is written to the internal system. Every lookup was audited, and edge cases such as a deceased patient or a superseded NHS number were handled explicitly. The integration route was different, but the discipline was the same one a Transaction API integration needs.