IAL2 Identity Verification iframe API

IAL2 Identity Verification iframe API is a NIST 800-63-3 IAL2 compliant identity proofing API that enables developers to verify the identity of users who sign up for their platform.

The National Institute of Standards and Technology’s (NIST) Special Publication 800-63-3: Digital Identity Guidelines calls for collecting and assessing multiple pieces of user asserted evidence to make an identity proofing decision as a way to better guard against identity fraud.

Use cases

This API should be used under the following circumstances:

  • An IAL2 verified identity is required for patient request to their personal medical records.
  • Any signup or workflow that requires IAL2 level of identity proofing.

OAuth 2.0

OAuth 2.0 protocol is used to secure Health Gorilla's API. Your application must get an access token and include it into the request to access the desired API endpoint. In order to be granted access to IAL2 Identity Verification APIs described in this document your application needs to include ial2 scope for the access token.

You must follow OAuth 2.0 guidelines when making calls to Health Gorilla API.

Health Gorilla endpoints are accessible only over SSL and plain text HTTP calls are rejected.

Patient Access iframe

The process for iframe support for ID proofing is performed under the OAuth user session. The result of the operation is a new Patient resource created within the OAuth user's practice.

ID proofing related fields:

Field

Value

Description

lexId

string

IAL2 verified ID used when patient is requesting their own medical records.

ial2PassedDate

date

Date when user was ID proofed.

iframe URL parameters

In order to start identity proofing wizard in the iframe or standalone browser window you need to point it to the following URL: https://www.healthgorilla.com/embedded_idproofing This URL accepts the following parameters:

Field

Value

Description

access_token

string

OAuth access token

callback

URL

HTTPS URL where the patient will be directed at the end of the flow. These parameters will be passed in the URL:

result - result of ID verification

  • succeed = ID verification successfully passed
  • failed = ID verification failed
  • cancelled = process cancelled by the user
  • linkExpired = link from SMS expired

    message - text representation of result
    patientID - patient instance ID (provided only if verification passed)

email

String

Patient email. Required

Example iframe URL

https://www.healthgorilla.com/embedded_idproofing?access_token=95374e6d59115486d8b8f17d6a0e9f39&
[email protected]
&callback=https://www.mysite.com/callback

Successful callback example

https://www.mysite.com/callback?result=succeed&patientId=234b056061f93146a983072f

User Experience

The ID proofing process will take a user approximately 5-10 minutes to complete. Before starting the process, the user should have the following information available:

  • Passport or driver's license or government issued ID
  • SMS and Internet enabled mobile device

The user will be guided through a series of screens to supply information:

  • Phone number (this will send a text message to the user)
  • Last four of SSN

The user will need to upload a picture of their driver's license or passport and take a selfie as part of the verification process.