--- title: "Retrieve \"on-behalf-of\" practitioner user information (A040, FHIR R4)" method: GET path: "/R4/Practitioner" tags: ["Retrieve user information"] --- # Retrieve "on-behalf-of" practitioner user information (A040, FHIR R4) `GET /R4/Practitioner` ## Overview Use this endpoint to determine which e-RS users a `SERVICE_PROVIDER_CLINICIAN_ADMIN` is allowed to work "on-behalf-of". Note: In e-RS, `SERVICE_PROVIDER_CLINICIAN_ADMIN` users always act "on-behalf-of" a `SERVICE_PROVIDER_CLINICIAN`. This endpoint specifically helps `SERVICE_PROVIDER_CLINICIAN_ADMIN` identify who they are allowed to log in as. ## Supported security patterns - Healthcare worker, user-restricted access ## Pre-requisites To use this endpoint, you must be an authenticated e-RS user and use one of the following e-RS roles depending on the query being invoked: | Query | e-RS Role(s) | | -------------------------------------------------------------------- | --------------------------------- | | onBehalfOf | `SERVICE_PROVIDER_CLINICIAN_ADMIN` | ## Use case As an authenticated user who has the `SERVICE_PROVIDER_CLINICIAN_ADMIN` role I need to know which provider clinical users I am allowed to work "on-behalf-of" at my provider organisation So I can log in as a `SERVICE_PROVIDER_CLINICIAN_ADMIN` user and complete tasks on behalf of a chosen `SERVICE_PROVIDER_CLINICIAN` user. ## Related endpoints To perform actions as a `SERVICE_PROVIDER_CLINICIAN_ADMIN` user, you must provide one of the returned Practitioner IDs, in the `NHSD-eRS-On-Behalf-Of-User-ID` header parameter, to indicate which `SERVICE_PROVIDER_CLINICIAN` the call is on-behalf-of. ## Query parameters - `_query` 'onBehalfOf', required ## Headers - `Authorization` string, ^Bearer\ [[:ascii:]]+$, required - `X-Correlation-ID` string - `NHSD-End-User-Organisation-ODS` string, required - `NHSD-eRS-Business-Function` 'REFERRING_CLINICIAN' | 'REFERRING_CLINICIAN_ADMIN' | 'REFERRING_ADMIN' | 'COMMISSIONER' | 'SERVICE_PROVIDER_CLINICIAN_ADMIN' | 'SERVICE_PROVIDER_CLINICIAN' | 'SERVICE_PROVIDER_ADMIN' | 'INFORMATION_ANALYST' | 'BOOKING_MANAGER' | 'ADDITIONAL_REQUIREMENTS_MANAGER', required ## Response `200` The response body is a `Bundle` that contains `Practitioner` entries which define the [[HYPERLINK_ERS_BUS_FUNCTIONS]] that the user has available at each `Organisation` where they have a role. ## Other responses - `400` — Where status code 400 (Bad Request) is returned then an [NHSDigital-OperationOutcome](https://fhir.nhs.uk/StructureDefinition/NHSDigital-OperationOutcome) will be included in the body, as detailed below. Check diagnostics property for specific information regarding the error. | issue.details.coding.code | issue.code | Coding System | Description | | ------------------------- | ---------- | ------------------------------------------------------------------ | ---------------------------------------------------------------| | REC_BAD_REQUEST | invalid | [BaRS Error Code](https://fhir.nhs.uk/CodeSystem/http-error-codes) | The query parameter _query is missing or has an invalid value. | - `401` — Where status code 401 (Unauthorized) is returned then an [NHSDigital-OperationOutcome](https://fhir.nhs.uk/StructureDefinition/NHSDigital-OperationOutcome) will be included in the body, as detailed below. Check diagnostics property for specific information regarding the error. | issue.details.coding.code | issue.code | Coding System | Description | | ------------------------- | ---------------- | ----------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | ACCESS_DENIED | | [APIM Error Code](https://fhir.nhs.uk/CodeSystem/NHSD-API-ErrorOrWarningCode) | The request could not be authenticated due to either no credentials being provided or the provided credentials no longer being valid. Callers receiving this code should reauthenticate. | - `403` — Where status code 403 (Forbidden) is returned then an [NHSDigital-OperationOutcome](https://fhir.nhs.uk/StructureDefinition/NHSDigital-OperationOutcome) will be included in the body, as detailed below. Check diagnostics property for specific information regarding the error. | issue.details.coding.code | issue.code | Coding System | Description | | ------------------------- | ---------- | ------------------------------------------------------------------ | ---------------------------------------------------------------------------------- | | REC_FORBIDDEN | forbidden | [BaRS Error Code](https://fhir.nhs.uk/CodeSystem/http-error-codes) | A call attempts to access or operate upon a resource without proper authorisation. | | ACCESS_DENIED | forbidden | [APIM Error Code](https://fhir.nhs.uk/CodeSystem/NHSD-API-ErrorOrWarningCode) | The request could not be authenticated due to insufficient credentials being provided. | - `406` — Where status code 406 (Not Acceptable) is returned then an [NHSDigital-OperationOutcome](https://fhir.nhs.uk/StructureDefinition/NHSDigital-OperationOutcome) will be included in the body, as detailed below. Check diagnostics property for specific information regarding the error. | issue.details.coding.code | issue.code | Coding System | Description | | ------------------------- | ------------- | ------------------------------------------------------------------ | --------------------------------------------------------------------------------------- | | REC_NOT_ACCEPTABLE | not-supported | [BaRS Error Code](https://fhir.nhs.uk/CodeSystem/http-error-codes) | The requested resource does not have a current representation that would be acceptable. | - `429` — Where status code 429 (Too Many Requests) is returned then an [NHSDigital-OperationOutcome](https://fhir.nhs.uk/StructureDefinition/NHSDigital-OperationOutcome) will be included in the body, as detailed below. Check diagnostics property for specific information regarding the error. | issue.details.coding.code | issue.code | Coding System | Description | | ------------------------- | ---------- | ----------------------------------------------------------------------------- | ---------------------------------- | | TOO_MANY_REQUESTS | throttled | [APIM Error Code](https://fhir.nhs.uk/CodeSystem/NHSD-API-ErrorOrWarningCode) | The rate limit has been reached. | The e-Referral service APIs limit the number of transactions you can make per unit of time. This protects our service against excessive use and denial-of-service (DoS) attacks, and is also to encourage you to use our APIs efficiently. Our standard rate limit for the production environment is 10 requests per second per application. If you go over the rate limit you'll receive a response with an HTTP status of 429 (Too Many Requests). Our path-to-live environments have very low rate limits. They are for functional testing only - you should not use them for [[HYPERLINK_PERFORMANCE_TESTING]]. If you have problems with rate limits, [[HYPERLINK_CONTACT_US]] to discuss your application design and volumetrics, and to see whether it's appropriate to raise your rate limit. If a 429 response is received, indicating a request has been rate limited, then you must back off and retry with exponentially increasing periods between requests. Once a request is successful again, then you may continue to send requests inline with the documented rate limits. Example: - Receive a 429 response - Wait 1s and resend, but still receive a 429 - Wait 2s and resend, but still receive a 429 - Wait 4s, request is successful - Return to normal request cadence - `500` — Where status code 500 (Internal Server Error) is returned then an [NHSDigital-OperationOutcome](https://fhir.nhs.uk/StructureDefinition/NHSDigital-OperationOutcome) will be included in the body, as detailed below. Check diagnostics property for specific information regarding the error. | issue.details.coding.code | issue.code | Coding System | Description | | ------------------------- | ---------- | ------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------- | | REC_SERVER_ERROR | exception | [BaRS Error Code](https://fhir.nhs.uk/CodeSystem/http-error-codes) | The server encountered an unexpected condition that prevented it from fulfilling the request. | - `503` — Where status code 503 (Service Unavailable) is returned then an [NHSDigital-OperationOutcome](https://fhir.nhs.uk/StructureDefinition/NHSDigital-OperationOutcome) will be included in the body, as detailed below. In response to receiving this status code, it is recommended that clients retry at a later time based on a returned `Retry-After` header when provided. | issue.details.coding.code | issue.code | Coding System | Description | | ------------------------- | ---------- | ------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------ | | REC_UNAVAILABLE | transient | [BaRS Error Code](https://fhir.nhs.uk/CodeSystem/http-error-codes) | A request to an internal component timed out whilst attempting to serve a response or the system is currently otherwise unavailable. | --- [API](https://skmtc.net/nhs/apis/e-referrals-service-api.md) · [All operations](https://skmtc.net/nhs/apis/e-referrals-service-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/nhs/e-referrals-service-api/versions/916969ea472f/schema)