--- title: "Get verified candidate relationships" method: GET path: "/RelatedPerson" --- # Get verified candidate relationships `GET /RelatedPerson` ## 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 - `identifier` string, token - `patient:identifier` string, token - `_include` string[] ## Headers - `Authorization` string, ^Bearer\ [[:ascii:]]+$, required - `X-Request-ID` string, uuid, required - `X-Correlation-ID` string, uuid ## Response `200` Information successfully returned. ## Other responses - `4XX` — Errors will be returned for the first error encountered in the request. An error occurred as follows: | HTTP status | Error code | Description | | ----------- | ---------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- | | 400 | `MISSING_IDENTIFIER_VALUE` | Missing RelatedPerson NHS number. | | 400 | `INVALID_IDENTIFIER_SYSTEM` | Invalid identifier system. | | 400 | `INVALID_VALUE` | Invalid Parameter or Invalid operation. | | 400 | `INVALID_PATIENT_IDENTIFIER_VALUE` | Malformed Patient NHS number. | | 400 | `INVALID_IDENTIFIER_VALUE` | Malformed RelatedPerson NHS number. | | 401 | `ACCESS_DENIED` | Missing or invalid OAuth 2.0 bearer token in request. | | 403 | `FORBIDDEN` | Access denied to resource. | | 404 | `INVALIDATED_RESOURCE` | Resource that has been marked as invalid was requested - invalid resources cannot be retrieved | | 405 | `METHOD_NOT_ALLOWED` | The method is not allowed. | | 408 | `TIMEOUT` | Request timed out. | | 429 | `THROTTLED` | You have exceeded your application's [rate limit](https://digital.nhs.uk/developer/guides-and-documentation/reference-guide#rate-limits). | - `5XX` — Errors will be returned for the first error encountered in the request. An error occurred as follows: | HTTP status | Error code | Description | | ----------- | -------------------------- | ------------------------------------------------------------ | | 500 | `SERVER_ERROR` | An unexpected internal server error has occurred. | | 501 | `NOT_IMPLEMENTED` | API Endpoint not implemented. | | 502 | `BAD_GATEWAY` | Connection to the backend service failed. | ## Changes - **2026-03-06** `aeaecd373dba` — 2 breaking, 46 info - the `issue/items/expression` response's property type/format changed from `string`/`` to `array`/`` for status `4XX` - the `issue/items/expression` response's property type/format changed from `string`/`` to `array`/`` for status `5XX` - removed the `business-rule` enum value from the `issue/items/code` response property for the response status `4XX` - removed the `business-rule` enum value from the `issue/items/code` response property for the response status `5XX` - …44 more - …earlier changes not shown [Full history](https://skmtc.dev/nhs/apis/validated-relationships-service-api-2/changes/RelatedPerson/get.md) --- [API](https://skmtc.dev/nhs/apis/validated-relationships-service-api-2.md) · [All operations](https://skmtc.dev/nhs/apis/validated-relationships-service-api-2/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/nhs/validated-relationships-service-api-2/revisions/f212e0c81005/schema)