Get verified candidate relationships
Overview
Use this endpoint to get verified relationship information for a user with a given NHS Number. This endpoint should NOT be used to retrieve established proxy roles; these should be queried from the GET /Consent endpoints.
You can query for RelatedPerson's in the following ways:
| Outcome | Query string value |
|---|---|
| Search for patient relationships for a candidate proxy | identifier={proxy identifier} |
| Search for candidate proxy relationships for a patient | patient:identifier={patient identifier} |
| Search for a specific verified candidate relationship for a given proxy and patient | identifier={proxy identifier}&patient:identifier={patient identifier} |
You must provide either the identifier={identifier} or patient:identifier={identifier} query string, or both, in your request.
Access modes
This endpoint supports the following access modes:
- Patient access
- Healthcare worker access
Sandbox test scenarios
You can test the following scenarios in our sandbox environment:
| Scenario | Request | Response |
|---|---|---|
| List Relationship | identifier=9000000017 | HTTP Status 200 List of relationships for the proxy |
| List Relationship and include patient's details | identifier=9000000017&_include=RelatedPerson:patient | HTTP Status 200 List of relationships for the proxy and includes patient data |
| List Patient Relationship | patient:identifier=9000000042 | HTTP Status 200 List of relationships for the patient |
| List Patient Relationship and include patient's details | patient:identifier=9000000042&_include=RelatedPerson:patient | HTTP Status 200 List of relationships for the patient and includes patient data |
| List Relationship and no relationships returned | identifier=9000000033 | HTTP Status 200 Empty bundle |
| Verify Relationship between proxy and patient | identifier=9000000017&patient:identifier=9000000009 | HTTP Status 200 Verified relationship between patient and proxy |
| Verify Relationship between proxy and patient and include patient's details | identifier=9000000017&patient:identifier=9000000009&_include=RelatedPerson:patient | HTTP Status 200 Verified relationship between patient and proxy and includes patient's details |
| Missing identifier | `` | 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 400 and INVALID_IDENTIFIER_VALUE error response |
| Malformed identifier & system | identifier=https://fhir.nhs.uk/Id/nhs-number/9730675929 | HTTP Status 400 and INVALID_IDENTIFIER_SYSTEM error response |
Sandbox constraints
The sandbox environment has the following constraints for this endpoint:
- Request headers are not tested. For example, X-Request-ID and X-Correlation-ID are disregarded.
Query parameters
The proxy's 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.
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.
Response
Information successfully returned.