{"openapi":"3.0.3","info":{"title":"Digital Staff Passport API","description":"
\n
\n
\n
\n \n \"\"\n \n
\n
\n
\n

This API is retired and not available for use.

\n
\n
\n
\n\n## Overview\nUse this API to notify [Digital Staff Passport (DSP)](https://digital.nhs.uk/services/digital-staff-passport) about changes to\nemployee information in your workforce system.\n\nThese 'event notifications' do not include any actual employee information, they just let DSP know that something has changed.\n\nTo use this API, your system must also provide an API that conforms to the [Digital Staff Passport API standard](https://digital.nhs.uk/developer/api-catalogue/digital-staff-passport-api-standard).\n\nDSP will then use the [Get employee records](https://digital.nhs.uk/developer/api-catalogue/digital-staff-passport-api-standard#get-/organisations/-org-id-/employees/-employee-id-/records) operation\non your API to retrieve the updated employee records.\n\nThe API currently supports the following event types:\n\n| Event type | Source |\n| ------------------- | ---------------------------------------- |\n| DBS check completed | Recruitment system / DBS registered body |\n| eLearning completed | Learning management system |\n\nFor more context, see [Integrating with the Digital Staff Passport](https://digital.nhs.uk/services/digital-staff-passport/integration), specifically:\n- [integration pattern 2](https://digital.nhs.uk/services/digital-staff-passport/integration#pattern-2-outbound-via-online-portal)\n\n## Who can use this API\nYou can only use this API if you are integrating your system with Digital Staff Passport.\n\n## Status\nThis API is [retired](https://digital.nhs.uk/developer/guides-and-documentation/reference-guide#statuses) and not available for use.\n\n## Service level\nThis API is a bronze service, meaning it is operational and supported during business hours.\n\nFor more details, see [service levels](https://digital.nhs.uk/developer/guides-and-documentation/reference-guide#service-levels).\n\n## Technology\nThis API is [RESTful](https://digital.nhs.uk/developer/guides-and-documentation/api-technologies-at-nhs-digital#basic-rest).\n\nIt does not conform to the [FHIR](https://digital.nhs.uk/developer/guides-and-documentation/api-technologies-at-nhs-digital#fhir)\nglobal standard for health care data exchance because it is not a clinical API, it relates to workforce.\nThis has been agreed with the [HL7 FHIR UK Board](https://www.hl7.org.uk/register/about-hl7-uk/management-board-members/).\n\n## Network access\nThis API is available on the internet and also indirectly via HSCN.\n\nFor more details, see [Network access for APIs](https://digital.nhs.uk/developer/guides-and-documentation/network-access-for-apis).\n\n## Security and authorisation\nThis API is [application-restricted](https://digital.nhs.uk/developer/guides-and-documentation/security-and-authorisation#application-restricted-apis),\nmeaning we authenticate the calling application but not the end user.\n\nTo use this API, use the following security pattern:\n- [application-restricted RESTful API - API key authentication](https://digital.nhs.uk/developer/guides-and-documentation/security-and-authorisation/application-restricted-restful-apis-api-key-authentication)\n\n## Errors\nWe use standard HTTP status codes to show whether an API request succeeded or not. They are usually in the range:\n\n* 200 to 299 if it succeeded\n* 400 to 499 if it failed because of a client error by your application\n* 500 to 599 if it failed because of an error on our server\n\nFor details of specific errors, see the 'Response' section for each operation. See our [reference guide](https://digital.nhs.uk/developer/guides-and-documentation/reference-guide#http-status-codes) for more on errors.\n\nYour API-calling application should have a mechanism to automatically try again, for example by giving status information to your end user, before giving up. See our [reference guide](https://digital.nhs.uk/developer/guides-and-documentation/reference-guide#error-handling) for more information about error handling.\n\n## Environments and testing\n\n| Environment | Base URL |\n| ----------------- | ---------------------------------------------------------------------- |\n| Sandbox | Not yet available |\n| Integration test | Not yet available |\n| Production | Not yet available |\n\n### Sandbox testing\nOur [sandbox environment](https://digital.nhs.uk/developer/guides-and-documentation/testing#sandbox-testing):\n* is for early developer testing\n* only covers a limited set of scenarios\n* is stateless, so does not actually persist any updates\n* is open access, so does not allow you to test authorisation\n\n### Integration testing\nOur [integration test environment](https://digital.nhs.uk/developer/guides-and-documentation/testing#integration-testing):\n* is for formal integration testing\n* is stateful, so persists updates\n* includes authorisation\n\nFor more details, see [Digital Staff Passport integration testing](https://digital.nhs.uk/services/digital-staff-passport/integration/testing).\n\n## Onboarding\nBefore 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.\n\nThis includes, for example, making sure we have processes in place to deal with live incidents.\n\nFor more details, see [Digital Staff Passport onboarding and assurance](https://digital.nhs.uk/services/digital-staff-passport/integration/onboarding-and-assurance).\n","contact":{"name":"API Management Support","url":"https://digital.nhs.uk/developer/help-and-support","email":"api.management@nhs.net"},"version":"v1.0.450-alpha"},"servers":[{"url":"/"}],"paths":{"/events":{"post":{"summary":"Publish an event","description":"Use this operation to notify DSP about a change to employee information in your workforce system.\n\nThe following event types are supported:\n\n| Event type | Event type ID | Source |\n| -------------------------- | ------------------------------ | ---------------------------------------- |\n| DBS check completed | `employee-dbs-check-completed` | Recruitment system / DBS registered body |\n| eLearning course completed | `employee-elearning-completed` | Learning management system |\n","operationId":"publish-event","parameters":[{"$ref":"#/components/parameters/ApiKey"}],"requestBody":{"content":{"application/cloudevents+json":{"schema":{"$ref":"#/components/schemas/Event"},"example":{"specversion":"1.0","id":"236a1d4a-5d69-4fa9-9c7f-e72bf505aa5b","source":"com.example-organisation.example-workforce-system","type":"employee-dbs-check-completed","time":"2020-06-01T13:00:00Z","subject":"12345","filtering":{"organisation":"RHQ"},"dataref":"https://api.example-workforce-system.example-organisation.com/dsp-api/organisations/RHQ/employees/12345/records"}}},"required":true},"responses":{"200":{"description":"Success - the event has been accepted.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EventResponse"},"example":{"id":"236a1d4a-5d69-4fa9-9c7f-e72bf505aa5b"}}}},"4XX":{"description":"An error occurred as follows:\n\n| HTTP status | Error code | Description |\n| ----------- | ------------------- | - |\n| 400 | invalid | Invalid data in request body, for example, missing mandatory field or invalid date/time format. |\n| 401 | invalid-credentials | Missing or invalid API key. |\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"resourceType":"OperationOutcome","issue":[{"severity":"error","code":"invalid","details":{"text":"Invalid format for time query parameter - must be as per RFC 3339."}}]}}}}},"deprecated":false}}},"components":{"schemas":{"Event":{"required":["specversion","id","source","type","time","subject","filtering","dataref"],"type":"object","properties":{"specversion":{"enum":["1.0"],"type":"string","description":"The version of the [CloudEvents](https://cloudevents.io/) specification which the event uses.","example":1.0},"id":{"type":"string","description":"A unique identifier for the event – a GUID.","example":"236a1d4a-5d69-4fa9-9c7f-e72bf505aa5b"},"source":{"type":"string","description":"The system that produced the event, expressed as a URI.","format":"uri-reference","example":"com.example-organisation.example-workforce-system"},"type":{"enum":["employee-dbs-check-completed","employee-elearning-completed"],"type":"string","description":"The type of event.","example":"employee-dbs-check-completed"},"time":{"type":"string","description":"Timestamp for when the event occurred, formatted as per [RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339).","format":"date-time","example":"2020-06-01 13:00:00+00:00"},"subject":{"type":"string","description":"The system-specific unique identifier for the employee who is the subject of the event.\nThis is the same as the `employee-id` field used in the [Digital Staff Passport API standard](https://digital.nhs.uk/developer/api-catalogue/digital-staff-passport-api-standard).\n","example":12345},"filtering":{"required":["organisation"],"type":"object","properties":{"organisation":{"type":"string","description":"ODS code for the employing organisation.","example":"RHQ"}},"description":"List of filter criteria."},"dataref":{"type":"string","description":"URL for the endpoint on the publishing service that can be used to retrieve the full information about the event or subject record.\n\nMust be an implementation of the [Get employee records operation](https://digital.nhs.uk/developer/api-catalogue/digital-staff-passport-api-standard#get-/organisations/-org-id-/employees/-employee-id-/records)\nfrom the Digital Staff Passport API standard.\n\nThe `employee-id` field in the URI must match the `subject` field for the event.\n\nThe `org-id` field in the URI must match the `filtering.organisation` field for the event.\n","format":"uri","example":"https://api.example-workforce-system.example-organisation.com/dsp-api/organisations/RHQ/employees/12345/records"}}},"EventResponse":{"required":["id"],"type":"object","properties":{"id":{"type":"string","description":"The unique identifier for the event, as supplied in the request.","example":"236a1d4a-5d69-4fa9-9c7f-e72bf505aa5b"}}},"Error":{"required":["resourceType","issue"],"type":"object","properties":{"resourceType":{"enum":["OperationOutcome"],"type":"string","description":"The resource type."},"issue":{"minItems":1,"type":"array","items":{"required":["severity","code"],"type":"object","properties":{"severity":{"enum":["fatal","error","warning","information"],"type":"string","description":"Issue severity, as per [https://hl7.org/fhir/R4/valueset-issue-severity.html](https://hl7.org/fhir/R4/valueset-issue-severity.html)."},"code":{"type":"string","description":"Error or warning code, as per [https://hl7.org/fhir/R4/valueset-issue-type.html](https://hl7.org/fhir/R4/valueset-issue-type.html).","example":"invalid"},"details":{"required":["text"],"type":"object","properties":{"text":{"type":"string","description":"A text description of the error or warning.","example":"Invalid format for time query parameter - must be as per RFC 3339."}},"description":"Additional details about the error or warning."}}},"description":"List of issues that have occurred. Usually there will be just one."}}}},"parameters":{"ApiKey":{"name":"apikey","in":"header","description":"The calling system's API key.\nFor details, see [Application-restricted RESTful API - API key authentication](https://digital.nhs.uk/developer/guides-and-documentation/security-and-authorisation/application-restricted-restful-apis-api-key-authentication).\n","required":true,"deprecated":false,"allowEmptyValue":false,"explode":false,"allowReserved":false,"schema":{"type":"string","example":"9Y8Y1CcNxFlsZjGSBdJmExfZcjGkGOac"}},"BearerAuthorization":{"name":"Authorization","in":"header","description":"The calling system's access token, which must be an OAuth 2.0 bearer token.\nFor details, see [Authorisation using OAuth 2.0 private key JWT](https://digital.nhs.uk/developer/api-catalogue/digital-staff-passport-api-standard/authorisation-using-oauth-2.0-private-key-jwt).\n","required":true,"deprecated":false,"allowEmptyValue":false,"explode":false,"allowReserved":false,"schema":{"type":"string","format":"^Bearer\\ [[:ascii:]]+$","example":"Bearer g1112R_ccQ1Ebbb4gtHBP1aaaNM"}},"OrganisationId":{"name":"org-id","in":"path","description":"The ODS code for the employing organisation.","required":true,"deprecated":false,"allowEmptyValue":false,"explode":false,"allowReserved":false,"schema":{"type":"string"},"example":"RHQ"},"EmployeeId":{"name":"employee-id","in":"path","description":"The employee's primary unique identifier, as used by the external system.","required":true,"deprecated":false,"allowEmptyValue":false,"explode":false,"allowReserved":false,"schema":{"type":"string"},"example":"12345"}}},"x-spec-publication":{"try-this-api":{"disabled":true}}}