Update a proxy role
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 http://hl7.org/fhir/consent-state-codes
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
The logical id of the Consent resource
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
Consent resource successfully updated