--- title: "Update a proxy role" method: PATCH path: "/Consent/{id}" --- # Update a proxy role `PATCH /Consent/{id}` ## Overview Use this endpoint to update an existing proxy role. Supported update scenarios include: * Update the status and status reason, (optionally) providing an additional free text description * Update the policy rule * Update the end date, for time-bound access ## Request Requirements * The proxy role must exist and be identified by a valid ID * JSON Patch operations must be valid according to RFC 6902 * Status changes must use valid status codes from ### IMPORTANT: Business Rule Enforcement for `/status` updates If you update the `/status` of a role, you **MUST** also provide a corresponding update to the `/extension` path in the same patch array to provide the `statusReason`. An error will be returned if a request for a change of `/status` does not include a status reason. The values for `/status` and `statusReason` are validated against a proxy role lifecycle to ensure that the transition between the existing and requested status is valid. An error will be returned if the requested transition is not valid. ## 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 | | ------------------------------- | ----------------------------------------------------------------------------------------------- | ------------------------------------------------------------- | | Successful status update | Valid patch changing status to 'active', request with id '74eed847-ca25-4e76-8cf2-f2c2d7842a7a' | HTTP Status 200 and OperationOutcome | | Successful access level update | Valid patch modifying the role end date, request with id '6b71ac92-baa3-4b76-b0f5-a601257e2722' | HTTP Status 200 and OperationOutcome | | Multiple valid changes | Valid patch with multiple operations, request with id '43003db8-ffcd-4bd6-ab2f-b49b9656f9e5' | HTTP Status 200 and OperationOutcome | | Valid OTHER reason code with free text | Patch with reason code 'OTHER' and free text, id='a1b2c3d4-e5f6-4789-a0b1-c2d3e4f5a6b7'| HTTP Status 200 and OperationOutcome | | Non-OTHER reason code without free text | Patch with a reason code other than 'OTHER', no free text, id='b2c3d4e5-f6a7-4890-b1c2-d3e4f5a6b7c8' | HTTP Status 200 and OperationOutcome | | Non-OTHER reason code with free text | Patch with a reason code other than 'OTHER', with free text, id='c3d4e5f6-a7b8-4901-c2d3-e4f5a6b7c8d9' | HTTP Status 200 and OperationOutcome | | Invalid patch format | Malformed JSON patch document, request with id '849ea584-2318-471b-a24c-cee1b5ad0137' | HTTP Status 400 and INVALID_PATCH_FORMAT error response | | Invalid path | Patch targeting non-existent element, request with id '01abb0c5-b1ac-499d-9655-9cd0b8d3588f' | HTTP Status 400 and INVALID_PATCH_PATH error response | | Invalid status code | Patch with invalid status value, request with id '78c35330-fa2f-4934-a5dd-fff847f38de5' | HTTP Status 422 and INVALID_STATUS_CODE error response | | Invalid status reason | Patch with invalid status reason value, request with id '51fb4df5-815a-45cd-8427-04d6558336b7' | HTTP Status 422 and INVALID_STATUS_REASON error response | | Resource not found | Patch for non-existent Consent, request with an id not listed here | HTTP Status 404 and RESOURCE_NOT_FOUND error response | | Invalid state transition | Patch attempting invalid status change, request with id '7b7f47b8-96e5-43eb-b733-283bf1449f2c' | HTTP Status 422 and INVALID_STATE_TRANSITION error response | | Missing free text for OTHER reason code | Patch with reason code 'OTHER' but missing free text, id='d4e8a6f2-1c3b-4a7e-9d2f-8b5c7e9f1a3d' | HTTP Status 400 and MISSING_FREE_TEXT_FOR_OTHER error response | | Missing grantor | Patch attempting to set status to 'active' without grantor extension, id='90957744-b971-496e-b7c3-ab971868ce14' | HTTP Status 400 and MISSING_GRANTOR error response | | Missing grantor valueReference | Request with grantor extension but missing valueReference, id='7e764160-38b6-41eb-9012-a3e476cbc517' | HTTP Status 400 and MISSING_GRANTOR_REFERENCE error response | | Missing grantor valueIdentifier | Request with grantor extension but missing valueIdentifier, id='faefd8c5-5e24-4415-8252-96e9241c7e78' | HTTP Status 400 and MISSING_GRANTOR_IDENTIFIER error response | | Invalid grantor ODS code value | Request with grantor extension but missing/empty/invalid ODS code, id='b68cbfc8-ccc2-48ad-b97b-b7410d773dc1' | HTTP Status 422 and INVALID_GRANTOR_VALUE error response | | Invalid grantor identifier system | Request with grantor extension but wrong/missing identifier system, id='fd189522-68e5-42dc-b44c-989be0eaa2bf' | HTTP Status 422 and INVALID_GRANTOR_SYSTEM error response | ### Sandbox constraints The sandbox environment has the following constraints for this endpoint: - Request body is not validated. - Request headers are not tested. - No proxy role is updated. ## Path parameters - `id` string, uuid, required ## Headers - `Authorization` string, ^Bearer\ [[:ascii:]]+$, required - `X-Request-ID` string, uuid, required - `X-Correlation-ID` string, uuid ## Response `200` Consent resource successfully updated ## Other responses - `4XX` — Errors will be returned for the first error encountered in the request. For details, see the `diagnostics` field of error. An error occurred as follows: | HTTP status | Error code | Description | | ----------- | --------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- | | 400 | `MISSING_VALUE` | Missing header or parameter. For details, see the `diagnostics` field. | | 400 | `MISSING_GRANTOR` | Grantor extension is required when creating or activating a consent with status "active". For details, see the `diagnostics` field. | | 400 | `MISSING_GRANTOR_REFERENCE` | Grantor extension reference is required when creating or activating a consent with status "active". For details, see the `diagnostics` field. | | 400 | `MISSING_GRANTOR_IDENTIFIER`| Grantor extension identifier is required when creating or activating a consent with status "active". For details, see the `diagnostics` field. | | 400 | `INVALID_PATCH` | Invalid patch. | | 400 | `INVALID_VALUE` | Invalid Parameter or Invalid operation. | | 401 | `ACCESS_DENIED` | Missing or invalid OAuth 2.0 bearer token in request. | | 403 | `FORBIDDEN` | Access denied to resource. | | 405 | `METHOD_NOT_ALLOWED` | The method is not allowed. | | 408 | `TIMEOUT` | Request timed out. | | 409 | `DUPLICATE_PATCHES` | Two or more patches use same path. | | 415 | `UNSUPPORTED_MEDIA` | Unsupported media type. | | 422 | `INVALID_EXTENSION` | Invalid extension. | | 422 | `INVALID_PATCH_PATH` | Invalid patch path. | | 422 | `INVALID_STATUS_CODE` | Invalid status code. | | 422 | `INVALID_STATUS_REASON` | Invalid status reason. | | 422 | `INVALID_STATE_TRANSITION` | Invalid state transition. | | 422 | `INVALID_LEGAL_BASIS_CODE` | Invalid legal basis code. | | 422 | `INVALID_END_DATE` | End date is invalid. | | 422 | `INVALID_GRANTOR_VALUE` | Invalid grantor identifier value. For details, see the `diagnostics` field. | | 422 | `INVALID_GRANTOR_SYSTEM` | Invalid grantor system value. For details, see the `diagnostics` field. | | 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. | --- [API](https://skmtc.dev/nhs/apis/validated-relationships-service-api.md) · [All operations](https://skmtc.dev/nhs/apis/validated-relationships-service-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/nhs/validated-relationships-service-api/revisions/83ee1febfe14/schema)