Custom REST APIs

Note: It is recommended that the FHIR APIs are used for any new integrations.

This tutorial assumes that an organisation has integrated or is developing its own mail management solution to include the following:

• Create new patients on PKB.

• Send electronic documents to the patient record.

• Invite the patients to register on PKB

• Monitor the read status of sent documents.

• Monitor changes to registration status of the patients

This is the PKB recommended implementation as of publishing date (June 2019) however the APIs and workflow will be refined in future releases.

A typical mail management workflow is proposed below:

Example User Journey: Mr Read Richards

1. Document received

A document (appointment letter) is received to the mail management solution. The letter is for ‘Read Richards’ - NHS 5760678914. Optional local exclusion rules may apply before continuing. An example local exclusion rule may be that the postal address is for an HMP address. The mail management solution determines the letter should not be excluded.

Open

2. Record creation

The mail solution determines the patient is not known and should be created on PKB. In the example workflow this is indicated by the ‘Patient in Reg Repo?’ decision point. The ‘Reg Repo’ is proposed to be a local table holding a list of known patients and their registration / invitation details. ‘Read Richards’ is not on the ‘Reg Repo’.

Open

HL7 API: The mail management solution sends an HL7 ADT^A28 with verified NHS number and required PID information to create the record. Reference HL7 ADT A28.

MSH|^~\&|POPRECORD|POPRECORD|HL7API|PKB|201904241033||ADT^A28|186b1b87-c438-443c-b254-3e69e5c7edff|P|2.4

PID|||5760678914^^^NHS^NH{status:01}||Richards^Read^^Mr||20000915|M|||1 Main Street^Town^City^County^NE1 1XC^|||||||||||A||||||||N|

The patient details are added to a local table referred to as ‘Reg Repo’. This record will be maintained and updated as the patient registration journey continues. This is indicated in the typical workflow by 'Update Reg Repo'.

HL7 API: The mail management solution sends an HL7 MDM^T02 to add the received document to the patient record. Reference HL7 MDM T02. The document id is : 78ffb8b4-566c-4a3e-ba07-adb04b798d8d

MSH|^~\&|POPRECORD|POPRECORD|HL7API|PKB|201904241033||MDM^T02|fc60f017-8cb0-4787-b128-b915946ef63b|P|2.4

PID|||5760678914^^^NHS^NH{status:01}||Richards^Read^^Mr||20000915|M|||1 Main Street^Town^City^County^NE1 1XC^|||||||||||A||||||||N|

TXA|1|AL|ED|201904241033|^^^^^|||||||78ffb8b4-566c-4a3e-ba07-adb04b798d8d||||Appointment Letter for 19-05-2019 09:00.pdf|AU

OBX|1|ED|||^TEXT^PDF^Base64^JVBERi0xLj……...||||||

PV1||O|^^^^^^^^

The document details are added to a local table referred to as ‘Unread Repo’. This record will be maintained and updated when the document is either read or posted. This is indicated in the typical workflow by 'Update Unread Repo'.

3. Invite the new patient to register.

The patient ‘Read Richards’ is a new patient and is eligible for invite. The mail management solution will call the PKB APIs to generate invitation tokens.

Note: ‘Eligible for invite?’ - optional locally defined rules may be in place to determine if a patient is eligible for invite. Details on the ‘Reg Repo’ may be interrogated for these local rules. PKB suggests the rules could be:

• Not in ‘Reg Repo’ or

• Status = NOT_REGISTERED and last invite sent > x months ago

Rest API: ‘GET byNationalId’. The mail management solution uses their OAUTH2 access token (system id) to retrieve the PKB ID (3594342) for ‘Read Richards’ (NHS: 5760678914). Reference OAUTH walkthrough (system client ID), REST getNationalNumberByPatientId

Request

curl -X GET --header 'Accept: application/json' --header 'Authorization: Bearer <access token>' 'https://sandbox.patientsknowbest.com/json/v2- beta/users/byNationalId/5760678914/NHS_NUMBER'

Response

The mail management solution records the PKB ID locally. In the typical workflow this is indicated by ‘Update Reg Repo’. The PKB ID will not change for the user and thus can be stored for future use.

Rest API: ‘GET recordAccessToken’. The mail management solution uses their OAUTH access token (system client id) to get a set of invitation tokens for user 3594342 (Read Richards). The tokens are valid for 30 days. Reference: REST recordAccessToken

Request

curl -X GET --header 'Accept: application/json' --header 'Authorization: Bearer <access token>' 'https://sandbox.patientsknowbest.com/json/v1/users/3594342/recordAccessToken'

Response

The mail management solution records the returned invitation details locally. In the typical workflow this is indicated by ‘Update Reg Repo’. The response status is neither ‘REGISTERED’ or ‘DEAD’ so the mail solution sends the letter plus invitation to the patient by post. An example invitation letter template is here: letters

4. The patient ‘Read Richards’ registers on PKB using the invite token and access token sent to him by the mail management solution.

5. The mail management solution periodically (e.g. overnight) queries PKB for changes to patient registration status and updates a local table...referred in the typical workflow as ‘Update Reg Repo’

HL7 API: The mail management solution sends an HL7 QRY^A19 with a QRD.9 of STA and a QRF.2 of a relevant date to retrieve registration status updates of patients in the organisation. Reference HL7 QRY A19 (STA).

Note: This query is primarily intended to be used as a delta query to build and maintain a local reference table of patients and their registration status within PKB. In the typical workflow this is referred to as ‘Update Reg Repo’. Note: an initial one off full QRY^A19 of patients and their statuses may have been run on deployment to build the ‘Reg Repo’ base version.

Query Request

MSH|^~\&|App|SendingInst|HL7API|PKB|201904262300||QRY^A19|ABC0000000001|P|2.4

QRD||||_queryId|||||STA||

QRF||<HL7 timestamp representing yesterday>

Query Response

MSH|^~\&|HL7API|PKB|App|ReceivingInst|201904262300||ADR^A19|E|P|2.4

MSA|AA|ABC0000000001

QRD||||_queryId|||||STA

PID|||5760678914^^^NHS^NH||RICHARDS^READ^^||20000915||||^^^^NE1 1XC

ZID|1fd2a0f6-890b-4f68-9fa1-65342f649771|REGISTERED^201904261300

...etc...

...etc...

The response tells the mail management solution ‘Read Richards’ is now REGISTERED. This is updated in the ‘Reg Repo’ and can be referenced for any future letters received for him.

6. The example patient ‘Read Richards’ reads his appointment letter in PKB.

7. The mail management solution can monitor the read status of the documents sent by the organisation. The mail management solution periodically (e.g. overnight) queries to find documents read on PKB since an indexed date (indexed date is the date the document was received on PKB). Read documents are updated in the local table. In the typical workflow this is referred to as ‘Update Unread Repo’.

The mail management solution may choose to physically post documents that have not been read beyond a threshold date. E.g. if a document is not read after 2 days then the solution may choose to post the letter.

FHIR API: Using an OAUTH access token (user client id) the mail management solution uses the FHIR DocumentReference resource to determine the read status of documents. A document is considered READ when the patient opens the message on PKB. Reference OAUTH walkthrough (user client ID), FHIR DocumentReference

PKB will provide you with the source_organisation parameter used below. This parameter will not change.

Request

https://sandbox.patientsknowbest.com/fhir/DocumentReference?indexed=<yyyy-mm-dd>&document- status=http://fhir.patientsknowbest.com/codesystem/document-status%7CREAD&source-organisation=Organization/<source-organisation>

The response indicates that the appointment letter sent to Read Richards (78ffb8b4-566c-4a3e-ba07-adb04b798d8d) has now been read.

Response