Written by Technical Team | Last updated 17.10.2025 | 13 minute read
GP Connect: Appointment Management is the national interface for booking and managing GP appointments across England’s principal practice systems. It enables authorised systems to retrieve a patient’s appointments, search for free slots, and then create, amend, read or cancel bookings held in the GP clinical system. In plain terms, it standardises appointment management across organisational and vendor boundaries so that an urgent care hub, NHS 111, a federation, or another provider can book into a practice diary reliably and safely. At a technical level, it is a FHIR-based REST API delivered over the NHS Spine, with a set of carefully profiled resources and interactions designed specifically for the realities of general practice.
The API is intended for clinical and administrative use within direct care. It is not the same as a patient-facing booking interface (which has its own, distinct specification) and it expects consumer software to operate within NHS governance, audit and security constraints. Because GP Connect relies on Spine services, consumers typically deploy on, or reach, the Health and Social Care Network (HSCN), route calls via the Spine Secure Proxy (SSP), and include an auditable JSON Web Token (JWT) with each request. The model ensures providers can expose bookable capacity safely and only to those organisations with an appropriate data sharing arrangement in place.
Conceptually, the Appointment Management capability sits alongside Foundations (for demographics and organisation data) and other GP Connect capabilities. In practice, that means you’ll call the Foundations API for “Read Patient”, “Read Organisation”, “Read Location” and related lookups to support appointment workflows, then use Appointment Management for the business acts of finding slots and creating or managing the booking itself. This division of responsibilities keeps appointment interactions slim and focused while ensuring a single, authoritative source for essential reference entities.
The integration surface is deliberately opinionated about security. All traffic flows through the Spine Secure Proxy, which provides a single point for authentication, authorisation, auditing and data-sharing agreement checks. Transport is TLS with mutual authentication on both legs, and the consumer must attach a JWT to every request that captures user identity, role, the consuming system, and the consuming organisation’s ODS code (and, where used, Smartcard/SDS identifiers). This design gives providers confidence that a booking operation is attributable to a specific user in a specific organisation, without providers having to implement a different trust model for every external system.
From a governance point of view, this is a direct-care API. You’ll need to be clear about your purpose, keep local role-based access controls tight, and operate within NHS information governance expectations. Before building, check your network posture: most implementations will require HSCN connectivity to reach the SSP; if you operate from multiple environments (development, test, production), confirm how each environment will reach the proxy and how certificates will be managed across them. The NHS provides a publicly accessible demonstrator (“Orange Test Lab”) for initial exploration and integration exercises, and a formal Integration (INT) environment for more rigorous end-to-end testing.
Onboarding is a structured journey and worth factoring into your delivery plan. First, submit a use case describing who you are, what business problem you’re solving, and how you intend to use the API. Once approved, you pass through consumer assurance—essentially technical and safety due diligence—to demonstrate your conformance to the specification and that your application is safe in context. The assurance process maps to artefacts you’ll need to produce (for example, clinical safety documentation under DCB0129/DCB0160 led by an accredited Clinical Safety Officer), and gates that you pass as you move from demonstration to integration to provider testing and, ultimately, live. Build time is precious; align your development milestones with the assurance gates so evidence creation and technical progress reinforce one another.
To keep your discovery and mobilisation tidy, assemble a short readiness checklist at the outset:
Appointment Management uses a tight set of FHIR STU3 resources and profiles. On the “search for free slots” path, the response is a Bundle containing GPConnect-profiled Slot and Schedule resources, plus references to Practitioner, Location and Organisation where appropriate. The Slot tells you when and for how long a bookable window exists; the Schedule provides the broader context of the diary and its service or practitioner; and the referenced resources link that capacity to real-world people and places. By constraining the resource shapes and binding key elements to controlled values, the specification ensures consistency across principal GP systems without demanding identical internal implementations from each vendor.
The core booking interactions are exactly what you’d expect: read an appointment, create (book) an appointment, amend an appointment and cancel an appointment. Creating a booking involves POSTing a GPConnect-profiled Appointment resource that associates the chosen Slot with the Patient and other participants. Amending uses an update interaction to modify attributes such as the appointment’s start time (where supported) or participant details; cancelling changes the status to “cancelled” with an appropriate reason code so provider systems can audit and surface the change correctly to staff and patients. The read operation returns the authoritative state from the provider. Where things go wrong—invalid references, conflicts, or business rule violations—the provider returns an OperationOutcome that explains the failure in a machine- and human-readable way.
It’s worth dwelling on the division of labour between Foundations and Appointment Management. Even though you can technically attempt to book with minimal context, any robust integration will do its homework upfront: confirm the Patient using NHS Number, pull back the Organisation and Location references for the practice and branch surgery, and retrieve Practitioner or PractitionerRole details where relevant. That way your Appointment resource contains resolvable references that the provider’s validation rules expect, and your user interface can present people and places with confidence. In environments where the consumer is booking into multiple practices or hubs, Foundations calls also drive your local directory and selection menus, reducing friction for users who book regularly into the same set of providers.
Behind the scenes, the capability also defines Spine “interaction IDs” for each operation. These URNs identify the specific message semantics and are used by the SSP to route and authorise requests. For example, there are interaction identifiers for “Get patient appointments”, “Search slot”, “Read appointment”, “Create appointment”, “Amend appointment” and “Cancel appointment”. From a developer’s perspective, think of these as the canonical contract labels that your HTTP layer must include in headers so the proxy and provider recognise precisely which behaviour you’re invoking. Treat them like you would versioned RPC names: hard-code them in your client library, write tests that assert they’re present, and make them discoverable in your logs for triage.
The resource profiles themselves aren’t just documentation—they’re design constraints that shape your payloads. GPConnect Appointment carries the participants (patient, practitioner or service), the start and end, the status and reason, and references to the Organisation and Location context. GPConnect Slot and Schedule add the scaffolding that makes capacity discoverable and bookable. If your application currently models “appointment type”, “delivery channel” (for example, telephone or face-to-face) or “provider role” in free text, you’ll need to adopt the standardised value sets mandated by the profiles. That improves search quality and reduces mis-booking by ensuring a slot described as “telephone with advanced nurse practitioner” means the same thing in every connected system.
Most teams start with a canonical “find-book-confirm” flow and then iterate for the realities of federations, extended hours, and urgent care. A defensible baseline looks like this:
If you book within a single registered practice, life is straightforward. Your consumer uses the ODS code for the patient’s practice and calls the slot search, then posts the booking. But as soon as you cross organisational boundaries—into federations, extended access hubs, or geographic “nearby” practices—you need a reliable way to determine the right practice and its ODS code. The specification recognises this and proposes different discovery strategies. Locally, your system might offer a pre-configured pick list of known practices (ideal for federations). Regionally, or for NHS 111 and other urgent and emergency care consumers, you can lean on the Directory of Services (DoS) to identify appropriate practices by hours, distance and service provision, and then proceed with booking. In any case, you still verify the patient’s NHS number via PDS to ensure you’re booking for the right person.
Slot availability is where design discipline pays off. Practices control which slots are exposed to GP Connect and to which organisation types or named organisations. They also categorise slots by delivery channel and practitioner role, which your UI should reflect to reduce errors. Put guardrails in your client: filter for compatible slot types based on the clinician’s scope and the booking context; warn if the slot’s channel doesn’t match the user’s expectation; prevent over-booking race conditions by re-validating slot status immediately before POSTing the Appointment. If you do encounter a conflict (for example, two users attempt to book the last slot simultaneously), surface the OperationOutcome cleanly and jump the user back to an updated list of slots rather than leaving them in a dead end.
Amend and cancel deserve as much product thinking as create. Not every field is amendable, and some providers’ rules limit what you can change after booking. Establish a clear user experience for rescheduling: in many workflows, “reschedule” is implemented as cancel-and-rebook; ensure your cancellation reason codes are mapped to provider expectations and that the audit trail is explicit about who did what, when and why. On cancellation, immediately release the slot back into search results to keep supply visible. For changes that are allowed via amend, apply a validation pass against the provider’s current state just before update so you don’t overwrite an appointment that has been altered locally at the practice.
Finally, plan for cross-system realities. Appointments booked via GP Connect must remain readable and manageable in the host GP system, and staff must see context such as booking organisation and reason. Conversely, make sure your own users see local context from the provider: location and route details for the branch surgery, whether the clinician offers phone or video at that time, and any pre-visit instructions. Much of this is present in the profiled resources; the rest can be wrapped in mutually agreed booking notes, always mindful of local information governance. A good integration translates between the universal (standardised codes and structures) and the local (how a practice actually runs its diary) without either side being surprised.
The fastest path to a robust integration is to build in the order the NHS assurance tooling expects. The Automated Test Suite focuses first on “search for free slots”, then “book an appointment”, and only after that “retrieve a patient’s appointments”, “amend”, “cancel” and “read”. That ordering mirrors real dependencies: you need working Foundations to validate references inside slot search responses; you need slot search and patient registration to book; and you need bookings in place before you can retrieve or amend them. Wire your CI to run the suite endpoint-by-endpoint as you implement each capability, and capture the HTTP exchanges for later analysis (including the interaction ID headers). This approach not only satisfies conformance but also bakes stability into your project from day one.
There are common snags to avoid. First, short-cutting Foundations lookups leads to brittle payloads and confusing validation errors; invest in reusable client functions for Patient, Organisation, Location and Practitioner reads. Second, treat your JWT as a first-class artefact: include a clear user ID, role and ODS code, and log JWT IDs against request IDs for end-to-end traceability through the SSP. Third, don’t assume every provider exposes the same slot metadata or supports the same edge-cases of amend; code defensively and test against more than one supplier. Fourth, make slot search fast and forgiving—users often filter by date and channel first, not practitioner, and appreciate graceful fall-backs when a specific filter yields no results. Last, embed clinical safety thinking early. Appointments are the front door to care; good hazard analysis will surface scenarios such as double-booking, mis-routing to the wrong location, or inadvertent booking under the wrong patient—issues the specification helps you prevent, but only if your UI and validation follow suit.
The current Appointment Management capability is built on HL7® FHIR® STU3 with GPConnect-specific profiles for the key resources (Appointment, Slot, Schedule, plus references to Practitioner, Organisation and Location). If you are used to R4 or later, be mindful of subtle differences in elements and search parameters; your models and client library settings should match STU3 for this integration.
If you’re booking into the patient’s registered practice, you’ll typically discover the ODS code via PDS and proceed. If you’re booking into other practices—federations, extended access hubs, or practices near a patient’s current location—use local configuration (for known partners) or the Directory of Services to discover services by hours, distance and eligibility, and then book using the practice’s ODS code.
The NHS runs the API 24×7×365 but provides support during business hours. In operational terms: design for resilience and graceful degradation; expect your own on-call to investigate consumer-side issues out of hours; and build idempotent retry logic for transient network or proxy blips. The demonstrator and INT environments are there for you to measure client behaviour under fault conditions before you ever touch live.
No, not strictly. You must implement local RBAC and include user and role details in the JWT. If your organisation already uses Smartcards, their identifiers can be included; otherwise, ensure your local identity provider can assert the necessary claims with the right level of assurance for direct-care operations.
Design for cancel-and-rebook unless you have a hard requirement to use “amend” to move times. Either way, check the provider’s current state immediately before your change, propagate reason codes, and confirm the outcome with a fresh read. Where possible, surface the booking organisation and notes to staff so they have the full picture.
Is your team looking for help with GP Connect integration? Click the button below.
Get in touch