From 6caf1746fe076982b3895803df60e07e42b6f5ea Mon Sep 17 00:00:00 2001 From: Tony Heap <40767455+tonyheap@users.noreply.github.com> Date: Wed, 11 Mar 2026 12:50:48 +0000 Subject: [PATCH 01/47] Update healthcare-worker-api.yaml --- specification/healthcare-worker-api.yaml | 8 ++------ 1 file changed, 2 insertions(+), 6 deletions(-) diff --git a/specification/healthcare-worker-api.yaml b/specification/healthcare-worker-api.yaml index f4203c1d..3510702a 100644 --- a/specification/healthcare-worker-api.yaml +++ b/specification/healthcare-worker-api.yaml @@ -25,7 +25,8 @@ info: ## Related APIs The following APIs are related to this one: - * [Healthcare Worker - FHIR API](https://digital.nhs.uk/developer/api-catalogue/healthcare-fhir-api) + - [Spine Directory Service - LDAP API](https://digital.nhs.uk/developer/api-catalogue/spine-directory-service-ldap) - The legacy API for accessing healthcare worker information in CIS. Only available on HSCN and being considered for deprecation. + - [Organisation Data Terminology - FHIR API](https://digital.nhs.uk/developer/api-catalogue/organisation-data-terminology) - Get organisation information from the Organisation Data Service (ODS), including some limited information on some prescribing staff at each organisation. ## API status and roadmap This API is [in production, beta](https://digital.nhs.uk/developer/guides-and-documentation/reference-guide#statuses). @@ -95,11 +96,6 @@ info: - used to confirm you are ready for production - includes application authentication - ## Related APIs - The following APIs are related to this one:- [Spine Directory Service - LDAP API](https://digital.nhs.uk/developer/api-catalogue/spine-directory-service-ldap) - Access details of organisations, people and systems registered in the Spine Directory Service (SDS) using our LDAP API. This API is only available on HSCN, doesn't use the FHIR standard and is being considered for deprecation. - - [Organisation Data Terminology - FHIR API](https://digital.nhs.uk/developer/api-catalogue/organisation-data-terminology) - Access an organisation-based dataset from the Organisation Data Service (ODS), including some limited information on some prescribing staff at each organisation. - - [Organisation Data Service - FHIR API](https://digital.nhs.uk/developer/api-catalogue/organisation-data-service-fhir) - Access a reduced organisation-based dataset from the Organisation Data Service (ODS). An older, limited alternative to ODS Terminology API and soon to be deprecated. - ## Onboarding You need to get your software approved by us before it can go live with this API. We call this onboarding. The onboarding process can sometimes be quite long, so it's worth planning well ahead. From 7b9a2df2b7db3483e9762f9726caea0d88d2f3d3 Mon Sep 17 00:00:00 2001 From: Tony Heap <40767455+tonyheap@users.noreply.github.com> Date: Wed, 11 Mar 2026 13:01:24 +0000 Subject: [PATCH 02/47] Update healthcare-worker-api.yaml Changes related to HCW-320 (order sections of the specification as per standard). --- specification/healthcare-worker-api.yaml | 22 ++++++++++------------ 1 file changed, 10 insertions(+), 12 deletions(-) diff --git a/specification/healthcare-worker-api.yaml b/specification/healthcare-worker-api.yaml index 3510702a..1a1b0eb4 100644 --- a/specification/healthcare-worker-api.yaml +++ b/specification/healthcare-worker-api.yaml @@ -64,16 +64,22 @@ info: * [Application-restricted RESTful APIs - signed JWT authentication](https://digital.nhs.uk/developer/guides-and-documentation/security-and-authorisation/application-restricted-restful-apis-signed-jwt-authentication) - ## Postman Collection - See https://github.com/NHSDigital/healthcare-worker-api/tree/develop/postman for an export of our postman collection. The readme in that directory explains how to set it up and send the requests. + ## Errors + We use standard HTTP status codes to show whether an API request succeeded or not. They are usually in the range: - ## Open source + * 200 to 299 if it succeeded, including code 202 if it was accepted by an API that needs to wait for further action + * 400 to 499 if it failed because of a client error by your application + * 500 to 599 if it failed because of an error on our server + + Errors specific to each API are shown in the Endpoints section, under Response. See our [reference guide](https://digital.nhs.uk/developer/guides-and-documentation/reference-guide#http-status-codes) for more on errors. + ## Open source You might find the following [open source](https://digital.nhs.uk/developer/guides-and-documentation/reference-guide#open-source) resources useful: | Resource | Description | Links | | ----------------------- | ------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- | - | Project codebase | The full Healthcare Worker codebase is open source in GitHub. | [Github](https://github.com/NHSDigital/healthcare-worker-api) | + | Project codebase | The full Healthcare Worker codebase is open source in GitHub. | [GitHub](https://github.com/NHSDigital/healthcare-worker-api) | + | Postman collection | Export of our Postman collection for use with the API. | [GitHub](https://github.com/NHSDigital/healthcare-worker-api/tree/develop/postman) | FHIR libraries and SDKs | Various open source libraries for integrating with FHIR APIs. | [FHIR libraries and SDKs](https://digital.nhs.uk/developer/guides-and-documentation/api-technologies-at-nhs-digital#fhir-libraries-and-sdks) | ## Environments and testing @@ -107,14 +113,6 @@ info: To get started, sign in or create a [developer account](https://onboarding.prod.api.platform.nhs.uk/), then select 'product onboarding'. - ## Errors - We use standard HTTP status codes to show whether an API request succeeded or not. They are usually in the range: - - * 200 to 299 if it succeeded, including code 202 if it was accepted by an API that needs to wait for further action - * 400 to 499 if it failed because of a client error by your application - * 500 to 599 if it failed because of an error on our server - - Errors specific to each API are shown in the Endpoints section, under Response. See our [reference guide](https://digital.nhs.uk/developer/guides-and-documentation/reference-guide#http-status-codes) for more on errors. contact: name: Spine Directory Service API Support url: https://digital.nhs.uk/developer/help-and-support From 559ffadefab67ab63aa04dcef743ad3de9af69c9 Mon Sep 17 00:00:00 2001 From: Tony Heap <40767455+tonyheap@users.noreply.github.com> Date: Wed, 11 Mar 2026 13:39:04 +0000 Subject: [PATCH 03/47] Update healthcare-worker-api.yaml --- specification/healthcare-worker-api.yaml | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/specification/healthcare-worker-api.yaml b/specification/healthcare-worker-api.yaml index 1a1b0eb4..60be896b 100644 --- a/specification/healthcare-worker-api.yaml +++ b/specification/healthcare-worker-api.yaml @@ -31,9 +31,9 @@ info: ## API status and roadmap This API is [in production, beta](https://digital.nhs.uk/developer/guides-and-documentation/reference-guide#statuses). - To see our roadmap, or to suggest, comment or vote on features for this API, see our [interactive product backlog](https://nhs-digital-api-management.featureupvote.com/suggestions/204411/healthcare-professionals-api). - - If you have any other queries, [contact us](https://digital.nhs.uk/developer/help-and-support). + For details of future changes, see the [Care Identity Service roadmap](https://digital.nhs.uk/services/care-identity-service/roadmap). + + If you have any other queries, [contact us](https://digital.nhs.uk/developer/help-and-support). ## Service level This API is a silver service during private beta, meaning it is operational 24 hours a day, 7 days a week but only supported during business hours (8am to 6pm), Monday to Friday excluding bank holidays. From 32d774629473dc25a0ccc3b43e7a0518953d8239 Mon Sep 17 00:00:00 2001 From: Tony Heap <40767455+tonyheap@users.noreply.github.com> Date: Wed, 11 Mar 2026 14:06:53 +0000 Subject: [PATCH 04/47] Update healthcare-worker-api.yaml --- specification/healthcare-worker-api.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/specification/healthcare-worker-api.yaml b/specification/healthcare-worker-api.yaml index 60be896b..aba20dfa 100644 --- a/specification/healthcare-worker-api.yaml +++ b/specification/healthcare-worker-api.yaml @@ -36,7 +36,7 @@ info: If you have any other queries, [contact us](https://digital.nhs.uk/developer/help-and-support). ## Service level - This API is a silver service during private beta, meaning it is operational 24 hours a day, 7 days a week but only supported during business hours (8am to 6pm), Monday to Friday excluding bank holidays. + This API is a silver service during beta, meaning it is operational 24 hours a day, 7 days a week but only supported during business hours (8am to 6pm), Monday to Friday excluding bank holidays. For more details, see [service levels](https://digital.nhs.uk/developer/guides-and-documentation/reference-guide#service-levels). From 00b390c2ded98e815a122ad7c5b1db76b9eb32b4 Mon Sep 17 00:00:00 2001 From: Tony Heap <40767455+tonyheap@users.noreply.github.com> Date: Wed, 11 Mar 2026 14:08:36 +0000 Subject: [PATCH 05/47] Update healthcare-worker-api.yaml --- specification/healthcare-worker-api.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/specification/healthcare-worker-api.yaml b/specification/healthcare-worker-api.yaml index aba20dfa..bebe3c72 100644 --- a/specification/healthcare-worker-api.yaml +++ b/specification/healthcare-worker-api.yaml @@ -32,7 +32,7 @@ info: This API is [in production, beta](https://digital.nhs.uk/developer/guides-and-documentation/reference-guide#statuses). For details of future changes, see the [Care Identity Service roadmap](https://digital.nhs.uk/services/care-identity-service/roadmap). - + If you have any other queries, [contact us](https://digital.nhs.uk/developer/help-and-support). ## Service level From b05b27c6fa7d11da5c9f3a7aaf0cf2a059024616 Mon Sep 17 00:00:00 2001 From: Tony Heap <40767455+tonyheap@users.noreply.github.com> Date: Wed, 11 Mar 2026 14:24:57 +0000 Subject: [PATCH 06/47] Update healthcare-worker-api.yaml --- specification/healthcare-worker-api.yaml | 19 ++++++++++++++++++- 1 file changed, 18 insertions(+), 1 deletion(-) diff --git a/specification/healthcare-worker-api.yaml b/specification/healthcare-worker-api.yaml index bebe3c72..ef41419a 100644 --- a/specification/healthcare-worker-api.yaml +++ b/specification/healthcare-worker-api.yaml @@ -7,10 +7,12 @@ info: Use this API to access details of healthcare workers registered in the [Care Identity Service (CIS)](https://digital.nhs.uk/services/care-identity-service) directory. You can: - - get basic professional details of any healthcare worker with an active care identity, using their unique ID (this is sometimes known as SDS user ID or Smartcard ID). + - get basic professional details of any healthcare worker with an active care identity, using their unique ID (this is sometimes known as SDS user ID or Smartcard ID) + - get details of the [national RBAC](https://digital.nhs.uk/services/care-identity-service/applications-and-services/cis2-authentication/integrate/design-and-build/national-rbac-for-developers) roles that have been assigned to them by their Registration Authority You cannot currently use this API to: - search by professional codes, such as GMC or RNC code + - get details of 'directly assigned' activities associated with the healthcare worker's role profiles The strategic aim of the API is to allow systems to search, retrieve and display healthcare worker data from over 1.4 million NHS employees with a health care profile. The objective is to increase data efficiency, business logic and improve interoperability within the business. @@ -18,6 +20,21 @@ info: This strategic solution will allow internal and 3rd party systems to access and share information more reliably, flexibly and efficiently while benefiting from improved network and bandwidth capacity, financial savings and easier and smoother access to clinical systems. + ### National RBAC and directly assigned activities + [National RBAC](https://digital.nhs.uk/services/care-identity-service/applications-and-services/cis2-authentication/integrate/design-and-build/national-rbac-for-developers) is the method CIS uses to manage user permissions. + + In national RBAC: + - users are assigned 'role profiles' + - each role profile is linked to a single 'role' + - each role is linked to zero or more 'activities' - the things the user is allowed to do + - a role profile can also have 'directly assigned' activities + + So the total set of activities for a given role profile includes: + - the activities that can be inferred from the role + - the directly assigned activities + + Currently, this API only provides details of the users' roles, not their directly assigned activities. We plan to add included activities in a future release. + ## Who can use this API This API can only be used where there is a legal basis to do so. Make sure you have a valid use case before you go too far with your development. From 4517984d7e456e6a7118a24f96cf9fcd85f915b5 Mon Sep 17 00:00:00 2001 From: Tony Heap <40767455+tonyheap@users.noreply.github.com> Date: Wed, 11 Mar 2026 14:32:47 +0000 Subject: [PATCH 07/47] Update healthcare-worker-api.yaml --- specification/healthcare-worker-api.yaml | 4 ---- 1 file changed, 4 deletions(-) diff --git a/specification/healthcare-worker-api.yaml b/specification/healthcare-worker-api.yaml index ef41419a..8d58f564 100644 --- a/specification/healthcare-worker-api.yaml +++ b/specification/healthcare-worker-api.yaml @@ -122,10 +122,6 @@ info: ## Onboarding You need to get your software approved by us before it can go live with this API. We call this onboarding. The onboarding process can sometimes be quite long, so it's worth planning well ahead. - As part of this process, you need to demonstrate that you can manage risks and that your software conforms - technically with the requirements for this API. This might impact the design of your software. For details, see - [Onboarding support information](https://digital.nhs.uk/developer/api-catalogue/child-protection-information-sharing-hl7-v3/onboarding-support-information). - To understand how our online digital onboarding process works, see [digital onboarding](https://digital.nhs.uk/developer/guides-and-documentation/digital-onboarding). To get started, sign in or create a [developer account](https://onboarding.prod.api.platform.nhs.uk/), then select 'product onboarding'. From d851cfa4324b192ddd513f6bc6bc7679db2c1b0c Mon Sep 17 00:00:00 2001 From: Tony Heap <40767455+tonyheap@users.noreply.github.com> Date: Wed, 11 Mar 2026 14:35:59 +0000 Subject: [PATCH 08/47] Update healthcare-worker-api.yaml --- specification/healthcare-worker-api.yaml | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/specification/healthcare-worker-api.yaml b/specification/healthcare-worker-api.yaml index 8d58f564..9f183902 100644 --- a/specification/healthcare-worker-api.yaml +++ b/specification/healthcare-worker-api.yaml @@ -93,11 +93,11 @@ info: ## Open source You might find the following [open source](https://digital.nhs.uk/developer/guides-and-documentation/reference-guide#open-source) resources useful: - | Resource | Description | Links | - | ----------------------- | ------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- | - | Project codebase | The full Healthcare Worker codebase is open source in GitHub. | [GitHub](https://github.com/NHSDigital/healthcare-worker-api) | - | Postman collection | Export of our Postman collection for use with the API. | [GitHub](https://github.com/NHSDigital/healthcare-worker-api/tree/develop/postman) - | FHIR libraries and SDKs | Various open source libraries for integrating with FHIR APIs. | [FHIR libraries and SDKs](https://digital.nhs.uk/developer/guides-and-documentation/api-technologies-at-nhs-digital#fhir-libraries-and-sdks) | + | Resource | Description | Links | + | ----------------------- | ----------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- | + | API source code | The full Healthcare Worker API codebase is open source in GitHub. | [GitHub](https://github.com/NHSDigital/healthcare-worker-api) | + | Postman collection | Export of our Postman collection for use with the API. | [GitHub](https://github.com/NHSDigital/healthcare-worker-api/tree/develop/postman) + | FHIR libraries and SDKs | Various open source libraries for integrating with FHIR APIs. | [FHIR libraries and SDKs](https://digital.nhs.uk/developer/guides-and-documentation/api-technologies-at-nhs-digital#fhir-libraries-and-sdks) | ## Environments and testing | Environment | Base URL From 96e683d5cff3092361232ed6721e7b63ef0a04f6 Mon Sep 17 00:00:00 2001 From: Tony Heap <40767455+tonyheap@users.noreply.github.com> Date: Mon, 16 Mar 2026 09:34:48 +0000 Subject: [PATCH 09/47] Update healthcare-worker-api.yaml --- specification/healthcare-worker-api.yaml | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/specification/healthcare-worker-api.yaml b/specification/healthcare-worker-api.yaml index 3158fbf1..fb4b7ee3 100644 --- a/specification/healthcare-worker-api.yaml +++ b/specification/healthcare-worker-api.yaml @@ -12,7 +12,7 @@ info: You cannot currently use this API to: - search by professional codes, such as GMC or RNC code - - get details of 'directly assigned' activities associated with the healthcare worker's role profiles + - get details of 'directly assigned' activities associated with the healthcare worker's role profiles (see below) The strategic aim of the API is to allow systems to search, retrieve and display healthcare worker data from over 1.4 million NHS employees with a health care profile. The objective is to increase data efficiency, business logic and improve interoperability within the business. @@ -20,7 +20,7 @@ info: This strategic solution will allow internal and 3rd party systems to access and share information more reliably, flexibly and efficiently while benefiting from improved network and bandwidth capacity, financial savings and easier and smoother access to clinical systems. - ### National RBAC and directly assigned activities + ### Directly assigned activities [National RBAC](https://digital.nhs.uk/services/care-identity-service/applications-and-services/cis2-authentication/integrate/design-and-build/national-rbac-for-developers) is the method CIS uses to manage user permissions. In national RBAC: @@ -33,7 +33,7 @@ info: - the activities that can be inferred from the role - the directly assigned activities - Currently, this API only provides details of the users' roles, not their directly assigned activities. We plan to add included activities in a future release. + Currently, this API only provides details of the users' roles, not their directly assigned activities. We plan to add directly assigned activities in a future release. ## Who can use this API This API can only be used where there is a legal basis to do so. Make sure you have a valid use case before you go too far with your development. From 6fe7fff5938c0538b9d856e069f5de2e77e593a3 Mon Sep 17 00:00:00 2001 From: Tony Heap <40767455+tonyheap@users.noreply.github.com> Date: Mon, 16 Mar 2026 10:49:19 +0000 Subject: [PATCH 10/47] Update healthcare-worker-api.yaml --- specification/healthcare-worker-api.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/specification/healthcare-worker-api.yaml b/specification/healthcare-worker-api.yaml index fb4b7ee3..af64e1fd 100644 --- a/specification/healthcare-worker-api.yaml +++ b/specification/healthcare-worker-api.yaml @@ -46,7 +46,7 @@ info: - [Organisation Data Terminology - FHIR API](https://digital.nhs.uk/developer/api-catalogue/organisation-data-terminology) - Get organisation information from the Organisation Data Service (ODS), including some limited information on some prescribing staff at each organisation. ## API status and roadmap - This API is [in production, beta](https://digital.nhs.uk/developer/guides-and-documentation/reference-guide#statuses). + This API is in [beta](https://digital.nhs.uk/developer/guides-and-documentation/reference-guide#statuses). For details of future changes, see the [Care Identity Service roadmap](https://digital.nhs.uk/services/care-identity-service/roadmap). From 5cd2be7e7046caad9c95f01a2724890cc16fb56d Mon Sep 17 00:00:00 2001 From: jolyonbrownnhs Date: Mon, 16 Mar 2026 10:51:08 +0000 Subject: [PATCH 11/47] HCW-319 fix grype related scanning errors --- .github/workflows/stage-1-commit.yaml | 2 +- .tool-versions | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/.github/workflows/stage-1-commit.yaml b/.github/workflows/stage-1-commit.yaml index c4a90234..b3f73455 100644 --- a/.github/workflows/stage-1-commit.yaml +++ b/.github/workflows/stage-1-commit.yaml @@ -120,7 +120,7 @@ jobs: permissions: id-token: write contents: read - timeout-minutes: 2 + timeout-minutes: 5 steps: - name: "Checkout code" uses: actions/checkout@v4 diff --git a/.tool-versions b/.tool-versions index ea517f08..6c23ca57 100644 --- a/.tool-versions +++ b/.tool-versions @@ -8,7 +8,7 @@ python 3.12 # The section below is reserved for Docker image versions. # TODO: Move this section - consider using a different file for the repository template dependencies. -# docker/ghcr.io/anchore/grype v0.69.1@sha256:d41fcb371d0af59f311e72123dff46900ebd6d0482391b5a830853ee4f9d1a76 # SEE: https://github.com/anchore/grype/pkgs/container/grype +# docker/ghcr.io/anchore/grype v0.109.1@sha256:7d1d08f2d17a9080a23d46548b23df8fc369c9efbf0bb8cf7901dfb2eabfa41f # SEE: https://github.com/anchore/grype/pkgs/container/grype # docker/ghcr.io/anchore/syft v0.92.0@sha256:63c60f0a21efb13e80aa1359ab243e49213b6cc2d7e0f8179da38e6913b997e0 # SEE: https://github.com/anchore/syft/pkgs/container/syft # docker/ghcr.io/gitleaks/gitleaks v8.18.0@sha256:fd2b5cab12b563d2cc538b14631764a1c25577780e3b7dba71657d58da45d9d9 # SEE: https://github.com/gitleaks/gitleaks/pkgs/container/gitleaks # docker/ghcr.io/igorshubovych/markdownlint-cli v0.37.0@sha256:fb3e79946fce78e1cde84d6798c6c2a55f2de11fc16606a40d49411e281d950d # SEE: https://github.com/igorshubovych/markdownlint-cli/pkgs/container/markdownlint-cli From 6b9d87fc180bcd35e110430e1b8117d8776db358 Mon Sep 17 00:00:00 2001 From: Tony Heap <40767455+tonyheap@users.noreply.github.com> Date: Mon, 16 Mar 2026 11:05:48 +0000 Subject: [PATCH 12/47] Update healthcare-worker-api.yaml --- specification/healthcare-worker-api.yaml | 2 ++ 1 file changed, 2 insertions(+) diff --git a/specification/healthcare-worker-api.yaml b/specification/healthcare-worker-api.yaml index af64e1fd..6f906cde 100644 --- a/specification/healthcare-worker-api.yaml +++ b/specification/healthcare-worker-api.yaml @@ -119,6 +119,8 @@ info: - used to confirm you are ready for production - includes application authentication + Read about [setting up test data in our path to live environments](https://digital.nhs.uk/services/path-to-live-environments/setting-up-test-data-in-our-path-to-live-environments). + ## Onboarding You need to get your software approved by us before it can go live with this API. We call this onboarding. The onboarding process can sometimes be quite long, so it's worth planning well ahead. From 52123ea3a178b0977821b7ae08fc9a69db7bce4b Mon Sep 17 00:00:00 2001 From: Tony Heap <40767455+tonyheap@users.noreply.github.com> Date: Mon, 16 Mar 2026 11:11:34 +0000 Subject: [PATCH 13/47] Update healthcare-worker-api.yaml --- specification/healthcare-worker-api.yaml | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/specification/healthcare-worker-api.yaml b/specification/healthcare-worker-api.yaml index 6f906cde..70de56c9 100644 --- a/specification/healthcare-worker-api.yaml +++ b/specification/healthcare-worker-api.yaml @@ -168,6 +168,8 @@ paths: You can also get details of the healthcare worker's [national RBAC roles](https://digital.nhs.uk/services/care-identity-service/applications-and-services/cis2-authentication/integrate/design-and-build/national-rbac-for-developers), using the `_revinclude` query parameter. + Note that this currently does not include details of directly assigned activities, as explained in the [main overview](#overview--overview). + parameters: - in: query name: identifier @@ -226,6 +228,9 @@ paths: This endpoint supports the use of the _include query parameter to expose more information about referenced organisations and practitioners. + + This endpoint currently does not include details of directly assigned activities, as explained in the [main overview](#overview--overview). + parameters: - in: query name: practitioner.identifier From ff9393dd6ed6207fbd1e0c66387ab09583a84ac4 Mon Sep 17 00:00:00 2001 From: Tony Heap <40767455+tonyheap@users.noreply.github.com> Date: Mon, 16 Mar 2026 11:17:17 +0000 Subject: [PATCH 14/47] Update healthcare-worker-api.yaml --- specification/healthcare-worker-api.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/specification/healthcare-worker-api.yaml b/specification/healthcare-worker-api.yaml index 70de56c9..2fe19b55 100644 --- a/specification/healthcare-worker-api.yaml +++ b/specification/healthcare-worker-api.yaml @@ -226,7 +226,7 @@ paths: Use this endpoint to get details of healthcare worker roles in the Care Identity Service (CIS) directory. It takes a CIS unique identifier as input and returns all the roles associated with that practitioner. - This endpoint supports the use of the _include query parameter to expose more information about referenced + This endpoint supports the use of the `_include` query parameter to expose more information about referenced organisations and practitioners. This endpoint currently does not include details of directly assigned activities, as explained in the [main overview](#overview--overview). From 3daf8bf75aa0231ff07f7732c87f62e0aa2d3ba4 Mon Sep 17 00:00:00 2001 From: Tony Heap <40767455+tonyheap@users.noreply.github.com> Date: Mon, 16 Mar 2026 11:50:06 +0000 Subject: [PATCH 15/47] Update healthcare-worker-api.yaml --- specification/healthcare-worker-api.yaml | 38 ++++++++++-------------- 1 file changed, 15 insertions(+), 23 deletions(-) diff --git a/specification/healthcare-worker-api.yaml b/specification/healthcare-worker-api.yaml index 2fe19b55..28a0e3a7 100644 --- a/specification/healthcare-worker-api.yaml +++ b/specification/healthcare-worker-api.yaml @@ -14,12 +14,6 @@ info: - search by professional codes, such as GMC or RNC code - get details of 'directly assigned' activities associated with the healthcare worker's role profiles (see below) - The strategic aim of the API is to allow systems to search, retrieve and display healthcare worker data from over 1.4 million NHS employees with a health care profile. - The objective is to increase data efficiency, business logic and improve interoperability within the business. - - This strategic solution will allow internal and 3rd party systems to access and share information more reliably, flexibly and efficiently while benefiting from improved network and bandwidth capacity, financial savings - and easier and smoother access to clinical systems. - ### Directly assigned activities [National RBAC](https://digital.nhs.uk/services/care-identity-service/applications-and-services/cis2-authentication/integrate/design-and-build/national-rbac-for-developers) is the method CIS uses to manage user permissions. @@ -38,11 +32,11 @@ info: ## Who can use this API This API can only be used where there is a legal basis to do so. Make sure you have a valid use case before you go too far with your development. - You must do this before you can go live (see "Onboarding" below). + You must do this before you can go live (see [Onboarding](#overview--onboarding)). ## Related APIs The following APIs are related to this one: - - [Spine Directory Service - LDAP API](https://digital.nhs.uk/developer/api-catalogue/spine-directory-service-ldap) - The legacy API for accessing healthcare worker information in CIS. Only available on HSCN and being considered for deprecation. + - [Spine Directory Service - LDAP API](https://digital.nhs.uk/developer/api-catalogue/spine-directory-service-ldap) - The legacy API for accessing healthcare worker information in CIS. Only available on HSCN and being planned for deprecation at some point. - [Organisation Data Terminology - FHIR API](https://digital.nhs.uk/developer/api-catalogue/organisation-data-terminology) - Get organisation information from the Organisation Data Service (ODS), including some limited information on some prescribing staff at each organisation. ## API status and roadmap @@ -67,8 +61,6 @@ info: You do not need to know much about FHIR to use this API - FHIR APIs are just RESTful APIs that follow specific rules. In particular: - resource names are capitalised and singular, for example `/Endpoint` not `/endpoints` - Error handling in this API follows [NHS guidelines](https://nhsconnect.github.io/FHIR-SpineCore/resources_error_handling.html) and produces an [OperationOutcome](https://fhir.nhs.uk/STU3/StructureDefinition/Spine-OperationOutcome-1) FHIR resource response with appropriate HTTP code. - ## Network access This API is available on the internet and, indirectly, on the [Health and Social Care Network (HSCN).](https://digital.nhs.uk/services/health-and-social-care-network) @@ -88,6 +80,8 @@ info: * 400 to 499 if it failed because of a client error by your application * 500 to 599 if it failed because of an error on our server + Error handling in this API follows [NHS guidelines](https://nhsconnect.github.io/FHIR-SpineCore/resources_error_handling.html) and produces an [OperationOutcome](https://fhir.nhs.uk/STU3/StructureDefinition/Spine-OperationOutcome-1) FHIR resource response with appropriate HTTP code. + Errors specific to each API are shown in the Endpoints section, under Response. See our [reference guide](https://digital.nhs.uk/developer/guides-and-documentation/reference-guide#http-status-codes) for more on errors. ## Open source @@ -108,15 +102,16 @@ info: ### Sandbox testing Our [sandbox environment](https://digital.nhs.uk/developer/guides-and-documentation/testing#sandbox-testing): - * only covers a limited set of scenarios - * is open-access, so does not allow you to test authorisation + - is for early developer testing + - only covers a limited set of scenarios + - is open-access, so does not allow you to test authorisation - For more details on sandbox testing, or to try out the sandbox using our \"Try this API\" feature, see the documentation for each endpoint. + For more details on sandbox testing, or to try out the sandbox using our 'Try this API' feature, see the documentation for each endpoint. ### Integration testing Our [integration test environment](https://digital.nhs.uk/developer/guides-and-documentation/testing#integration-testing): - - is for early developer testing - - used to confirm you are ready for production + - is for developer testing and formal integration testing + - is used to confirm you are ready for production - includes application authentication Read about [setting up test data in our path to live environments](https://digital.nhs.uk/services/path-to-live-environments/setting-up-test-data-in-our-path-to-live-environments). @@ -126,7 +121,7 @@ info: To understand how our online digital onboarding process works, see [digital onboarding](https://digital.nhs.uk/developer/guides-and-documentation/digital-onboarding). - To get started, sign in or create a [developer account](https://onboarding.prod.api.platform.nhs.uk/), then select 'product onboarding'. + To get started, sign in or create a [developer account](https://onboarding.prod.api.platform.nhs.uk/), then select 'Digital onboarding service'. contact: name: Spine Directory Service API Support @@ -166,9 +161,7 @@ paths: Only active accounts are returned. If the care identity itself is closed, the endpoint returns a 410 (Gone) response. You can also get details of the healthcare worker's [national RBAC roles](https://digital.nhs.uk/services/care-identity-service/applications-and-services/cis2-authentication/integrate/design-and-build/national-rbac-for-developers), - using the `_revinclude` query parameter. - - Note that this currently does not include details of directly assigned activities, as explained in the [main overview](#overview--overview). + using the `_revinclude` query parameter. This currently does not include details of directly assigned activities, as explained in the [main overview](#overview--overview). parameters: - in: query @@ -223,11 +216,10 @@ paths: operationId: getPractitionerRole description: | # Overview - Use this endpoint to get details of healthcare worker roles in the Care Identity Service (CIS) directory. It takes a CIS unique identifier - as input and returns all the roles associated with that practitioner. + Use this endpoint to get details of healthcare worker roles in the Care Identity Service (CIS). It takes a CIS unique identifier + as input and returns all the roles associated with that healthcare worker. - This endpoint supports the use of the `_include` query parameter to expose more information about referenced - organisations and practitioners. + You can get more information on the healthcare worker and the organisations linked to the roles using the `_include` query parameter. This endpoint currently does not include details of directly assigned activities, as explained in the [main overview](#overview--overview). From 2b24a23450918990fe59cd6811038aaecac007a8 Mon Sep 17 00:00:00 2001 From: Tony Heap <40767455+tonyheap@users.noreply.github.com> Date: Mon, 16 Mar 2026 12:55:58 +0000 Subject: [PATCH 16/47] Update healthcare-worker-api.yaml --- specification/healthcare-worker-api.yaml | 2 -- 1 file changed, 2 deletions(-) diff --git a/specification/healthcare-worker-api.yaml b/specification/healthcare-worker-api.yaml index 28a0e3a7..b135a36a 100644 --- a/specification/healthcare-worker-api.yaml +++ b/specification/healthcare-worker-api.yaml @@ -44,8 +44,6 @@ info: For details of future changes, see the [Care Identity Service roadmap](https://digital.nhs.uk/services/care-identity-service/roadmap). - If you have any other queries, [contact us](https://digital.nhs.uk/developer/help-and-support). - ## Service level This API is a silver service during beta, meaning it is operational 24 hours a day, 7 days a week but only supported during business hours (8am to 6pm), Monday to Friday excluding bank holidays. From 7460f6e9325dbaea95dbaf75cb86c85af2d61edd Mon Sep 17 00:00:00 2001 From: Tony Heap <40767455+tonyheap@users.noreply.github.com> Date: Mon, 16 Mar 2026 13:08:22 +0000 Subject: [PATCH 17/47] Create GetHealthcareWorkerDetailsResponseError.json --- ...etHealthcareWorkerDetailsResponseError.json | 18 ++++++++++++++++++ 1 file changed, 18 insertions(+) create mode 100644 specification/components/examples/GetHealthcareWorkerDetailsResponseError.json diff --git a/specification/components/examples/GetHealthcareWorkerDetailsResponseError.json b/specification/components/examples/GetHealthcareWorkerDetailsResponseError.json new file mode 100644 index 00000000..f46d1c8a --- /dev/null +++ b/specification/components/examples/GetHealthcareWorkerDetailsResponseError.json @@ -0,0 +1,18 @@ +{ + "resourceType": "OperationOutcome", + "issue": [ + { + "severity": "error", + "code": "unknown", + "details": { + "coding": [ + { + "system": "https://fhir.nhs.uk/STU3/ValueSet/Spine-ErrorOrWarningCode-1", + "code": "400", + "display": "Missing practitioner identifier" + } + ] + } + } + ] +} From 56405f1b5df0af7c46389a198dc4e62caaa31d44 Mon Sep 17 00:00:00 2001 From: Tony Heap <40767455+tonyheap@users.noreply.github.com> Date: Mon, 16 Mar 2026 13:14:42 +0000 Subject: [PATCH 18/47] Create GetHealthcareWorkerRoleDetailsResponseError.json --- ...althcareWorkerRoleDetailsResponseError.json | 18 ++++++++++++++++++ 1 file changed, 18 insertions(+) create mode 100644 specification/components/examples/GetHealthcareWorkerRoleDetailsResponseError.json diff --git a/specification/components/examples/GetHealthcareWorkerRoleDetailsResponseError.json b/specification/components/examples/GetHealthcareWorkerRoleDetailsResponseError.json new file mode 100644 index 00000000..f46d1c8a --- /dev/null +++ b/specification/components/examples/GetHealthcareWorkerRoleDetailsResponseError.json @@ -0,0 +1,18 @@ +{ + "resourceType": "OperationOutcome", + "issue": [ + { + "severity": "error", + "code": "unknown", + "details": { + "coding": [ + { + "system": "https://fhir.nhs.uk/STU3/ValueSet/Spine-ErrorOrWarningCode-1", + "code": "400", + "display": "Missing practitioner identifier" + } + ] + } + } + ] +} From beac0b2271d1a589afe267384be5993c0ab4c26a Mon Sep 17 00:00:00 2001 From: Tony Heap <40767455+tonyheap@users.noreply.github.com> Date: Mon, 16 Mar 2026 13:38:51 +0000 Subject: [PATCH 19/47] Update healthcare-worker-api.yaml --- specification/healthcare-worker-api.yaml | 130 +++++++++++++++++++++++ 1 file changed, 130 insertions(+) diff --git a/specification/healthcare-worker-api.yaml b/specification/healthcare-worker-api.yaml index b135a36a..1f3578d3 100644 --- a/specification/healthcare-worker-api.yaml +++ b/specification/healthcare-worker-api.yaml @@ -194,6 +194,28 @@ paths: with-includes: summary: Response with roles included externalValue: components/examples/GetHealthcareWorkerDetailsResponseSuccessWithIncludes.json + '4XX': + description: | + An error occurred as follows: + + | HTTP status | Error code | Description | + | ----------- | -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ | + | 400 | INVALID_SEARCH_DATA | Invalid combination of search parameters. For details, see the `diagnostics` field. | + | 400 | UNSUPPORTED_SERVICE | No search parameters provided. | + | 400 | MISSING_VALUE | Missing header or query parameter. For details, see the `diagnostics` field. | + | 400 | INVALID_VALUE | Invalid header or query parameter. For details, see the `diagnostics` field. | + | 400 | ADDITIONAL_PROPERTIES | Unrecognised query parameter. For details, see the `diagnostics` field. | + | 401 | ACCESS_DENIED | Access token missing, invalid or expired, or calling application not configured for this operation. | + | 403 | INVALID_VALUE | Multiple results requested when using the API in application-restricted mode. | + | 408 | UNABLE_TO_CALL_SERVICE | The downstream domain processing has not completed within the configured timeout period. | + | 429 | TOO_MANY_REQUESTS | You have exceeded your application's [rate limit](https://digital.nhs.uk/developer/guides-and-documentation/reference-guide#rate-limits). | + + content: + application/fhir+json: + schema: + $ref: '#/components/schemas/OperationOutcome' + example: + externalValue: components/examples/GetHealthcareWorkerDetailsResponseError.json '400': description: Missing or invalid query parameter(s). '404': @@ -258,6 +280,28 @@ paths: with-includes: summary: Response with practitioner and organisations included externalValue: components/examples/GetHealthcareWorkerRoleDetailsResponseSuccessWithIncludes.json + '4XX': + description: | + An error occurred as follows: + + | HTTP status | Error code | Description | + | ----------- | -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ | + | 400 | INVALID_SEARCH_DATA | Invalid combination of search parameters. For details, see the `diagnostics` field. | + | 400 | UNSUPPORTED_SERVICE | No search parameters provided. | + | 400 | MISSING_VALUE | Missing header or query parameter. For details, see the `diagnostics` field. | + | 400 | INVALID_VALUE | Invalid header or query parameter. For details, see the `diagnostics` field. | + | 400 | ADDITIONAL_PROPERTIES | Unrecognised query parameter. For details, see the `diagnostics` field. | + | 401 | ACCESS_DENIED | Access token missing, invalid or expired, or calling application not configured for this operation. | + | 403 | INVALID_VALUE | Multiple results requested when using the API in application-restricted mode. | + | 408 | UNABLE_TO_CALL_SERVICE | The downstream domain processing has not completed within the configured timeout period. | + | 429 | TOO_MANY_REQUESTS | You have exceeded your application's [rate limit](https://digital.nhs.uk/developer/guides-and-documentation/reference-guide#rate-limits). | + + content: + application/fhir+json: + schema: + $ref: '#/components/schemas/OperationOutcome' + example: + externalValue: components/examples/GetHealthcareWorkerDetailsResponseError.json '400': description: Missing or invalid query parameter(s). '404': @@ -555,3 +599,89 @@ components: type: string display: type: string + OperationOutcome: + type: object + description: | + Details of an error. + There are a number of possible error codes that can be returned along with a more detailed description in the `display` field. + properties: + resourceType: + type: string + description: FHIR Resource Type. + enum: OperationOutcome + issue: + type: array + description: List of issues that have occurred. + minItems: 1 + items: + type: object + required: + - severity + - code + properties: + severity: + type: string + enum: [fatal, error, warning, information] + description: Severity of the error. + example: error + code: + type: string + description: FHIR error code. + example: invalid + enum: + - invalid + - structure + - required + - value + - invariant + - security + - login + - unknown + - expired + - forbidden + - suppressed + - processing + - not-supported + - duplicate + - multiple-matches + - not-found + - deleted + - too-long + - code-invalid + - extension + - too-costly + - business-rule + - conflict + - transient + - lock-error + - no-store + - exception + - timeout + - incomplete + - throttled + - informational + details: + type: object + description: Internal error code. + properties: + coding: + type: array + items: + type: object + properties: + system: + type: string + description: URI of the coding system specification. + example: https://fhir.nhs.uk/R4/CodeSystem/Spine-ErrorOrWarningCode + version: + type: string + description: Version of the coding system in use. + example: '1' + code: + type: string + description: Symbol in syntax defined by the system. + example: MISSING_PRACTITIONER_IDENTIFIER + display: + type: string + description: Representation defined by the system. + example: Missing practitioner identifier From 06bbef29e1cd9d1c43943986e9c04991370f397c Mon Sep 17 00:00:00 2001 From: Tony Heap <40767455+tonyheap@users.noreply.github.com> Date: Mon, 16 Mar 2026 13:41:53 +0000 Subject: [PATCH 20/47] Update healthcare-worker-api.yaml --- specification/healthcare-worker-api.yaml | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/specification/healthcare-worker-api.yaml b/specification/healthcare-worker-api.yaml index 1f3578d3..788c53bf 100644 --- a/specification/healthcare-worker-api.yaml +++ b/specification/healthcare-worker-api.yaml @@ -78,7 +78,7 @@ info: * 400 to 499 if it failed because of a client error by your application * 500 to 599 if it failed because of an error on our server - Error handling in this API follows [NHS guidelines](https://nhsconnect.github.io/FHIR-SpineCore/resources_error_handling.html) and produces an [OperationOutcome](https://fhir.nhs.uk/STU3/StructureDefinition/Spine-OperationOutcome-1) FHIR resource response with appropriate HTTP code. + Error handling in this API follows [NHS guidelines](https://nhsconnect.github.io/FHIR-SpineCore/resources_error_handling.html) and produces an [utcome](https://fhir.nhs.uk/STU3/StructureDefinition/Spine-utcome-1) FHIR resource response with appropriate HTTP code. Errors specific to each API are shown in the Endpoints section, under Response. See our [reference guide](https://digital.nhs.uk/developer/guides-and-documentation/reference-guide#http-status-codes) for more on errors. @@ -608,7 +608,7 @@ components: resourceType: type: string description: FHIR Resource Type. - enum: OperationOutcome + enum: [OperationOutcome] issue: type: array description: List of issues that have occurred. From 6eb54f344e688391fa65f6690a28e60fde745be6 Mon Sep 17 00:00:00 2001 From: Tony Heap <40767455+tonyheap@users.noreply.github.com> Date: Mon, 16 Mar 2026 13:50:14 +0000 Subject: [PATCH 21/47] Update healthcare-worker-api.yaml --- specification/healthcare-worker-api.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/specification/healthcare-worker-api.yaml b/specification/healthcare-worker-api.yaml index 788c53bf..31b37bed 100644 --- a/specification/healthcare-worker-api.yaml +++ b/specification/healthcare-worker-api.yaml @@ -301,7 +301,7 @@ paths: schema: $ref: '#/components/schemas/OperationOutcome' example: - externalValue: components/examples/GetHealthcareWorkerDetailsResponseError.json + externalValue: components/examples/GetHealthcareWorkerRoleDetailsResponseError.json '400': description: Missing or invalid query parameter(s). '404': From 5b2855ab8c68ee558aa07a2eb5f9e6eeed0a6d08 Mon Sep 17 00:00:00 2001 From: Tony Heap <40767455+tonyheap@users.noreply.github.com> Date: Mon, 16 Mar 2026 13:58:59 +0000 Subject: [PATCH 22/47] Update healthcare-worker-api.yaml --- specification/healthcare-worker-api.yaml | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/specification/healthcare-worker-api.yaml b/specification/healthcare-worker-api.yaml index 31b37bed..ed07780d 100644 --- a/specification/healthcare-worker-api.yaml +++ b/specification/healthcare-worker-api.yaml @@ -215,7 +215,8 @@ paths: schema: $ref: '#/components/schemas/OperationOutcome' example: - externalValue: components/examples/GetHealthcareWorkerDetailsResponseError.json + $ref: 'components/examples/GetHealthcareWorkerDetailsResponseError.json' + # externalValue: components/examples/GetHealthcareWorkerDetailsResponseError.json '400': description: Missing or invalid query parameter(s). '404': From b4c2e5bb2971122d977d3bb776b834f7b1f2e763 Mon Sep 17 00:00:00 2001 From: Tony Heap <40767455+tonyheap@users.noreply.github.com> Date: Mon, 16 Mar 2026 14:59:58 +0000 Subject: [PATCH 23/47] Update healthcare-worker-api.yaml --- specification/healthcare-worker-api.yaml | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/specification/healthcare-worker-api.yaml b/specification/healthcare-worker-api.yaml index ed07780d..bd73a042 100644 --- a/specification/healthcare-worker-api.yaml +++ b/specification/healthcare-worker-api.yaml @@ -216,7 +216,6 @@ paths: $ref: '#/components/schemas/OperationOutcome' example: $ref: 'components/examples/GetHealthcareWorkerDetailsResponseError.json' - # externalValue: components/examples/GetHealthcareWorkerDetailsResponseError.json '400': description: Missing or invalid query parameter(s). '404': @@ -277,7 +276,7 @@ paths: examples: basic: summary: Basic response (without practitioner or organisation included) - externalValue: components/examples/GetHealthcareWorkerRoleDetailsResponseSuccessBasic.json + $ref: 'components/examples/GetHealthcareWorkerRoleDetailsResponseSuccessBasic.json' with-includes: summary: Response with practitioner and organisations included externalValue: components/examples/GetHealthcareWorkerRoleDetailsResponseSuccessWithIncludes.json @@ -302,7 +301,7 @@ paths: schema: $ref: '#/components/schemas/OperationOutcome' example: - externalValue: components/examples/GetHealthcareWorkerRoleDetailsResponseError.json + $ref: 'components/examples/GetHealthcareWorkerRoleDetailsResponseError.json' '400': description: Missing or invalid query parameter(s). '404': From dc5f3e600f1c7dd1013cb02cf26e8b8c064b5c8d Mon Sep 17 00:00:00 2001 From: Tony Heap <40767455+tonyheap@users.noreply.github.com> Date: Mon, 16 Mar 2026 15:22:09 +0000 Subject: [PATCH 24/47] Update healthcare-worker-api.yaml --- specification/healthcare-worker-api.yaml | 12 ++++++++---- 1 file changed, 8 insertions(+), 4 deletions(-) diff --git a/specification/healthcare-worker-api.yaml b/specification/healthcare-worker-api.yaml index bd73a042..026eed66 100644 --- a/specification/healthcare-worker-api.yaml +++ b/specification/healthcare-worker-api.yaml @@ -190,10 +190,12 @@ paths: examples: basic: summary: Basic response (without roles) - externalValue: components/examples/GetHealthcareWorkerDetailsResponseSuccessBasic.json + value: + $ref: 'components/examples/GetHealthcareWorkerDetailsResponseSuccessBasic.json' with-includes: summary: Response with roles included - externalValue: components/examples/GetHealthcareWorkerDetailsResponseSuccessWithIncludes.json + value: + $ref: 'components/examples/GetHealthcareWorkerDetailsResponseSuccessWithIncludes.json' '4XX': description: | An error occurred as follows: @@ -276,10 +278,12 @@ paths: examples: basic: summary: Basic response (without practitioner or organisation included) - $ref: 'components/examples/GetHealthcareWorkerRoleDetailsResponseSuccessBasic.json' + value: + $ref: 'components/examples/GetHealthcareWorkerRoleDetailsResponseSuccessBasic.json' with-includes: summary: Response with practitioner and organisations included - externalValue: components/examples/GetHealthcareWorkerRoleDetailsResponseSuccessWithIncludes.json + value: + $ref: 'components/examples/GetHealthcareWorkerRoleDetailsResponseSuccessWithIncludes.json' '4XX': description: | An error occurred as follows: From 7f950dc28253aab3dbb4bd9bd163edb8fbdc8f06 Mon Sep 17 00:00:00 2001 From: Tony Heap <40767455+tonyheap@users.noreply.github.com> Date: Mon, 16 Mar 2026 15:30:19 +0000 Subject: [PATCH 25/47] Update healthcare-worker-api.yaml --- specification/healthcare-worker-api.yaml | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/specification/healthcare-worker-api.yaml b/specification/healthcare-worker-api.yaml index 026eed66..b010edb3 100644 --- a/specification/healthcare-worker-api.yaml +++ b/specification/healthcare-worker-api.yaml @@ -199,7 +199,7 @@ paths: '4XX': description: | An error occurred as follows: - + | HTTP status | Error code | Description | | ----------- | -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ | | 400 | INVALID_SEARCH_DATA | Invalid combination of search parameters. For details, see the `diagnostics` field. | @@ -287,7 +287,7 @@ paths: '4XX': description: | An error occurred as follows: - + | HTTP status | Error code | Description | | ----------- | -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ | | 400 | INVALID_SEARCH_DATA | Invalid combination of search parameters. For details, see the `diagnostics` field. | From 4f26d7eca928b78341cd048c899079d3bfe87da4 Mon Sep 17 00:00:00 2001 From: Tony Heap <40767455+tonyheap@users.noreply.github.com> Date: Mon, 16 Mar 2026 15:37:26 +0000 Subject: [PATCH 26/47] Update GetHealthcareWorkerDetailsResponseError.json --- .../examples/GetHealthcareWorkerDetailsResponseError.json | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/specification/components/examples/GetHealthcareWorkerDetailsResponseError.json b/specification/components/examples/GetHealthcareWorkerDetailsResponseError.json index f46d1c8a..fcc3f855 100644 --- a/specification/components/examples/GetHealthcareWorkerDetailsResponseError.json +++ b/specification/components/examples/GetHealthcareWorkerDetailsResponseError.json @@ -8,7 +8,7 @@ "coding": [ { "system": "https://fhir.nhs.uk/STU3/ValueSet/Spine-ErrorOrWarningCode-1", - "code": "400", + "code": "MISSING_PRACTITIONER_IDENTIFIER", "display": "Missing practitioner identifier" } ] From efe9db66e7a4af66d481f776596a83ae6d340257 Mon Sep 17 00:00:00 2001 From: Tony Heap <40767455+tonyheap@users.noreply.github.com> Date: Mon, 16 Mar 2026 15:37:33 +0000 Subject: [PATCH 27/47] Update GetHealthcareWorkerRoleDetailsResponseError.json --- .../examples/GetHealthcareWorkerRoleDetailsResponseError.json | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/specification/components/examples/GetHealthcareWorkerRoleDetailsResponseError.json b/specification/components/examples/GetHealthcareWorkerRoleDetailsResponseError.json index f46d1c8a..fcc3f855 100644 --- a/specification/components/examples/GetHealthcareWorkerRoleDetailsResponseError.json +++ b/specification/components/examples/GetHealthcareWorkerRoleDetailsResponseError.json @@ -8,7 +8,7 @@ "coding": [ { "system": "https://fhir.nhs.uk/STU3/ValueSet/Spine-ErrorOrWarningCode-1", - "code": "400", + "code": "MISSING_PRACTITIONER_IDENTIFIER", "display": "Missing practitioner identifier" } ] From 23d31f2cdc5113df0b725d86a39ba52b4b94d2e5 Mon Sep 17 00:00:00 2001 From: Tony Heap <40767455+tonyheap@users.noreply.github.com> Date: Mon, 16 Mar 2026 15:53:21 +0000 Subject: [PATCH 28/47] Update healthcare-worker-api.yaml --- specification/healthcare-worker-api.yaml | 81 +++++++----------------- 1 file changed, 22 insertions(+), 59 deletions(-) diff --git a/specification/healthcare-worker-api.yaml b/specification/healthcare-worker-api.yaml index b010edb3..9e174c97 100644 --- a/specification/healthcare-worker-api.yaml +++ b/specification/healthcare-worker-api.yaml @@ -190,27 +190,23 @@ paths: examples: basic: summary: Basic response (without roles) - value: - $ref: 'components/examples/GetHealthcareWorkerDetailsResponseSuccessBasic.json' + externalValue: 'components/examples/GetHealthcareWorkerDetailsResponseSuccessBasic.json' with-includes: summary: Response with roles included - value: - $ref: 'components/examples/GetHealthcareWorkerDetailsResponseSuccessWithIncludes.json' + externalValue: 'components/examples/GetHealthcareWorkerDetailsResponseSuccessWithIncludes.json' '4XX': description: | An error occurred as follows: - | HTTP status | Error code | Description | - | ----------- | -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ | - | 400 | INVALID_SEARCH_DATA | Invalid combination of search parameters. For details, see the `diagnostics` field. | - | 400 | UNSUPPORTED_SERVICE | No search parameters provided. | - | 400 | MISSING_VALUE | Missing header or query parameter. For details, see the `diagnostics` field. | - | 400 | INVALID_VALUE | Invalid header or query parameter. For details, see the `diagnostics` field. | - | 400 | ADDITIONAL_PROPERTIES | Unrecognised query parameter. For details, see the `diagnostics` field. | - | 401 | ACCESS_DENIED | Access token missing, invalid or expired, or calling application not configured for this operation. | - | 403 | INVALID_VALUE | Multiple results requested when using the API in application-restricted mode. | - | 408 | UNABLE_TO_CALL_SERVICE | The downstream domain processing has not completed within the configured timeout period. | - | 429 | TOO_MANY_REQUESTS | You have exceeded your application's [rate limit](https://digital.nhs.uk/developer/guides-and-documentation/reference-guide#rate-limits). | + | HTTP status | Error code | Description | + | ----------- | ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ | + | 400 | MISSING_VALUE | Required request parameter missing, for example `identifier`. | + | 401 | ACCESS_DENIED | Access token missing, invalid or expired, or calling application not configured for this operation. | + | 404 | RESOURCE_NOT_FOUND | No healthcare worker record found for the given CIS identifier. | + | 410 | INACTIVE_ACCOUNT | The requested healthcare worker record is inactive in CIS. | + | 429 | TOO_MANY_REQUESTS | You have exceeded your application's [rate limit](https://digital.nhs.uk/developer/guides-and-documentation/reference-guide#rate-limits). | + + For more details, see [HTTP status codes](https://digital.nhs.uk/developer/guides-and-documentation/reference-guide#http-status-codes). content: application/fhir+json: @@ -218,20 +214,6 @@ paths: $ref: '#/components/schemas/OperationOutcome' example: $ref: 'components/examples/GetHealthcareWorkerDetailsResponseError.json' - '400': - description: Missing or invalid query parameter(s). - '404': - description: Invalid endpoint path - '405': - description: Unsupported HTTP method. For this endpoint only GET is available - '410': - description: Resource closed. The requested care identity profile is no longer active. - '500': - description: Unhandled internal server error - '502': - description: Upstream system returned an unsupported response - '504': - description: Upstream server request has timed out /PractitionerRole: get: summary: Get healthcare worker role details @@ -278,27 +260,22 @@ paths: examples: basic: summary: Basic response (without practitioner or organisation included) - value: - $ref: 'components/examples/GetHealthcareWorkerRoleDetailsResponseSuccessBasic.json' + externalValue: 'components/examples/GetHealthcareWorkerRoleDetailsResponseSuccessBasic.json' with-includes: summary: Response with practitioner and organisations included - value: - $ref: 'components/examples/GetHealthcareWorkerRoleDetailsResponseSuccessWithIncludes.json' - '4XX': + externalValue: 'components/examples/GetHealthcareWorkerRoleDetailsResponseSuccessWithIncludes.json' description: | An error occurred as follows: - | HTTP status | Error code | Description | - | ----------- | -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ | - | 400 | INVALID_SEARCH_DATA | Invalid combination of search parameters. For details, see the `diagnostics` field. | - | 400 | UNSUPPORTED_SERVICE | No search parameters provided. | - | 400 | MISSING_VALUE | Missing header or query parameter. For details, see the `diagnostics` field. | - | 400 | INVALID_VALUE | Invalid header or query parameter. For details, see the `diagnostics` field. | - | 400 | ADDITIONAL_PROPERTIES | Unrecognised query parameter. For details, see the `diagnostics` field. | - | 401 | ACCESS_DENIED | Access token missing, invalid or expired, or calling application not configured for this operation. | - | 403 | INVALID_VALUE | Multiple results requested when using the API in application-restricted mode. | - | 408 | UNABLE_TO_CALL_SERVICE | The downstream domain processing has not completed within the configured timeout period. | - | 429 | TOO_MANY_REQUESTS | You have exceeded your application's [rate limit](https://digital.nhs.uk/developer/guides-and-documentation/reference-guide#rate-limits). | + | HTTP status | Error code | Description | + | ----------- | ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ | + | 400 | MISSING_VALUE | Required request parameter missing, for example `practitioner.identifier`. | + | 401 | ACCESS_DENIED | Access token missing, invalid or expired, or calling application not configured for this operation. | + | 404 | RESOURCE_NOT_FOUND | No healthcare worker record found for the given CIS identifier. | + | 410 | INACTIVE_ACCOUNT | The requested healthcare worker record is inactive in CIS. | + | 429 | TOO_MANY_REQUESTS | You have exceeded your application's [rate limit](https://digital.nhs.uk/developer/guides-and-documentation/reference-guide#rate-limits). | + + For more details, see [HTTP status codes](https://digital.nhs.uk/developer/guides-and-documentation/reference-guide#http-status-codes). content: application/fhir+json: @@ -306,20 +283,6 @@ paths: $ref: '#/components/schemas/OperationOutcome' example: $ref: 'components/examples/GetHealthcareWorkerRoleDetailsResponseError.json' - '400': - description: Missing or invalid query parameter(s). - '404': - description: Invalid endpoint path - '405': - description: Unsupported HTTP method. For this endpoint only GET is available - '410': - description: Resource closed. The requested care identity profile is no longer active. - '500': - description: Unhandled internal server error - '502': - description: Upstream system returned an unsupported response - '504': - description: Upstream server request has timed out components: securitySchemes: app-level3: From 1add1808cdc19523a843d1a5726f2f88d7fe1d12 Mon Sep 17 00:00:00 2001 From: Tony Heap <40767455+tonyheap@users.noreply.github.com> Date: Mon, 16 Mar 2026 15:55:37 +0000 Subject: [PATCH 29/47] Update healthcare-worker-api.yaml --- specification/healthcare-worker-api.yaml | 1 + 1 file changed, 1 insertion(+) diff --git a/specification/healthcare-worker-api.yaml b/specification/healthcare-worker-api.yaml index 9e174c97..0fbfe803 100644 --- a/specification/healthcare-worker-api.yaml +++ b/specification/healthcare-worker-api.yaml @@ -264,6 +264,7 @@ paths: with-includes: summary: Response with practitioner and organisations included externalValue: 'components/examples/GetHealthcareWorkerRoleDetailsResponseSuccessWithIncludes.json' + '4XX': description: | An error occurred as follows: From fe0d262ff0826d997f7334347e1aaebe2789e590 Mon Sep 17 00:00:00 2001 From: Tony Heap <40767455+tonyheap@users.noreply.github.com> Date: Mon, 16 Mar 2026 16:14:28 +0000 Subject: [PATCH 30/47] Update GetHealthcareWorkerRoleDetailsResponseError.json --- .../examples/GetHealthcareWorkerRoleDetailsResponseError.json | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/specification/components/examples/GetHealthcareWorkerRoleDetailsResponseError.json b/specification/components/examples/GetHealthcareWorkerRoleDetailsResponseError.json index fcc3f855..be7a4a12 100644 --- a/specification/components/examples/GetHealthcareWorkerRoleDetailsResponseError.json +++ b/specification/components/examples/GetHealthcareWorkerRoleDetailsResponseError.json @@ -8,7 +8,7 @@ "coding": [ { "system": "https://fhir.nhs.uk/STU3/ValueSet/Spine-ErrorOrWarningCode-1", - "code": "MISSING_PRACTITIONER_IDENTIFIER", + "code": "MISSING_VALUE", "display": "Missing practitioner identifier" } ] From e18275272e5abb09dc074a4dd224a50d2543870d Mon Sep 17 00:00:00 2001 From: Tony Heap <40767455+tonyheap@users.noreply.github.com> Date: Mon, 16 Mar 2026 16:14:32 +0000 Subject: [PATCH 31/47] Update GetHealthcareWorkerDetailsResponseError.json --- .../examples/GetHealthcareWorkerDetailsResponseError.json | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/specification/components/examples/GetHealthcareWorkerDetailsResponseError.json b/specification/components/examples/GetHealthcareWorkerDetailsResponseError.json index fcc3f855..be7a4a12 100644 --- a/specification/components/examples/GetHealthcareWorkerDetailsResponseError.json +++ b/specification/components/examples/GetHealthcareWorkerDetailsResponseError.json @@ -8,7 +8,7 @@ "coding": [ { "system": "https://fhir.nhs.uk/STU3/ValueSet/Spine-ErrorOrWarningCode-1", - "code": "MISSING_PRACTITIONER_IDENTIFIER", + "code": "MISSING_VALUE", "display": "Missing practitioner identifier" } ] From 8be571c87c2ef8cd39c545eba98ce62b1945f564 Mon Sep 17 00:00:00 2001 From: Tony Heap <40767455+tonyheap@users.noreply.github.com> Date: Mon, 16 Mar 2026 16:15:01 +0000 Subject: [PATCH 32/47] Update healthcare-worker-api.yaml --- specification/healthcare-worker-api.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/specification/healthcare-worker-api.yaml b/specification/healthcare-worker-api.yaml index 0fbfe803..69385bec 100644 --- a/specification/healthcare-worker-api.yaml +++ b/specification/healthcare-worker-api.yaml @@ -78,7 +78,7 @@ info: * 400 to 499 if it failed because of a client error by your application * 500 to 599 if it failed because of an error on our server - Error handling in this API follows [NHS guidelines](https://nhsconnect.github.io/FHIR-SpineCore/resources_error_handling.html) and produces an [utcome](https://fhir.nhs.uk/STU3/StructureDefinition/Spine-utcome-1) FHIR resource response with appropriate HTTP code. + Error handling in this API follows [NHS guidelines](https://nhsconnect.github.io/FHIR-SpineCore/resources_error_handling.html) and produces an [OperationOutcome](https://fhir.nhs.uk/STU3/StructureDefinition/Spine-OperationOutcome-1) FHIR resource response with appropriate HTTP code. Errors specific to each API are shown in the Endpoints section, under Response. See our [reference guide](https://digital.nhs.uk/developer/guides-and-documentation/reference-guide#http-status-codes) for more on errors. From 8c798b3ae89514b757ebcef847bac43e8970602e Mon Sep 17 00:00:00 2001 From: Tony Heap <40767455+tonyheap@users.noreply.github.com> Date: Tue, 17 Mar 2026 13:02:22 +0000 Subject: [PATCH 33/47] Update healthcare-worker-api.yaml --- specification/healthcare-worker-api.yaml | 16 ++++++++++++++++ 1 file changed, 16 insertions(+) diff --git a/specification/healthcare-worker-api.yaml b/specification/healthcare-worker-api.yaml index 69385bec..c3c041d6 100644 --- a/specification/healthcare-worker-api.yaml +++ b/specification/healthcare-worker-api.yaml @@ -183,6 +183,18 @@ paths: responses: '200': description: Successful operation + headers: + X-Message-Id: + description: The X-Message-ID from the request header, if supplied, mirrored back. + schema: + type: string + format: uuid + example: '6d3d3674-7ce5-11ec-90d6-0242ac121234' + X-Correlation-Id: + description: The X-Correlation-ID from the request header, if supplied, mirrored back. + schema: + type: string + example: 11C46F5F-CDEF-4865-94B2-0EE0EDCC26DA content: application/fhir+json: schema: @@ -326,6 +338,10 @@ components: type: string example: '11C46F5F-CDEF-4865-94B2-0EE0EDCC26DA' schemas: + CorrelationId: + TBC + MessageId: + TBC Bundle: type: object properties: From 44597ac7e5b379a87439f4e6b7432a052d901df5 Mon Sep 17 00:00:00 2001 From: Tony Heap <40767455+tonyheap@users.noreply.github.com> Date: Tue, 17 Mar 2026 13:04:30 +0000 Subject: [PATCH 34/47] Update healthcare-worker-api.yaml --- specification/healthcare-worker-api.yaml | 4 ---- 1 file changed, 4 deletions(-) diff --git a/specification/healthcare-worker-api.yaml b/specification/healthcare-worker-api.yaml index c3c041d6..35d9e6e7 100644 --- a/specification/healthcare-worker-api.yaml +++ b/specification/healthcare-worker-api.yaml @@ -338,10 +338,6 @@ components: type: string example: '11C46F5F-CDEF-4865-94B2-0EE0EDCC26DA' schemas: - CorrelationId: - TBC - MessageId: - TBC Bundle: type: object properties: From bdb18fbda3d5435d2032152c8d892c19c3b6a443 Mon Sep 17 00:00:00 2001 From: Tony Heap <40767455+tonyheap@users.noreply.github.com> Date: Tue, 17 Mar 2026 13:17:16 +0000 Subject: [PATCH 35/47] Update healthcare-worker-api.yaml --- specification/healthcare-worker-api.yaml | 20 ++++++++++++++------ 1 file changed, 14 insertions(+), 6 deletions(-) diff --git a/specification/healthcare-worker-api.yaml b/specification/healthcare-worker-api.yaml index 35d9e6e7..c8f0d3d6 100644 --- a/specification/healthcare-worker-api.yaml +++ b/specification/healthcare-worker-api.yaml @@ -184,12 +184,8 @@ paths: '200': description: Successful operation headers: - X-Message-Id: - description: The X-Message-ID from the request header, if supplied, mirrored back. - schema: - type: string - format: uuid - example: '6d3d3674-7ce5-11ec-90d6-0242ac121234' + X-Request-Id: + $ref: #/components/headers/RequestId X-Correlation-Id: description: The X-Correlation-ID from the request header, if supplied, mirrored back. schema: @@ -337,6 +333,18 @@ components: schema: type: string example: '11C46F5F-CDEF-4865-94B2-0EE0EDCC26DA' + headers: + RequestId: + description: The X-Request-Id from the request header, if supplied, mirrored back. + schema: + type: string + format: uuid + example: '6d3d3674-7ce5-11ec-90d6-0242ac121234' + CorrelationId: + description: The X-Correlation-Id from the request header, if supplied, mirrored back. + schema: + type: string + example: 11C46F5F-CDEF-4865-94B2-0EE0EDCC26DA schemas: Bundle: type: object From 54a06111080d086f14d6d41a8771375d82f0563b Mon Sep 17 00:00:00 2001 From: Tony Heap <40767455+tonyheap@users.noreply.github.com> Date: Tue, 17 Mar 2026 13:20:08 +0000 Subject: [PATCH 36/47] Update healthcare-worker-api.yaml --- specification/healthcare-worker-api.yaml | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/specification/healthcare-worker-api.yaml b/specification/healthcare-worker-api.yaml index c8f0d3d6..ceae874a 100644 --- a/specification/healthcare-worker-api.yaml +++ b/specification/healthcare-worker-api.yaml @@ -339,12 +339,12 @@ components: schema: type: string format: uuid - example: '6d3d3674-7ce5-11ec-90d6-0242ac121234' + example: '6d3d3674-7ce5-11ec-90d6-0242ac121234' CorrelationId: description: The X-Correlation-Id from the request header, if supplied, mirrored back. schema: type: string - example: 11C46F5F-CDEF-4865-94B2-0EE0EDCC26DA + example: 11C46F5F-CDEF-4865-94B2-0EE0EDCC26DA schemas: Bundle: type: object From 606cfc4585604e415a18157dfe00409f3d82cde8 Mon Sep 17 00:00:00 2001 From: Tony Heap <40767455+tonyheap@users.noreply.github.com> Date: Tue, 17 Mar 2026 13:28:32 +0000 Subject: [PATCH 37/47] Update healthcare-worker-api.yaml --- specification/healthcare-worker-api.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/specification/healthcare-worker-api.yaml b/specification/healthcare-worker-api.yaml index ceae874a..03b0a3dd 100644 --- a/specification/healthcare-worker-api.yaml +++ b/specification/healthcare-worker-api.yaml @@ -185,7 +185,7 @@ paths: description: Successful operation headers: X-Request-Id: - $ref: #/components/headers/RequestId + $ref: '#/components/headers/RequestId' X-Correlation-Id: description: The X-Correlation-ID from the request header, if supplied, mirrored back. schema: From e8b484e64e51c99d1b9d77c42ea182e4a7ebcff0 Mon Sep 17 00:00:00 2001 From: Tony Heap <40767455+tonyheap@users.noreply.github.com> Date: Tue, 17 Mar 2026 13:40:04 +0000 Subject: [PATCH 38/47] Update healthcare-worker-api.yaml --- specification/healthcare-worker-api.yaml | 22 ++++++++++++++++++---- 1 file changed, 18 insertions(+), 4 deletions(-) diff --git a/specification/healthcare-worker-api.yaml b/specification/healthcare-worker-api.yaml index 03b0a3dd..53bb4fdc 100644 --- a/specification/healthcare-worker-api.yaml +++ b/specification/healthcare-worker-api.yaml @@ -187,10 +187,7 @@ paths: X-Request-Id: $ref: '#/components/headers/RequestId' X-Correlation-Id: - description: The X-Correlation-ID from the request header, if supplied, mirrored back. - schema: - type: string - example: 11C46F5F-CDEF-4865-94B2-0EE0EDCC26DA + $ref: '#/components/headers/CorrelationId' content: application/fhir+json: schema: @@ -216,6 +213,11 @@ paths: For more details, see [HTTP status codes](https://digital.nhs.uk/developer/guides-and-documentation/reference-guide#http-status-codes). + headers: + X-Request-Id: + $ref: '#/components/headers/RequestId' + X-Correlation-Id: + $ref: '#/components/headers/CorrelationId' content: application/fhir+json: schema: @@ -261,6 +263,11 @@ paths: responses: '200': description: Successful operation + headers: + X-Request-Id: + $ref: '#/components/headers/RequestId' + X-Correlation-Id: + $ref: '#/components/headers/CorrelationId' content: application/fhir+json: schema: @@ -286,6 +293,11 @@ paths: For more details, see [HTTP status codes](https://digital.nhs.uk/developer/guides-and-documentation/reference-guide#http-status-codes). + headers: + X-Request-Id: + $ref: '#/components/headers/RequestId' + X-Correlation-Id: + $ref: '#/components/headers/CorrelationId' content: application/fhir+json: schema: @@ -335,12 +347,14 @@ components: example: '11C46F5F-CDEF-4865-94B2-0EE0EDCC26DA' headers: RequestId: + name: X-Request-Id description: The X-Request-Id from the request header, if supplied, mirrored back. schema: type: string format: uuid example: '6d3d3674-7ce5-11ec-90d6-0242ac121234' CorrelationId: + name: X-Correlation-Id description: The X-Correlation-Id from the request header, if supplied, mirrored back. schema: type: string From 8c490af6a316f404f03fb7f5146eec444df3b5e9 Mon Sep 17 00:00:00 2001 From: Tony Heap <40767455+tonyheap@users.noreply.github.com> Date: Tue, 17 Mar 2026 13:49:48 +0000 Subject: [PATCH 39/47] Update healthcare-worker-api.yaml --- specification/healthcare-worker-api.yaml | 2 -- 1 file changed, 2 deletions(-) diff --git a/specification/healthcare-worker-api.yaml b/specification/healthcare-worker-api.yaml index 53bb4fdc..f25eef50 100644 --- a/specification/healthcare-worker-api.yaml +++ b/specification/healthcare-worker-api.yaml @@ -347,14 +347,12 @@ components: example: '11C46F5F-CDEF-4865-94B2-0EE0EDCC26DA' headers: RequestId: - name: X-Request-Id description: The X-Request-Id from the request header, if supplied, mirrored back. schema: type: string format: uuid example: '6d3d3674-7ce5-11ec-90d6-0242ac121234' CorrelationId: - name: X-Correlation-Id description: The X-Correlation-Id from the request header, if supplied, mirrored back. schema: type: string From e172e10b2ceedd216147d76d2d76d903784b4895 Mon Sep 17 00:00:00 2001 From: Tony Heap <40767455+tonyheap@users.noreply.github.com> Date: Tue, 17 Mar 2026 14:34:15 +0000 Subject: [PATCH 40/47] Update healthcare-worker-api.yaml --- specification/healthcare-worker-api.yaml | 61 ++++++++++++++++++++---- 1 file changed, 53 insertions(+), 8 deletions(-) diff --git a/specification/healthcare-worker-api.yaml b/specification/healthcare-worker-api.yaml index f25eef50..46d24130 100644 --- a/specification/healthcare-worker-api.yaml +++ b/specification/healthcare-worker-api.yaml @@ -438,9 +438,11 @@ components: type: object properties: system: + description: Coding system used for the identifier. type: string - default: https://fhir.nhs.uk/Id/sds-user-id + enum: [https://fhir.nhs.uk/Id/sds-user-id] value: + description: The identifier value. type: string example: '123456789012' active: @@ -512,9 +514,9 @@ components: description: Whether the role is active in CIS. example: True practitioner: - $ref: '#/components/schemas/Reference' + $ref: '#/components/schemas/PractitionerReference' organization: - $ref: '#/components/schemas/Reference' + $ref: '#/components/schemas/OrganizationReference' period: description: Time period during which the role applies, or applied. type: object @@ -531,7 +533,7 @@ components: minItems: 1 maxItems: 1 items: - $ref: '#/components/schemas/CodeableConcept' + $ref: '#/components/schemas/RoleCode' Organization: description: | An organisation associated with one of the roles in the result set, formatted as a FHIR `Organization` resource. @@ -565,39 +567,82 @@ components: description: Organisation name. type: string example: SILKSTONE PHARMACY - Reference: + PractitionerReference: + description: Summary of the healthcare worker to whom the roles relate. type: object properties: reference: + description: Relative URL for the Practitioner FHIR resource for the healthcare worker. type: string identifier: + description: CIS identifier for the healthcare worker. Also known as their UUID or smartcard ID. type: object properties: system: + description: Coding system for the identifier. type: string + enum: [https://fhir.nhs.uk/Id/sds-user-id] value: + description: The identifier itself. type: string display: + description: Healthcare worker's full name, including prefix, given name and family name. type: string - CodeableConcept: + OrganizationReference: + description: Summary of an organisation to which one or more of the roles relate. + type: object + properties: + reference: + description: Relative URL for the Organization FHIR resource for the organisation. + type: string + identifier: + description: ODS code for the organisation. + type: object + properties: + system: + description: Coding system for the ODS code. + type: string + enum: [https://fhir.nhs.uk/Id/ods-organization-code] + value: + description: The ODS code itself. + type: string + display: + description: Organisation name. + type: string + RoleCode: + description: Code for the role, expressed as a FHIR CodeableConcept resource. type: object properties: resourceType: + description: FHIR resource type. type: string - default: CodeableConcept + enum: [CodeableConcept] coding: + description: The actual coding, expressed as a FHIR Coding resource. type: array + minItems: 1 + maxItems: 1 items: type: object properties: resourceType: + description: FHIR resource type. type: string - default: Coding + enum: [Coding] system: + description: Code system used for the role code. type: string + enum: [https://fhir.nhs.uk/CodeSystem/NHSDigital-SDS-JobRoleCode] code: + description: | + The role code itself. Consists of three parts, separated by colons, in the format `Snnnn:Gnnnn:Rnnnn`, + forming a hierarchy. The useful part is the 'R' code, which maps to activity codes as explained in + [National RBAC for developers](https://digital.nhs.uk/services/care-identity-service/applications-and-services/cis2-authentication/integrate/design-and-build/national-rbac-for-developers). type: string display: + description: | + Role code description. Consists of three parts, separated by colons, corresponding to the three parts of the role code. + The useful part is the third part, corresponding to the 'R' code. type: string OperationOutcome: type: object From e56569f7d9fb526eadbb4a8104c5a2c05432f06a Mon Sep 17 00:00:00 2001 From: Tony Heap <40767455+tonyheap@users.noreply.github.com> Date: Tue, 17 Mar 2026 14:55:56 +0000 Subject: [PATCH 41/47] Update healthcare-worker-api.yaml --- specification/healthcare-worker-api.yaml | 16 +++++++++------- 1 file changed, 9 insertions(+), 7 deletions(-) diff --git a/specification/healthcare-worker-api.yaml b/specification/healthcare-worker-api.yaml index 46d24130..c8ad5656 100644 --- a/specification/healthcare-worker-api.yaml +++ b/specification/healthcare-worker-api.yaml @@ -418,7 +418,7 @@ components: type: string enum: [match,include] Practitioner: - description: A healthcare worker's personal details, formatted as a FHIR `Practitioner` resource. + description: A healthcare worker's personal details, expressed as a FHIR `Practitioner` resource. type: object properties: resourceType: @@ -442,11 +442,13 @@ components: type: string enum: [https://fhir.nhs.uk/Id/sds-user-id] value: - description: The identifier value. + description: The identifier itself. type: string example: '123456789012' active: - description: Indicates whether the healthcare worker's account is active in CIS. + description: | + Indicates whether the healthcare worker's account is active in CIS. + Because the response only ever includes active accounts, this is always `true`. type: boolean example: true name: @@ -481,7 +483,7 @@ components: example: 'Ms' PractitionerRole: description: | - A healthcare worker role (sometimes called a 'role profile'), formatted as a FHIR `PractitionerRole` resource. + A healthcare worker role (sometimes called a 'role profile'), expressed as a FHIR `PractitionerRole` resource. A healthcare worker can have multiple roles, and each role is associated with a specific organisation. If the worker performs the same role in multiple organisations, there is a separate role profile for each organisation. type: object @@ -536,7 +538,7 @@ components: $ref: '#/components/schemas/RoleCode' Organization: description: | - An organisation associated with one of the roles in the result set, formatted as a FHIR `Organization` resource. + An organisation associated with one of the roles in the result set, expressed as a FHIR `Organization` resource. type: object properties: resourceType: @@ -610,7 +612,7 @@ components: description: Organisation name. type: string RoleCode: - description: Code for the role, expressed as a FHIR CodeableConcept resource. + description: Code for the role, expressed as a FHIR `CodeableConcept` resource. type: object properties: resourceType: @@ -618,7 +620,7 @@ components: type: string enum: [CodeableConcept] coding: - description: The actual coding, expressed as a FHIR Coding resource. + description: The actual coding, expressed as a FHIR `Coding` resource. type: array minItems: 1 maxItems: 1 From 8456001df59531a44576195c3d7c8fb1df91a56b Mon Sep 17 00:00:00 2001 From: Tony Heap <40767455+tonyheap@users.noreply.github.com> Date: Wed, 18 Mar 2026 11:49:18 +0000 Subject: [PATCH 42/47] Update healthcare-worker-api.yaml --- specification/healthcare-worker-api.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/specification/healthcare-worker-api.yaml b/specification/healthcare-worker-api.yaml index c8ad5656..91047649 100644 --- a/specification/healthcare-worker-api.yaml +++ b/specification/healthcare-worker-api.yaml @@ -42,7 +42,7 @@ info: ## API status and roadmap This API is in [beta](https://digital.nhs.uk/developer/guides-and-documentation/reference-guide#statuses). - For details of future changes, see the [Care Identity Service roadmap](https://digital.nhs.uk/services/care-identity-service/roadmap). + For details of future changes, see [Care Identity Service roadmap](https://digital.nhs.uk/services/care-identity-service/roadmap). ## Service level This API is a silver service during beta, meaning it is operational 24 hours a day, 7 days a week but only supported during business hours (8am to 6pm), Monday to Friday excluding bank holidays. From 7cbe64de8ccdba5d145740df1c9213161fe656b5 Mon Sep 17 00:00:00 2001 From: jolyonbrownnhs Date: Wed, 18 Mar 2026 16:20:38 +0000 Subject: [PATCH 43/47] HCW-319 use redocly dereferencing to fix response header issues --- .github/workflows/publish-spec-uat.yml | 1 + buildspecs/deploy.yml | 6 ++++-- 2 files changed, 5 insertions(+), 2 deletions(-) diff --git a/.github/workflows/publish-spec-uat.yml b/.github/workflows/publish-spec-uat.yml index bf8673f9..8013bec7 100644 --- a/.github/workflows/publish-spec-uat.yml +++ b/.github/workflows/publish-spec-uat.yml @@ -23,6 +23,7 @@ jobs: run: | npx -y @redocly/cli bundle \ specification/healthcare-worker-api.yaml \ + -d \ -o specification/healthcare-worker-api.resolved.json \ --keep-url-references npx -y @redocly/cli lint --config redocly.yaml diff --git a/buildspecs/deploy.yml b/buildspecs/deploy.yml index c8aadedd..130f7c87 100644 --- a/buildspecs/deploy.yml +++ b/buildspecs/deploy.yml @@ -25,11 +25,13 @@ phases: - chmod +x /usr/bin/yq pre_build: commands: - # Bundle the OpenAPI spec to inline all external references (e.g. externalValue example files). + # Bundle and dereference the OpenAPI spec before publication. + # Proxygen preserves response header names reliably when header component refs are already + # inlined under the response header map keys. # This resolved file is used by apim_instance_deploy.sh so that proxygen receives a fully # self-contained spec rather than one with unresolvable relative file paths. # --keep-url-references (-k) preserves the proxygen-managed security scheme $ref which must remain unresolved. - - npx -y @redocly/cli bundle specification/healthcare-worker-api.yaml -o specification/healthcare-worker-api.resolved.yaml --keep-url-references + - npx -y @redocly/cli bundle specification/healthcare-worker-api.yaml -d -o specification/healthcare-worker-api.resolved.yaml --keep-url-references build: commands: - cd infrastructure From 5c6c46ce5f3b8dded519dd870e73f9c2f69e4709 Mon Sep 17 00:00:00 2001 From: jolyonbrownnhs Date: Wed, 18 Mar 2026 17:17:40 +0000 Subject: [PATCH 44/47] HCW-319 make responses direct header objects in spec --- specification/healthcare-worker-api.yaml | 56 +++++++++++++++--------- 1 file changed, 36 insertions(+), 20 deletions(-) diff --git a/specification/healthcare-worker-api.yaml b/specification/healthcare-worker-api.yaml index 91047649..1dc86ccd 100644 --- a/specification/healthcare-worker-api.yaml +++ b/specification/healthcare-worker-api.yaml @@ -185,9 +185,16 @@ paths: description: Successful operation headers: X-Request-Id: - $ref: '#/components/headers/RequestId' + description: The X-Request-Id from the request header, if supplied, mirrored back. + schema: + type: string + format: uuid + example: '6d3d3674-7ce5-11ec-90d6-0242ac121234' X-Correlation-Id: - $ref: '#/components/headers/CorrelationId' + description: The X-Correlation-Id from the request header, if supplied, mirrored back. + schema: + type: string + example: 11C46F5F-CDEF-4865-94B2-0EE0EDCC26DA content: application/fhir+json: schema: @@ -215,9 +222,16 @@ paths: headers: X-Request-Id: - $ref: '#/components/headers/RequestId' + description: The X-Request-Id from the request header, if supplied, mirrored back. + schema: + type: string + format: uuid + example: '6d3d3674-7ce5-11ec-90d6-0242ac121234' X-Correlation-Id: - $ref: '#/components/headers/CorrelationId' + description: The X-Correlation-Id from the request header, if supplied, mirrored back. + schema: + type: string + example: 11C46F5F-CDEF-4865-94B2-0EE0EDCC26DA content: application/fhir+json: schema: @@ -265,9 +279,16 @@ paths: description: Successful operation headers: X-Request-Id: - $ref: '#/components/headers/RequestId' + description: The X-Request-Id from the request header, if supplied, mirrored back. + schema: + type: string + format: uuid + example: '6d3d3674-7ce5-11ec-90d6-0242ac121234' X-Correlation-Id: - $ref: '#/components/headers/CorrelationId' + description: The X-Correlation-Id from the request header, if supplied, mirrored back. + schema: + type: string + example: 11C46F5F-CDEF-4865-94B2-0EE0EDCC26DA content: application/fhir+json: schema: @@ -295,9 +316,16 @@ paths: headers: X-Request-Id: - $ref: '#/components/headers/RequestId' + description: The X-Request-Id from the request header, if supplied, mirrored back. + schema: + type: string + format: uuid + example: '6d3d3674-7ce5-11ec-90d6-0242ac121234' X-Correlation-Id: - $ref: '#/components/headers/CorrelationId' + description: The X-Correlation-Id from the request header, if supplied, mirrored back. + schema: + type: string + example: 11C46F5F-CDEF-4865-94B2-0EE0EDCC26DA content: application/fhir+json: schema: @@ -345,18 +373,6 @@ components: schema: type: string example: '11C46F5F-CDEF-4865-94B2-0EE0EDCC26DA' - headers: - RequestId: - description: The X-Request-Id from the request header, if supplied, mirrored back. - schema: - type: string - format: uuid - example: '6d3d3674-7ce5-11ec-90d6-0242ac121234' - CorrelationId: - description: The X-Correlation-Id from the request header, if supplied, mirrored back. - schema: - type: string - example: 11C46F5F-CDEF-4865-94B2-0EE0EDCC26DA schemas: Bundle: type: object From 4a10e3fb58b3a263548f10205d74d13545d274b5 Mon Sep 17 00:00:00 2001 From: jolyonbrownnhs Date: Thu, 19 Mar 2026 13:11:39 +0000 Subject: [PATCH 45/47] HCW-319 add test marker for UAT refresh check --- specification/healthcare-worker-api.yaml | 2 ++ 1 file changed, 2 insertions(+) diff --git a/specification/healthcare-worker-api.yaml b/specification/healthcare-worker-api.yaml index 1dc86ccd..88b8f9b5 100644 --- a/specification/healthcare-worker-api.yaml +++ b/specification/healthcare-worker-api.yaml @@ -6,6 +6,8 @@ info: ## Overview Use this API to access details of healthcare workers registered in the [Care Identity Service (CIS)](https://digital.nhs.uk/services/care-identity-service) directory. + This is a test marker for UAT refresh verification. + You can: - get basic professional details of any healthcare worker with an active care identity, using their unique ID (this is sometimes known as SDS user ID or Smartcard ID) - get details of the [national RBAC](https://digital.nhs.uk/services/care-identity-service/applications-and-services/cis2-authentication/integrate/design-and-build/national-rbac-for-developers) roles that have been assigned to them by their Registration Authority From c54da2360c6e656ad56fa2388645368d2bbbb533 Mon Sep 17 00:00:00 2001 From: jolyonbrownnhs Date: Thu, 19 Mar 2026 14:10:01 +0000 Subject: [PATCH 46/47] HCW-319 remove UAT refresh test marker --- specification/healthcare-worker-api.yaml | 2 -- 1 file changed, 2 deletions(-) diff --git a/specification/healthcare-worker-api.yaml b/specification/healthcare-worker-api.yaml index 88b8f9b5..1dc86ccd 100644 --- a/specification/healthcare-worker-api.yaml +++ b/specification/healthcare-worker-api.yaml @@ -6,8 +6,6 @@ info: ## Overview Use this API to access details of healthcare workers registered in the [Care Identity Service (CIS)](https://digital.nhs.uk/services/care-identity-service) directory. - This is a test marker for UAT refresh verification. - You can: - get basic professional details of any healthcare worker with an active care identity, using their unique ID (this is sometimes known as SDS user ID or Smartcard ID) - get details of the [national RBAC](https://digital.nhs.uk/services/care-identity-service/applications-and-services/cis2-authentication/integrate/design-and-build/national-rbac-for-developers) roles that have been assigned to them by their Registration Authority From 5ed07d10d2e636c855c49411f8823c2db5ae5fef Mon Sep 17 00:00:00 2001 From: jolyonbrownnhs Date: Thu, 19 Mar 2026 14:50:10 +0000 Subject: [PATCH 47/47] HCW-319 use external response header fragments --- .../components/headers/XCorrelationId.yaml | 5 +++ .../components/headers/XRequestId.yaml | 6 +++ specification/healthcare-worker-api.yaml | 44 ++++--------------- 3 files changed, 19 insertions(+), 36 deletions(-) create mode 100644 specification/components/headers/XCorrelationId.yaml create mode 100644 specification/components/headers/XRequestId.yaml diff --git a/specification/components/headers/XCorrelationId.yaml b/specification/components/headers/XCorrelationId.yaml new file mode 100644 index 00000000..c9743520 --- /dev/null +++ b/specification/components/headers/XCorrelationId.yaml @@ -0,0 +1,5 @@ +description: | + The X-Correlation-Id from the request header, if supplied, mirrored back. +schema: + type: string + example: 11C46F5F-CDEF-4865-94B2-0EE0EDCC26DA \ No newline at end of file diff --git a/specification/components/headers/XRequestId.yaml b/specification/components/headers/XRequestId.yaml new file mode 100644 index 00000000..7e15b5ea --- /dev/null +++ b/specification/components/headers/XRequestId.yaml @@ -0,0 +1,6 @@ +description: | + The X-Request-Id from the request header, if supplied, mirrored back. +schema: + type: string + format: uuid + example: '6d3d3674-7ce5-11ec-90d6-0242ac121234' \ No newline at end of file diff --git a/specification/healthcare-worker-api.yaml b/specification/healthcare-worker-api.yaml index 1dc86ccd..563b94f9 100644 --- a/specification/healthcare-worker-api.yaml +++ b/specification/healthcare-worker-api.yaml @@ -185,16 +185,9 @@ paths: description: Successful operation headers: X-Request-Id: - description: The X-Request-Id from the request header, if supplied, mirrored back. - schema: - type: string - format: uuid - example: '6d3d3674-7ce5-11ec-90d6-0242ac121234' + $ref: 'components/headers/XRequestId.yaml' X-Correlation-Id: - description: The X-Correlation-Id from the request header, if supplied, mirrored back. - schema: - type: string - example: 11C46F5F-CDEF-4865-94B2-0EE0EDCC26DA + $ref: 'components/headers/XCorrelationId.yaml' content: application/fhir+json: schema: @@ -222,16 +215,9 @@ paths: headers: X-Request-Id: - description: The X-Request-Id from the request header, if supplied, mirrored back. - schema: - type: string - format: uuid - example: '6d3d3674-7ce5-11ec-90d6-0242ac121234' + $ref: 'components/headers/XRequestId.yaml' X-Correlation-Id: - description: The X-Correlation-Id from the request header, if supplied, mirrored back. - schema: - type: string - example: 11C46F5F-CDEF-4865-94B2-0EE0EDCC26DA + $ref: 'components/headers/XCorrelationId.yaml' content: application/fhir+json: schema: @@ -279,16 +265,9 @@ paths: description: Successful operation headers: X-Request-Id: - description: The X-Request-Id from the request header, if supplied, mirrored back. - schema: - type: string - format: uuid - example: '6d3d3674-7ce5-11ec-90d6-0242ac121234' + $ref: 'components/headers/XRequestId.yaml' X-Correlation-Id: - description: The X-Correlation-Id from the request header, if supplied, mirrored back. - schema: - type: string - example: 11C46F5F-CDEF-4865-94B2-0EE0EDCC26DA + $ref: 'components/headers/XCorrelationId.yaml' content: application/fhir+json: schema: @@ -316,16 +295,9 @@ paths: headers: X-Request-Id: - description: The X-Request-Id from the request header, if supplied, mirrored back. - schema: - type: string - format: uuid - example: '6d3d3674-7ce5-11ec-90d6-0242ac121234' + $ref: 'components/headers/XRequestId.yaml' X-Correlation-Id: - description: The X-Correlation-Id from the request header, if supplied, mirrored back. - schema: - type: string - example: 11C46F5F-CDEF-4865-94B2-0EE0EDCC26DA + $ref: 'components/headers/XCorrelationId.yaml' content: application/fhir+json: schema: