Digital Staff Passport event
Let Digital Staff Passport know about new or updated employee information in your workforce system via our Multicast Notification Service.
Overview
Use this integration to let Digital Staff Passport (DSP) know about new or updated employee information in an external workforce system via our Multicast Notification Service (MNS) API.
External workforce systems might be:
- recruitment systems
- learning management systems
- occupational health systems
This integration uses a publish-subscribe model, as follows:
- DSP subscribes to MNS to receive event notifications for specific employees.
- External workforce systems publish events when employee information is added or updated in their system. These events do not contain any employee information, they are simply a notification that something has been added or updated for a given employee in a given system.
- MNS forwards notifications of interest on to DSP, based on DSP’s subscriptions.
- DSP uses the Digital Staff Passport API standard to retrieve the new or updated employee information from the external workforce system.
For more context, see Integrating with the Digital Staff Passport, specifically integration pattern 2.
Who can use this integration
You can only use this integration if you are integrating an external workforce system with the Digital Staff Passport.
Status
This integration is in development, meaning:
- we have published this specification
- the integration is not yet available for testing in the integration environment
we might make breaking changes based on developer feedback
Publishing events
To publish an event, use the MNS Publish an event operation.
Use the following schema for the JSON payload:
|
specversion: string required |
The version of the CloudEvents specification that the event uses. Allowed values: 1.0 |
|
id: string required |
A unique identifier for the event – a GUID. |
|
source: uri-reference Required |
The system that produced the event, expressed as a URI. |
|
type: string Required |
The type of event. Allowed values:
|
|
time: date-time Required |
Timestamp for when the event occurred, formatted as per RFC 3339. |
|
subject: string |
The system-specific unique identifier for the employee who is the subject of the event. This is the same as the employee-id field used in the Digital Staff Passport API standard. |
|
filtering: object |
List of filter criteria. |
|
organisation: string |
ODS code for the employing organisation. |
|
dataref: uri required |
URL for the endpoint on the publishing service that can be used to retrieve the full information about the event or subject record. Must be an implementation of the Get employee records operation from the Digital Staff Passport API standard. The employee-id field in the URI must match the subject field for the event. The org-id field in the URI must match the filtering.organisation field for the event. |
Here's an example payload:
{
"specversion": "1.0",
"id": "236a1d4a-5d69-4fa9-9c7f-e72bf505aa5b",
"source": "com.acme.workforce-magic",
"type": "employee-dbs-check-completed",
"time": "2020-06-01T13:00:00Z",
"subject": "12345",
"filtering": {
"organisation": "RHQ",
},
"dataref": "https://api.workforce-magic.acme.com/dsp-api/organisations/RHQ/employees/12345/records"
}
Organisation level security
To ensure that events are not shared across organisations, the credentials used to access the Multicast Notification Service will be associated with a specific organisation ODS code.
Each external workforce system will therefore need a separate set of credentials for each organisation.
Subscribing to and receiving events
Currently, only Digital Staff Passport is allowed to subscribe to and receive events.
Last edited: 30 September 2026 9:45 am