Building healthcare software - organisations and healthcare services

Overview

This guide explains how to build software that deals with organisations and healthcare services within the NHS in England.

It is a non-technical guide, aimed at people building healthcare software, including:

product owners
architects
business analysts
delivery managers
software engineers

It covers the following topics:

what organisations and healthcare services are
what national services and APIs are available for your use case
the software delivery process
getting started

This guide is part of our series of domain-specific guides on building healthcare software.

For more context, also see our introduction to healthcare technology.

Organisations and healthcare services

The NHS in England is an ecosystem of care providers, each with a specific purpose or specialism.

This ecosystem is made up of organisations - legal entities, groups of people, care providers, third parties and so on - that provide healthcare services.

For example:

a GP practice is an organisation that provides a range of primary care services
an acute trust is an organisation that provides a wide range of secondary care services
a software developer is an organisation that provides no direct healthcare services

Organisations

These are usually legal entities, which might be public sector NHS organisations (such as acute trusts) or private sector organisations doing work for, or on behalf of, the NHS to provide health and social care services.

Some examples of organisations include:

GP practices
acute trusts
pharmacies
dental practices
social care providers
schools
prisons
software development organisations

Some of these organisations do not even provide healthcare services, such as software developers, who have a different relationship with the NHS as software suppliers.

Organisation Data Service

The Organisation Data Service (ODS) is a national service for managing information about organisations. It provides organisations with a unique identifier, known as an ODS code, and everyone else with the tools to look them up.

To support reporting or cross-charging needs, sometimes ODS codes can be allocated at a more granular level, for example, to an individual geographic site location, or even to an individual clinician.

ODS codes

ODS codes consist of 1 to 9 alphanumeric characters.

The table below shows what ODS codes look like.

Category	Sample ODS code	Description
GP	G3472185	General Medical Practitioner - SMITH J
Branch surgery	K81003001	Branch Surgery - DR. M. D. SMITH
Pharmacy	FVR79	Pharmacy - SMITHS CHEMIST
Dental practice	V03462	General Dental Practice - S.J. SMITH & ASSOCIATES
Social care site	VLAXL	Social Care Site - SMITH CRESCENT CARE HOME

For full details about ODS code formats, and the information held about each type of organisation, see the ODS Standards Repository guide.

Finding organisations

To access organisation information, including ODS codes, we provide two web user interfaces and two APIs for specific use cases as described below.

Some of these interfaces return a reduced data subset intended for transactional use. Others return a full dataset primarily intended for creating and maintaining a local data store.

The full dataset includes any details captured about:

relationships - meaning legal and operational relationships with other organisations, including history
succession - meaning the history of legal succession following organisational reconfigurations, mergers, and so on.

Examples of why you would want to look up details of an organisation include:

to find the GP practice that a patient is registered with
to make payments to a GP practice providing services, based on the legal entity providing them
to ship vaccines and consumables to a new vaccination site, such as a hotel or village hall, and pay the parent GP practice
to check that an ODS code received in a message or report is valid, and find the name or other details of the organisation
to share data under a 'GP Connect' data sharing agreement - these place limits on which organisations (legal entities) can access patient data

Guidance for specific use cases - organisations

The following table explains which user interface or API to use for specific use cases.

Use case	Channel	Guidance
For an ad hoc search for an organisation: to get full details of any relationships and succession with no access controls	User interface	Use the ODS portal. Use either the: organisation search to get details of organisations and also GP and dental practitioners within England and Wales geographic search to get details of local authority, higher health authority and clinical commissioning groups for postcodes in England and Wales
Download the ODS data you need: to get organisation details, not including any relationships or succession in CSV or Excel format without needing guaranteed 24 hours a day, 365 days a year availability with no access controls	User interface	Use the ODS DataPoint web user interface. You can download: predefined reports - the most commonly used ODS files, such as lists of branch surgeries, general medical practitioners, and so on user-defined reports - to choose, filter, arrange and export the ODS data you need
Search for an organisation from an application, maybe as part of another business process: to get organisation details, not including any relationships or succession without needing guaranteed 24 hours a day, 365 days a year availability with no access controls	API	Use the Organisation Data Service (ODS) - FHIR API. Use the: retrieval mode - to get a single ODS record search mode - to search for multiple matching records batch mode - to get baseline data from TRUD (in ORD format), then use the 'lastUpdateDate' parameter to get changes from that date up to 180 days later parameters to request an XML or FHIR STU3 JSON response
Search for an organisation from an application, maybe as part of another business process: to get full details including any relationships and succession without needing guaranteed 24 hours a day, 365 days a year availability with no access controls	API	Use the Organisation Data Service (ODS) - ORD API. Use the: retrieval mode - to get a single ODS record search mode - to search for multiple matching records batch mode - to get baseline data from TRUD (in ORD format), then use the 'lastUpdateDate' parameter to get changes from that date up to 180 days later '_format' parameter to request an XML ORD-standard, or a FHIR STU3 JSON response
Create a local copy of the dataset to search locally: to get full details including any relationships and succession with 24 hours a day, 365 days a year availability with user registration	API	Use the Technology Reference Update Distribution (TRUD) API to automate the download of TRUD release files which you then search locally. Use the API to: receive release downloads in the ORD XML standard receive monthly releases, where each release contains "full" and "archive" files. The "archive" contains all historic ODS items as removed from the "full" file.

Healthcare services

Healthcare services are provided by the majority of organisations.

healthcare services are normally grouped into categories according to the type of care they provide, as explained in the Healthcare ecosystem. Examples include:

dispensing services from pharmacies
urgent and emergency care services provided by ambulance trusts, NHS 111, urgent treatment centres, emergency departments or out-of-hours GPs

We have national services for looking up some, but not all, types of healthcare service. For instance, we do not have a lookup for education services.

Finding services

To find healthcare service information, we provide two web user interfaces, a widget and several APIs for specific use cases as described below.

The reason that a large number of healthcare service search directories exist, with different capabilities and lookup mechanisms, is largely for historical and speciality reasons. Most are referred to as “Directory of Services (DoS)” or simply “Service Search”.

Examples of why you would want to look up details of a healthcare service include:

for a referral and booking, to discover the required service using one of the DoS APIs
for prescribing using the Electronic Prescription Service (EPS), a key step is finding an EPS-enabled pharmacy service using a DoS API
following a call to NHS 111, to find the appropriate service for a patient referral available in the required timeframe

Guidance for specific use cases - healthcare services

The following table explains which user interface or API to use for specific use cases.

Use case	Channel	Guidance
For an ad hoc search for a healthcare service: with no access controls	User interface	Use the NHS.UK web user interface - also known as “Find services near you”. It guides the user through short journeys to find services in these categories: GP dentist optician hospital pharmacy urgent care services sexual health services pregnancy services mental health services other NHS services
For an ad hoc search for a healthcare service: as a healthcare worker only with a username and password	User interface	Use the NHS Service Finder web user interface.
To add an NHS healthcare service search by postcode to your website: embed code in your webpages generate the code when you register with the NHS website portal	Widget	Use the Find services widget. You can configure this widget to display NHS healthcare services (GPs, hospitals, dentists, pharmacies and opticians) searchable by postcode, on your webpages.
Search for a healthcare service from an application, maybe as part of another business process: without needing guaranteed 24 hours a day, 365 days a year availability with a subscription key you get when you register with the NHS website portal	API	Use the Service Search API. This API has a powerful search filtering capability, including filtering by: service provided, such as "asthma clinic" organisation type, such as "minor injury unit” location, such as latitude and longitude, postcode, or location name Search results include NHS organisations that provide healthcare services - as listed in the NHS service near you: trusts GP practices pharmacies community services schools offering services dentists opticians social care providers coronavirus (COVID 19) walk-in vaccination sites
Search for prescription dispensers from an application, maybe as part of another business process: based on their opening hours who can process electronic prescriptions - if they are EPS-enabled without needing guaranteed 24 hours a day, 365 days a year availability with access to the credentials for the sole dedicated DoS user for the EPS DoS API	API	Use the Electronic Prescription Service Directory of Services API. This provides two searches, to find dispensers by their: opening hours and location - based on the number of hours open from now, and the distance from the patient's postcode location name (required) and postcode
Search for prescription dispensers from an application, maybe as part of another business process: who can process electronic prescriptions - if they are EPS-enabled who are an 'internet pharmacy' such as 'pharmacy2u' without needing guaranteed 24 hours a day, 365 days a year availability with no access controls	API	Use the Electronic Transmission of Prescriptions Web Services - SOAP API. This provides four searches, to find dispensers by their: ODS code name, service type (community pharmacy or appliance contractor) and if they are EPS-enabled name, location, type and if they are EPS-enabled postcode, service type and if they are EPS-enabled
Search for a healthcare service from an application, in the context of an NHS Pathways patient encounter with NHS 111 and 111 online, 999, Urgent Care Clinical Assessments and urgent care or emergency departments: to find an appropriate NHS healthcare service to signpost the patient to to get an indication of service availability when you need guaranteed 24 hours a day, 365 days a year availability with a valid DoS account	API	Use the Directory of Services - Urgent and Emergency Care - SOAP API. You can search for services based on a combination of parameters: find an appropriate list of services for a specific clinical need get technical endpoint information for a given service, using a service ID or ODS code obtain capacity information for specified hospitals or wards, using a service ID or ODS code The search takes into account service opening times, for example, to avoid NHS 111 sending a patient to a service which closed 30 minutes earlier.
Search for a healthcare service from an application, in the context of any clinical diagnosis without an NHS Pathways outcome: to find an appropriate NHS healthcare service to signpost the patient to to get an indication of service availability when you need guaranteed 24 hours a day, 365 days a year availability with a valid DoS account	API	Use the Directory of Services - Urgent and Emergency Care - REST API but note this is not suitable for referrals from NHS Pathways patient encounters. You can search for services based on a combination of parameters: the patient’s age, sex, and current location the patient’s clinical need You can also search for services using similar parameters, such as by: service type - to find matching service type ID, location and optional patient details clinical term - to find matching symptoms, location and optional patient details ODS code - to find active services with a matching ODS code service ID - to find active services with a matching service identifier Search results include an indication of the capacity for services: green - high amber - low red - none
Search for a planned care service from an application, which a patient can be referred to: when you need guaranteed 24 hours a day, 365 days a year availability as an authenticated e-RS user with an e-RS role as a referring clinician, or a referring clinician admin	API	Use the e-Referral Service FHIR API’s patient service search endpoint.

The software delivery process

How you deliver your software is up to you. But there are some important things you need to plan in when building software for the NHS in England, such as clinical safety, security and information governance.

For more details, read our introduction to healthcare technology.

Getting started

To get started with building your software and using our API services and standards, see getting started.