Mass Registration Implementation Guide

This tutorial assumes that an organisation would like to mass create and invite patients to register for their PKB records including

  • Mass creation/update via CSV 

  • Mass invitation utilizing tokens for delivery via

    • Post in partnership with a mail management company or in house

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

A typical mass registration workflow is proposed below:

Example User Journey: Mr Read Richards

1. Record creation

The record for Read Richards is created along with the other records via the CSV Mass Upload process.

2. Invite the new patient to register.

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

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


    curl -X GET --header 'Accept: application/json' --header 'Authorization: Bearer <access token>' '   beta/users/byNationalId/5760678914/NHS_NUMBER'



    "id": "3594342",


    "firstName": "Read",

    "lastName": "Richards",

    "dob": "2000-09-15",

    "dateDeceased": null,


    "postalCode": "NE1 1XC",


    "nationalIds": [


    "value": "5760678914",

     "name": "NHS number",

     "countryCodes": [







Rest API: ‘GET recordAccessToken’.  The customer 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


    curl -X GET --header 'Accept: application/json' --header 'Authorization: Bearer <access token>'          ''



    "invitationCode": "NKcYiAciBU",

    "token": "KVPnrFYPay",



3. Invite delivery to citizen


The customer/mail management solution sends the letter plus invitation to the patient by post. An example invitation letter template is here: letters


The customer uploads a spreadsheet of phone numbers and other details along with an invite template to Gov.UK Notify for SMS invitation. This option is best when the customer possess verified mobile phone numbers. 

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