Get proxy roles
Overview
Use this endpoint to get the details about proxy roles, including current status, based on a provided NHS Number.
Either performer:identifier or patient:identifier request parameters must be provided. performer:identifier and patient:identifier can be used together.
You can (optionally) include a status={status} query string parameter to filter the response to records with a given status bound to the http://hl7.org/fhir/consent-state-codes CodeSystem e.g. status=active or status=proposed,active.
You can (optionally) include the _include=Consent:performer request parameter to include the proxy's details in the response.
You can (optionally) include the _include=Consent:patient request parameter to include the patient's details in the response.
Access modes
This endpoint supports the following access modes:
- Patient access
- Healthcare worker access
- Application-restricted access
Sandbox test scenarios
You can test the following scenarios in our sandbox environment:
| Scenario | Request | Response |
|---|---|---|
| Multiple proxy relationships filtered by 'active' status including details | performer:identifier=9000000017&_include=Consent:patient&_include=Consent:performer&status=active | HTTP Status 200 Bundle containing a multiple active proxy relationships including performer and patient details |
| Multiple proxy relationships filtered by 'inactive' status | performer:identifier=9000000017&status=inactive | HTTP Status 200 Bundle containing a multiple inactive proxy relationships |
| Multiple proxy relationships filtered by 'proposed' and 'active' status | performer:identifier=9000000017&status=proposed,active | HTTP Status 200 Bundle containing a multiple proposed and active proxy relationships |
| Multiple proxy relationships without filtering and details | performer:identifier=9000000022 | HTTP Status 200 Bundle containing a multiple proxy relationships without details |
| Multiple proxy relationships including performer details | performer:identifier=9000000022&_include=Consent:performer | HTTP Status 200 Bundle containing a multiple proxy relationships including performer details |
| Multiple proxy relationships including patient details | performer:identifier=9000000022&_include=Consent:patient | HTTP Status 200 Bundle containing a multiple proxy relationships including patient details |
| Multiple proxy relationships including performer and patient details | performer:identifier=9000000022&_include=Consent:patient&_include=Consent:performer | HTTP Status 200 Bundle containing a multiple proxy relationships including performer and patient details |
| Multiple proxy relationships, single patient | patient:identifier=9000000100 | HTTP Status 200 Bundle containing a multiple proxy relationships including performer and patient details |
| Multiple proxy relationships, single patient, including proxy details | patient:identifier=9000000100&_include=Consent:performer | HTTP Status 200 Bundle containing a multiple proxy relationships including proxy details |
| Multiple proxy relationships, single patient, including patient details | patient:identifier=9000000100&_include=Consent:patient | HTTP Status 200 Bundle containing a multiple proxy relationships including patient details |
| Multiple proxy relationships, single patient, including proxy and patient details | patient:identifier=9000000100&_include=Consent:patient&_include=Consent:performer | HTTP Status 200 Bundle containing a multiple proxy relationships including proxy and patient details |
| No proxy relationships | performer:identifier=9000000025&_include=Consent:patient&_include=Consent:performer&status=active | HTTP Status 200 empty bundle |
| A single proxy relationship between consenting adults | performer:identifier=9000000010 and/or patient:identifier=9000000005 | HTTP Status 200 Bundle containing a single proxy relationship |
| A single proxy relationship between consenting adults including details | performer:identifier=9000000010 and/or patient:identifier=9000000005&_include=Consent:patient&_include=Consent:performer | HTTP Status 200 Bundle containing a single proxy relationship including performer and patient details |
| A single proxy relationship between a mother and child | performer:identifier=9000000019 and/or patient:identifier=9000000009 | HTTP Status 200 Bundle containing a single proxy relationship |
| A single proxy relationship between a mother and child including details | performer:identifier=9000000019 and/or patient:identifier=9000000009&_include=Consent:patient&_include=Consent:performer | HTTP Status 200 Bundle containing a single proxy relationship including performer and patient details |
| A single proxy relationship between a mother and child with legal basis unknown | performer:identifier=9000000111 and/or patient:identifier=9000000119 | HTTP Status 200 Bundle containing a single proxy relationship with legal basis unknown |
| Invalid status parameter | performer:identifier=9000000019 and/or patient:identifier=9000000009&status=test | HTTP Status 422 and INVALID_PARAMETER error response |
| Invalid include parameter | performer:identifier=9000000019 and/or patient:identifier=9000000009&_include=test | HTTP Status 422 and INVALID_PARAMETER error response |
| Missing identifier | patient:identifier=9000000009 | HTTP Status 400 and MISSING_IDENTIFIER_VALUE error response |
| Invalid identifier | identifier=900000000 Note: This identifier is 9 characters long, too short to be NHS Number | HTTP Status 422 and INVALID_IDENTIFIER_VALUE error response |
| Invalid identifier system | identifier=https://fhir.nhs.uk/Id/nhs-number/9730675929 | HTTP Status 422 and INVALID_IDENTIFIER_SYSTEM error response |
| No performer record found | identifier=9000000999 | HTTP Status 404 and INVALIDATED_RESOURCE error response |
| GP Practice not found | identifier=9000000012 | HTTP Status 404 and GP_PRACTICE_NOT_FOUND error response |
Sandbox constraints
The sandbox environment has the following constraints for this endpoint:
- Request headers are not tested. X-IM1-Connection-Params, X-Request-ID and X-Correlation-ID are disregarded.
Query parameters
The performer's (Proxy) NHS number. For more information on FHIR tokens in general, see here.
The patient's NHS number. For more information on FHIR tokens in general, see here.
Specify one or more status values to filter the records returned in the bundle.
Supports FHIR search conventions:
- OR — comma-separated values within a single parameter, e.g. status=active,proposed returns records with status active or proposed.
- AND — repeated parameters, e.g. status=active&status=proposed. For a single-valued field like status, AND groups are intersected; disjoint groups will return no results.
- AND of ORs — e.g. status=active,proposed&status=inactive.
Valid status values are bound to the http://hl7.org/fhir/consent-state-codes CodeSystem: proposed, active, rejected, inactive, entered-in-error.
Include referenced resources in the bundle response by specifying one or more _include parameters. Further info here.
Headers
A globally unique identifier (GUID) for the request, which we use to correlate logs through different components. Must be a universally unique identifier (UUID) (ideally version 4). Mirrored back in a response header.
An optional ID which you can use to track transactions across multiple systems. Must be a universally unique identifier (UUID) (ideally version 4). Mirrored back in a response header.
An optional ; delimited string containing parameters required to refresh proxy relationships from GPIT supplier systems. Parameters that comprise this string are:
- IM1 User Connection token
- ODS Code
Response
Information successfully returned.