Skip to main content

GP Connect Appointment Management - FHIR API

Manage GP practice appointments between different systems.


Use this API to enable administrative and clinical end users to book and manage patient appointments held in any of the principal GP practice systems.

You can:

  • retrieve a patient’s appointments
  • search for free slots
  • read an appointment
  • book an appointment
  • amend an appointment
  • cancel an appointment

For example:

  • staff at a GP practice can book, view, amend or cancel appointments on behalf of a patient at another practice
  • organisations such as NHS 111 call centre, out of hours services, or extended access hubs can book, view, amend or cancel appointments on behalf of a patient at their registered GP practice or federated GP practices

Note: You need to use this API in conjunction with the GP Connect Foundations FHIR API. With this API you can:

  • get patient details - “Read Patient”

  • search for patient - “Patient Search”

  • get practitioner details - “Read Practitioner”

  • search for practitioner - “Practitioner Search”

  • get organisation details - “Read Organisation”

  • search for organisation - “Organisation Search”

  • get location details - “Read Location”

  • register patient - “Register Patient”

For more details, see the GP Connect specifications for developers.

For a non-technical overview of how to build software that deals with referrals and bookings, see Building healthcare software - referrals and bookings.

Who can use this API

This API can be used by developers of clinical systems that support clinicians delivering direct care. It is not a patient-facing API.

Before you start development, read the Appointment Management section of the GP Connect v1.2.7 specification, which includes Foundations, and the prerequisites listed below.  



You must:

Information governance (IG)

You must:

  • be compliant with the GP Connect Direct Care API Information Governance Model
  • manage access to your system locally using local role-based access control (RBAC). This does not need to be compliant with the national RBAC model and GP Connect products do not require smartcards to control access, though they can be used if already implemented
  • be using the GP Connect APIs for direct care purposes for NHS patients in England

Clinical safety

You must:

If you are confident that you can meet the prerequisites, contact us to express your interest. See 'Onboarding' below.

API status

This API (v1.2.7) is in production.

It might not be fully supported by all providing systems. See GP Connect supplier progress for details of provider rollout.

Service level

This API is a silver service, meaning it is operational 24 x 7 x 365 but only supported during business hours (8am to 6pm), Monday to Friday excluding bank holidays.

For more details, see service levels.


This API is a FHIR API.

It sends a FHIR STU3 payload over a Spine Server Proxy (SSP) transport.

For more details, see FHIR.

Network access

You need a Health and Social Care Network (HSCN) connection to use this API.

For more details, see Network access for APIs.

Security and authorisation


Access to the GP Connect APIs is controlled and protected by the Spine Secure Proxy (SSP), a forward HTTP proxy.

It provides a single security point for both authentication and authorisation for consuming systems. Additional responsibilities include auditing of requests, checking data sharing agreements and transaction logging.

All HTTP communications are secured using TLS MA. This includes both legs of the request, from consumer system to the proxy and then from the proxy to provider system.


Authorisation takes place in two locations: 

  • the consumer system
  • the SSP

The consumer system must have local RBAC in place and restrict GP Connect APIs to authorised users. With each request, a JSON Web Token (JWT) must be included with the following information:

  • details of users, including role
  • where smartcards are used in the consumer system, including SDS user and role IDs
  • details of the consumer system
  • details of the consumer’s organisation, including ODS code

The information in the JWT is retained for audit purposes.

The SSP checks data-sharing agreements to ensure that the consumer system is authorised to communicate with the provider system.

Environments and testing

Environment URL
Internet-facing demonstrator
Opentest environment
Integration (INT)

Provided during onboarding process


Expressing an interest

If you meet the prerequisites and have a product that can integrate with GP Connect, you should express an interest with us by submitting a use case.

The main purpose of the use case is to help us understand how you plan to use GP Connect APIs and the business issue you are looking to address. You can submit your use case directly to the GP Connect team by completing a use case submission form.

Once we receive your use case, we'll respond within 14 days.

Consumer assurance process

Once we approve your use case, we support you through the assurance process to go live. We will discuss the assurance process and artefacts with you to help you understand our requirements.

Implemented at
local level
Implemented at...
Consumer assurance process
Appointment Management
Consumer assurance process...
Use case
approved by
NHS Digital
Use case...
Complete the requirements in the SCAL and provide supporting evidence
Complete the requirements in the SCAL and provide supporting evide...
Development to specifications
Development to spe...
Enabled for
use in live
Enabled for...
Sign connection agreement
Sign connection...
Technical conformance
Technical conformance...

Test in internet facing demonstrator
Test in internet facing d...
Gate 1
Gate 1

Test in Integration (INT) environment
Test in Integration (INT)...
Gate 2
Gate 2

Test against providers
via INT
Test against providers...
Gate 3
Gate 3
Text is not SVG - cannot display Consumer assurance process for GP Connect Appointment Management

Start your development work within 6 months of use case approval. If you miss this date, a review or new submission of the use case will be required. Changes or additional development will also require a review or new use case submission. 


For a full list of interactions for this API, see Appointment Management which includes Foundations.

For details on the general structure of the interactions, see FHIR.

Last edited: 28 July 2023 10:06 am