Mass registration: Custom REST APIs

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

Why the API

This implementation guide is centred on the Record Access Token API call, available from our custom REST API.

The API call allows mass registration of patients by letter-printing companies, patient kiosk vendors and hospital IT departments.

The faster an organisation registers patients the faster the return on investment. This API allows registering patients without needing face-to-face appointments. Instead the registration details for patients can go to each patient’s home using automatically generated letters from the institution’s existing database about the patient.

Please also review the letter-based mass registration guidance on our deployment site, which includes additional information, including a sample letter.

How it works

Here are the steps:

  1. The organisation creates a record for their patient as they normally do (e.g. via HL7 ADT A28 or CSV manual upload). The organisation can immediately send data to populate the record, for example with laboratory test results and clinic appointments.

  2. Any user with access to this patient’s record can use the new PKB REST API call to generate a patient-specific unique invitation code and secret token for that record. For example, a hospital can use these values to create an invitation letter, SMS or email to send to the patient.

  3. The patient uses the invitation code and secret token to start registration on the PKB web site - refer to Join PKB URLs.

  4. For security, PKB tests the registering user’s knowledge of the patient’s date of birth.

  5. The patient enters their email address and password.

  6. The patient can now log into the PKB web site to see their data and send messages to their clinical team.

Here is an example of the steps using an integration with letter printing software (such as Synertec):

Specification

GET /v1/users/{PKB ID}/recordAccessToken

Scope

This API operation can be called either by Team Coordinators directly, or else by System Clients.

Parameters

Response

On success, three parameters will be returned.

  • invitationCode [string]. This is the first piece of information the patient will need to enter to register.

  • token [string]. This should also be sent to the patient; they will need to enter it to register.

  • status [string]. Possible values:

    • NOT_INVITED_NOT_REGISTERED. A record exists for the patient, no invitations have been sent, registration has not been completed.

    • INVITED_NOT_REGISTERED. A record exists, an email address has been added and an invitation has been sent to that email address. Registration has not been completed. This does not recognise if a token has previously been generated to invite a patient.

Here is an example of a successful response:

{ "invitationCode": "wtXdUSnm4E", "token": "BqqdG2xNgB", "status": "INVITED_NOT_REGISTERED" }

On failure, an appropriate HTTP error code will be returned and the response body will contain error information. Reasons a call might not succeed include (but are not limited to) the following:

  • Registration already completed. A patient cannot be invited to register if they have already registered.

    • Record missing a date of birth. A patient cannot be invited if PKB does not have have a record of their Date Of Birth. This is needed as the 2FA challenge required to register an account.

    • Patient deceased. A deceased patient cannot be invited to register.

Here is an example response for a patient who is already registered:

{ "statusCode": 400, "errorMessage": "Registration already completed", "developerMessage": null, "errorDetails": [ { "errorCode": "invitation.patient.status", "messages": [ "Registration already completed" ] } ] }

Notes

Relevant API calls

 

© Patients Know Best, Ltd. Registered in England and Wales Number: 6517382. VAT Number: GB 944 9739 67.

This API specification and design is licensed under a Creative Commons Attribution 4.0 International License.