How to request a change to a patient's permissions
There is a single main use case available from the user permissions API using the POST HTTP request method i.e. requesting a change to a patient's permission. This can be further broken down into the following three cases:
- requesting additional access to the appointments
- requesting additional access to the prescriptions
- requesting additional access to the medical record
Prerequisites
Consumer
The consumer must make a request to get a patient's permissions prior to making any other PFS API requests. This ensures that the patient has online access enabled, see New online patient access for additional details.
Supplier
The supplier must ensure the patient has online access enabled. This is performed during the authorisation process of the patient's request by the GP supplier system. See New online patient access for additional details.
Common concerns
A request to change the level of access a patient has can be made. Requests must be to increase the level of access. Lowering the level of access is not currently supported and will be rejected.
Each use case has the same basic request format providing information on the type of permission and the access level the request is for. For medical records there is an additional property so it is known whether the medical record's current or historical permissions should be updated.
Request workflow
A POST request is made to the user permissions API with the appropriate payload based on the request the patient wants to make. Each request will be validated and if the validation passes, the request will be added to the GP system's workflow where it will be processed at some point in the future. Requests added to the workflow will be responded to with a state of pending.
Rejected requests are not added to the GP system's workflow. The text included in the response to a rejected request explains the reason for the rejection, this should be under details.text in the OperationOutcome. This should be displayed to the patient.
Request handling
Pending requests will be listed on the response to getting a patients permissions.
If a request is a duplicate, it is deduplicated by the GP system, with the original request being preserved.
If multiple requests are made (and accepted) they are combined within the workflow and reviewed together by a healthcare worker.
Use case 1 - Additional access to appointments
Access to the appointments service is represented by three levels:
| level | description |
|---|---|
none |
no access |
view |
view only |
manage |
view, book, amend & cancel existing appointments |
A request to update the access level for the appointments service requires a POST request to the API with a body containing JSON.
An example request to increase the access level a patient has to manage for the appointments service can be seen below.
{
"permissionType" : "appointments",
"accessLevel" : "manage"
}
Use case 2 - Additional access to prescriptions
Access to the prescriptions service is represented by three levels:
| level | description |
|---|---|
none |
no access |
view |
view only |
manage |
view, order, amend & cancel existing prescriptions |
A request to update the access level for the prescriptions service requires a POST request to the API with a body containing JSON.
An example request to increase the access level a patient has to manage for the prescriptions service can be seen below.
{
"permissionType" : "prescriptions",
"accessLevel" : "manage"
}
Use case 3 - Additional access to medical record
Access to the medical record is represented by five levels:
| level | description |
|---|---|
none |
no access |
summary |
summary record access |
detailed |
detailed coded record access |
documents |
documents access |
full |
full access |
Refer to How to get a patient's permissions for details on what each level provides access to.
A request to update the access level for the medical record requires a POST request to the API with a body containing JSON.
An example request to increase the access level a patient has to full for their current medical record can be seen below.
{
"permissionType" : "medicalRecord",
"medicalRecordType": "current",
"accessLevel" : "full"
}