Mass registration

Why the API

This implementation guide is centered 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 decryption rights to this patient’s record can use the new PKB REST API call to generate a patient-specific unique user id and decryption token for that record. For example a hospital can create a letter to send to the patient’s home with the ID and token.
  3. The recipient of the letter uses ID and token to start registration on the PKB web site.
  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 a integration with letter printing software (such as Synertec):


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

  • PKB ID of the patient
Return - success:
  • invitationCode [string]
  • token [string]
Return - failure: appropriate http error code &
  • REGISTERED errorMessage [Registration already completed]
  • errorMessage [string with descriptive details of error]
  • The call will be scoped to TEAMCOORD and System Client ID callers
  • PKB ID can be retrieved using existing call GET /v2-beta/users/byNationalId/{nationalId}/{nationalIdType}
  • PKB Record must have patient identifier and date of birth present in order for token to be returned
  • Status return 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.
    • Registration already completed - a record exists, registration has been completed
    • Record missing a date of birth - tokens can not be generated for records without DOB as this is the 2FA challenge required to register an account
    • Patient has died
  • Tokens will time-expire (30 days) from the time of generation
  • Tokens can be generated at any time using this call - new id/token will be generated each time, existing id/token will not be invalidated (until they time-expire)
  • If a record already exists and was created in a different org a 401 response will be returned.
  • Registration is performed against parameters may be passed into this url for form pre-population if desired. 
Relevant API calls