API Authenticating Patients
Your app can create new accounts for patients, connect to an existing patient and check for patient’s existence on Patient Vault. Patients authenticate with your app using their email and a PIN number, once they authenticate an access token will be granted to your app, which you can use later to call other methods related to the patient’s account on Patient Vault.
Patients have complete control over their passwords and PINs. At any time a patient could change either one, but your access token will not be affected by this. The patients also have control over the access token granted to you and they could revoke it if they so decide. In this case your app will have to re-connect to the patients account by obtaining their PIN number again.
Once you connect or create an account for a patient, your app will appear on the Patient’s list of apps. Your app will be granted the necessary permissions to connect and perform basic operations.
Figure 1 – Patient Vault Account Process
This diagram illustrates the process in which your app should handle the creation and connection of patients accounts. Green steps indicate API calls to Patient Vault’s API.
For this scenario, we will learn how to work with the API to integrate patient authentication on your app. In this scenario the patient is visiting an organization that wants to post documents to the patient’s Patient Vault’s account.
For this the app needs to authenticate the user and obtain an access token. In this case the organization is using your app, and a user in the organization will create the patients account and later re-connect it.
These are the persons on this scenario:
- A patient without an existing Patient Vault account, let’s call him John.
- An organization that wants to post documents to John’s account, let’s call them GetWell Clinic.
- A user of your app who is also an employee of GetWell Clinic, let’s call her Mary.
Let’s see how easy it is to create a new account for John using Patient Vault:
Getting your test environment ready
You will need a Patient Vault API Key and Dev Key before you start using the API, which you can request by sending an email to firstname.lastname@example.org.
To get familiarized with the API we’ll use POSTMAN, which can be obtained from: http://www.getpostman.com/
Once you download and install POSTMAN, import the following file into your collections:
Patient Vault Public API.json
Now you need to setup your environment, this allows POSTMAN to replace regularly used parameters in the request with specified values, so that you don’t have to enter them every time.
Click on the environment icon:
Next, click manage environments
For your convenience here’s an empty environment, all you need to do is import it and put your Api Key and Dev Key. Don’t worry about the rest of the variables for now.
This will include your API key and DEVKEY in the header of all requests you make, thus authenticating your app:
That’s it! You are now set to start using the API.
Steps for using the account API
- Check if John’s email exists on Patient Vault.
- Since John does not have an account, your app needs to ask Mary to ask John for a PIN to create the account with.
- You store the access token for the newly created account on your app
Checking to see if a patient account exists
The first step in the process is checking to see if John already has an account with Patient Vault. To do this you have to call the AccountExists method of the API.
On POSTMAN, go to the Account category and click the Account – Exists method. The method has these parameters:
The response to this call will be this:
Errors: [ ]
Warnings: [ ]
The Exists property on the response will indicate if the account exists or not.
Registering the patient on Patient Vault
Since John does not have an account, your app needs to create one. First you should indicate to Mary that John does not have an account in Patient Vault and if she would like to create one for him, your app then should ask Mary for a Pin to use on John’s account.
Once you do that on your app, you can call the AccountCreate method of the API. On POSTMAN go to the Account category and click the Account – Create method.
Your request would look like this one: