NDP Demographics API Useful Information | The National Digital Platform

Overview

The NDP Demographics API allows to retrieve demographics data for individuals registered with NHS Scotland.

Demographics data includes:

name
date of birth
postcode
other non-clinical information

Supported Operations

The system allows users to:

retrieve demographics details by using a patient’s Community Health Index (CHI) number
retrieve a CHI number using demographic details provided in HL7 FHIR format if the patient’s CHI number is unknown

The accuracy of the demographics data depends on:

citizens keeping their GP records up to date
GP practices recording patients’ data accurately in the National CHI Database

Environments

There are two environments available externally

1. Staging Environment

This environment is designed for development and integration testing. It contains test patient data.

Credentials for this environment are available on request. For more information, go to the 'Onboarding and Getting Access' section at the end of this document.

Support for this environment is available Monday to Friday, 7am to 6pm.

2. Production Environment

This environment contains live patient data.

Credentials for this environment are issued following information governance approval. If you require production access, notify us at least 4 weeks in advance.

Network Security

There are no IP restrictions in place for any of the environments.

Authentication and Access Control

Authentication

The API uses OAuth 2.0 access token authentication. Clients must obtain access tokens from the NDP Identity and Access Management service.

Authorization

The client must include access token in the 'Authorization' header of every API request.

Scopes

The client will be registered with the appropriate scope or scopes for the operations they need depending on if they want to:

look up by CHI Number: platform.ndp.scot/patient:read
match by Demographics: platform.ndp.scot/patient:search

Access

The NDP Demographics Service supports 2 access patterns:

User-level

This is the access pattern for any application that has end users using the system.

The application makes requests using the authenticated user's identity. This means, each API call is attributed to a specific user rather than the application itself. This process allows for more granular access to data as well as auditing of user actions. The user will normally use the Authorization Code Flow to obtain the Bearer token.

In production, users of NHS Scotland EntraID will be able to sign in with the NHS Scotland credentials.

Application-level

This access is only granted in special cases when an application is trusted and it’s not possible to provide user-level access. The application will use the Client Credentials Flow to obtain the access token.

In this case, the application makes requests using its own identity. This means, API calls are attributed to the application rather than any individuals. Under these circumstances, there is no way to provide more granular access or auditing.

Auditing

All accesses to the NDP Demographics Service are fully audited. Each record includes

calling client identity
end user, if there’s a user-level authentication/authorization
timestamp
requested resource
API response
the response data sent by the service

Client Responsibility

Applications must be able to demonstrate that they capture, maintain and retain full user level audit logs of all API usage. These logs must be retained following the clinical data user activity policies in effect at the time of access.

Endpoints and API Documentation

Find the OpenAPI 3.0 documentation in the NDP Demographics Service Docs .

Returned Data Fields

The following items are typically included in the returned FHIR Patient resource . These are standard fields and are always available in the National CHI Database.

CHI Number
full name
date of birth
current address
gender
GP Practice code, 5 digits related to where the patient is registered
Health Board cyphers: 1 letter
readable Health Board Name, for example N - NHS Grampian*
deceased status
match score, if using Match by Demographics

Health Board Cyphers

A: NHS Ayrshire & Arran
B: NHS Borders
C: NHS Argyll & Clyde (disbanded)
D: Domiciliary
E: Outwith Scotland (NHS England, Ireland or Wales)
F: NHS Fife
G: NHS Greater Glasgow & Clyde
H: NHS Highland
K: National
L: NHS Lanarkshire
N: NHS Grampian
O: Outside U.K
P: Pharmacy
Q: No fixed abode
R: NHS Orkney
S: NHS Lothian
T: NHS Tayside
U: Unknown
V: NHS Forth Valley
W: NHS Western Isles
X: Government locations & NSS properties
Y: NHS Dumfries & Galloway
Z: NHS Shetland

In certain circumstances, the user will have the disbanded board 'C' (NHS Argyll & Clyde) returned. This board has been split between NHS Highland and NHS Greater Glasgow & Clyde.

During the onboarding process, users will receive the mapping of the GP Practice to the new Health Board along with other test data.

Onboarding and Getting Access

If you’re part of NHS Scotland

To start the onboarding process, complete the Technical Triage Form.

After review, we'll issue staging credentials and we’ll be in touch with any required information governance steps.

In reference to question 12 within the Technical Triage Form, you need to attach in your application response:

all information security
governance documentation

If you’re not part of NHS Scotland

You need permission from the CHI Management Board (CHIMB).

To get this, apply using the Health and Social Care Public Benefit and Privacy Panel (HSC-PBPP) application form . To do this:

Go to the 'How to apply ' section.
For more information about the process, go to point 6: ‘HSC-PBPP Guidance for Applicants v4.0 document ’.
To complete the application form, scroll down, go to the third paragraph after point 12 and click on ‘HSC-PBPP Application Form V4.0 ’.

Once you complete the application, send it to nss.committee@nhs.scot stating it’s for approval by CHIMB.

The NDP Demographics Service team does not have the ability to influence or accelerate the board’s decision-making processes.

Support and contact

For any issues, please log a ticket in the NDP Service Desk.

Demographics API Useful Information