Integrating with the Digital Staff Passport

The NHS Digital Staff Passport (DSP) needs to be integrated with a variety of external systems so that employees can share their employment information between NHS organisations.

The integration landscape is complex because:

• within each NHS employer, there are different systems for different types of information
• different NHS employers use different systems
• different systems use different integration patterns

This page explains the various integration patterns and provides guidance for teams that need to integrate an external system with DSP.

Credentials are the different types of information that can be shared between NHS employers via DSP. This includes things like:

• personal details
• pre-employment checks, including identity checks
• core skills, achieved through training
• occupational health information, such as vaccinations

Credentials are issued by a trusted body such as NHS England or a specific NHS trust.

Read more about credentials.

NHS employers use a variety of IT systems to provide workforce-related capabilities like:

• recruitment, including vacancies, applications and pre-employment checks
• payroll
• learning management, including core skills training
• occupational health, including vaccinations

We call these 'authoritative systems'. They are the master systems for the various credentials that can be transferred via DSP.

Some authoritative systems are national - available to all NHS employers in England. Some of the important ones are as follows:

These national systems are intended to meet the majority of, if not all, workforce-related needs. However, some NHS employers choose to use alternatives for some use cases. Usually these are commercial systems provided by third-party suppliers, including:

• third-party recruitment systems
• third-party learning management systems
• third-party occupational health systems

The result is that different NHS employers use different combinations of authoritative systems. To succeed, DSP needs to be able to integrate with as many of them as possible.

When an employee wants to move from one NHS employer to another, they need to gather their employment information from their current employer into their digital wallet.

This information - their credentials - must be retrieved from the appropriate workforce management systems for their current employer. We call this 'outbound information flow'.

Once the employee has gathered their credentials in their digital wallet, they can share it with their new employer.

This information must be sent to the appropriate authoritative systems for their new employer. We call this 'inbound information flow'.

There is no national identifier for NHS employees. Doctors registered with the General Medical Council have a unique GMC number, but not all employees are doctors.

As a result, each IT system in each NHS employer has a separate identifier for each employee. For example, the employee identifier in ESR is called the 'person ID', but this is not shared across employers.

To share information between NHS employers, and across different systems within an employer, employee records must be 'matched' between systems. Every integration of an external system with DSP needs to consider how to achieve this.

DSP consists of two key components:

• DSP online portal
• DSP digital wallet

The DSP online portal is where employers and employees perform various actions, such as signing up and managing their information.

There are separate areas of the online portal for employers and employees. We sometimes call these the 'employer portal' and the 'employee portal', although they share the same underlying database.

Importantly, there is a separate 'instance' of the DSP online portal for each employer, with data from each employer stored separately.

The DSP digital wallet is an app on the employee’s phone that securely stores the employee’s credentials, using a technology known as verifiable credentials. Currently we use Microsoft Authenticator for this.

Importantly, the only way to share information between employers is via the employee’s digital wallet. The employee must download credentials from their old employer and share them with their new employer. This puts the employee very much in control of their own information.

There are different ways to integrate external systems with DSP. We call these ‘integration patterns’. Different patterns are suitable for different external systems, depending on their characteristics.

The following sections summarise the various patterns and when each one should be used.

In this pattern, the employee downloads their credentials directly into their digital wallet from the authoritative system, bypassing the DSP online portal.

Before they do this, they must first upload their identity credential to the authoritative system to strongly authenticate themselves and ensure the verification trail.

When to use this pattern

This pattern is suitable for authoritative systems that have an employee portal that employees sign in to directly.

In this pattern, the authoritative system exposes a RESTful API that the DSP online portal calls to retrieve an employee's relevant information, using the Digital Staff Passport API standard.

An HR user within the NHS employer uses the DSP online portal to:

• match the employee record between DSP and the authoritative system
• retrieve the employee's information from the authoritative system
• provide the information as a credential with the employee

Then, the employee uses the DSP online portal to download the credential to their digital passport on their phone.

Automated updates

If new employee information arrives, or is created, in the authoritative system, it can let DSP know using a 'pro-active' notification via the Digital Staff Passport API.

If the information is for an employee of interest, DSP can retrieve it from the authoritative system and provide it to the employee as a credential.

When to use this pattern

This pattern is appropriate for authoritative systems that don't have an employee portal that employees sign in to directly.

In this pattern, the authoritative system is integrated with ESR and the employee's information flows into DSP via the ESR RESTful API.

Documentation for integrating authoritative systems with ESR is available in the Interfaces section of the ESR document library.

Automated updates

If new employee information arrives, or is created, in the authoritative system, it will flow into DSP via ESR.

DSP can then provide it to the employee as a credential.

When to use this pattern

This pattern is suitable for authoritative systems that are already integrated with ESR, but it is not a preferred pattern – we prefer interfaces direct to DSP.

How to use this pattern

Contact us for further guidance.

In this pattern, the authoritative system exposes a RESTful API that the DSP online portal calls to send an employee's relevant information, using the Digital Staff Passport API standard.

Prior to this, the employee must have uploaded their credentials from their digital wallet to the DSP online portal.

An HR user within the NHS employer then uses the DSP online portal to:

• accept the employee's credentials
• match the employee record between DSP and the authoritative system
• send the employee's information to the authoritative system

When to use this pattern

This is currently the only inbound pattern – use it for all inbound integrations with DSP.

The following table lists the authoritative systems that are either already integrated with DSP or are actively in progress.

To integrate an authoritative system with DSP, follow the steps below.

1. Engagement

During the pilot phase, we're working with a limited number of external system providers. If we haven't done so already, we'll be in touch with you about joining the pilot.

Once the pilot is complete, we hope to allow other providers to integrate with DSP. To express an interest, contact us and tell us about your system and why you want to integrate with DSP.

2. Design and build

Working with us, decide which integration patterns to use, and build those patterns into your system.

We'll also make any changes needed to DSP to support the integration.

3. Testing

As well as your own system testing, we’ll need to do:

• integration testing
• user acceptance testing

You’ll need to deploy your system to a test environment for this and set up appropriate test data.

For more details, see Digital Staff Passport integration testing.

4. Onboarding and assurance

Before your integration goes live, we’ll need to complete a number of assurance checks for both your organisation and your system. We call this onboarding.

This includes, for example, making sure we have processes in place to deal with live incidents.

For more details, see Digital Staff Passport onboarding and assurance.

5. Live pilot

We'll probably want to pilot your integration in a small number of NHS employers before rolling it out more widely.

6. Full roll-out

Once we've seen the integration working in a live pilot, you’ll be able to roll it out to all NHS employers who are using both DSP and your system.

Incidents

To raise a live service incident, use the Help form for current NHS Digital Staff Passport suppliers.

Enquiries

For any questions about integrating with DSP, you can:

1. ask your question or look for an existing answer in the Digital Staff Passport category on the NHS England developer community
2. contact us