Identity Verification API

Version: 1.1
Welcome to Health Gorilla's Developer Portal. Access API documentation for our suite of clinical data APIs.

Our Identity Verification API enables developers to verify the identity of providers, patients, and other users who sign up for their platform. This guide describes the API and contains simple examples of requests to the corresponding endpoints.

Resources:

1. Using OAuth 2.0 to Access our Identity Verification API

OAuth 2.0 protocol is used to secure Health Gorilla API.

Your application must get an access token to access private data using this API.

  • The auth_provider scope is required to be granted to your client application to access results via Health Gorilla API.

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

2. Endpoints

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

2.1. Provider Authorization API Endpoint

This service is based on the JSON-RPC protocol. You should be familiar with the JSON-RPC protocol specification to know common rules and error handling.

The Health Gorilla healthcare providers authorization endpoint is:

https://healthgorilla.com/prauth/api

3. API Definition

3.1. Request Knowledge Base questions

To begin the application makes JSON-RPC call to Provider Authorization API Endpoint. Method name is requestKBQuestions. This method is used to find provider by specified parameters and request questions to check identity. If submitted fields fail validation then error message is returned in response. If no provider found by provided DoB and zip code, the response may contain needSsn4 flag as indicator that the client should submit last 4 digits of provider's SSN and repeat the call. Note that dob and ssn4 fields might be provided both for the first invocation. In this case method tries to find provider by DoB and zip code first and then (if no success) uses SSN4. If provider found then set of Knowledge Base questions will be returned along with responseId that is required for further process.

Request contains the following fields (case sensitive):

Field

Values

Description

firstname

String. Required.

Provider first name.

lastname

String. Required

Provider lastname. Required

dob

Local Date JSON. Required
for first call - should be empty
if method invoked second
time after getting
needSsn4=true in response.

Provider Date of Birth.

zip

String. Required.

Provider ZIP - 5 digits

ssn4

String. Required for second
call after getting needSsn4=true in response.

Last 4 digits of Provider SSN.

Local Date JSON contains the following fields

Field

Values

Description

year

1900+. Required

Year

month

1 - 12. Required

Month number

day

1 - 31. Required

Day of the month.

All fields are mandatory.

Below you can find an example of a such request (with DoB provided):

POST /prauth/api HTTP/1.1
Authorization: Bearer fb0ecb5f514a02dbe044d54b8dd29cac
Host: www.healthgorilla.com

{
  "jsonrpc": "2.0",
  "method": "requestKBQuestions",
  "params": [{
    "firstname": "Kurt",
    "lastname": "Klar",
  "zip": "12345",
  "dob": {
  "year": 1998,
  "month": 2,
  "day": 3
}
}],
"id": 1
}

A response contains the following fields:

Field

Type

Description

needSsn4

boolean

If true then provider should be asked for Last 4 digits of SSN

responseId

String

response ID for reference in future requests

questions

Questions JSON

List of questions that should be asked from user

errorMessage

String

Contains text of error occurred

Questions JSON contains the following fields

Field

Values

Description

type

String

Question type

prompt

String

Question text

answers

List of strings

List of options that should be asked

correctAnswer

String

Populated by client before sending request to verify answers

Below you can find an example of successful response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "success": true,
    "responseId": "2070588697",
    "questions": [
      {
        "type": "vehicle.year",
        "prompt": "What year is your Ford Expedition?",
        "answers": [
          "2004",
          "2005",
          "2006",
          "None of the above"
        ]
      },
      {
        "type": "vehicle.purchase.date",
        "prompt": "When did you purchase or lease your Ford Expedition?",
        "answers": [
          "December 2006",
          "April 2008",
          "July 2010",
          "None of the above"
        ]
      },
      {
        "type": "person.known",
        "prompt": "Which of the following people do you know?",
        "answers": [
          "MANNY EDELSTEIN",
          "LISA MCKITRICK",
          "ANTHONY BROWN",
          "None of the above"
        ]
      },
      {
        "type": "property.size",
        "prompt": "What is the approximate square footage of the property at 222333 PEACHTREE PLACE?",
        "answers": [
          "1,000 or less",
          "1,001 - 1,500",
          "1,501 - 2,000",
          "2,001 - 2,500",
          "Over 2,500",
          "None of the above"
        ]
      }
    ]
  }

This example of response for a case when system couldn’t find provider by specified DoB and prompts for last 4 digits of SSN :

{
    "jsonrpc": "2.0",
    "id": 1,
    "result": {
        "success": true,
        "needSsn4": true
    }
}

Second request sample (with SSN4 provided):

POST /prauth/api HTTP/1.1
Authorization: Bearer fb0ecb5f514a02dbe044d54b8dd29cac
Host: www.healthgorilla.com

{
  "jsonrpc": "2.0",
  "method": "requestKBQuestions",
  "params": [
    {
      "firstname": "Kurt",
      "lastname": "Klar",
      "zip": "12345",
      "ssn4": "2233"
    }
  ],
  "id": 1
}

Sample error responses:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "success": false,
    "errorMessage": "Missing required fields: 'lastname','zip'."
  }
}
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "success": false,
    "errorMessage": "Identity validation failed: provider notfound"
  }
}

3.2. Verify Answers

Once client got answers for set of questions requested then method verifyKBAnswers to submit answered questions for identity check should be invoked. Note that parameter responseId from previous successful response is required at method request. If only some of questions were answered correctly then method returns challenge=true and set of challenge questions in response. This means that client should get answers for them and repeat method call with challenge=true in request. If response has idologySuccess is true then it means user passed validation.

Request contains the following fields (case sensitive):

Field

Values

Description

responseId

String. Required.

ID obtained from previous
response
.

answeredQuestions

Questions JSON.
Required

List of questions obtained
from previous response with populated correctAnswer field

challenge

Boolean. Required if answers
to challenge questions send
in request.

Signs that answers to challenge questions send in request

Below you can find an example of a such request:

POST /prauth/api HTTP/1.1
Authorization: Bearer fb0ecb5f514a02dbe044d54b8dd29cac
Host: www.healthgorilla.com

{
  "jsonrpc": "2.0",
  "method": "verifyKBAnswers",
  "params": [
    {
      "responseId": "2070588697",
      "answeredQuestions": [
        {
          "type": "vehicle.year",
          "prompt": "What year is your Ford Expedition?",
          "correctAnswer": "2005",
          "answers": [
            "2004",
            "2005",
            "2006",
            "None of the above"
          ]
        },
        {
          "type": "vehicle.purchase.date",
          "prompt": "When did you purchase or lease your Ford Expedition?",
          "correctAnswer": "December 2006",
          "answers": [
            "December 2006",
            "April 2008",
            "July 2010",
            "None of the above"
          ]
        },
        {
          "type": "person.known",
          "prompt": "Which of the following people do youknow?",
          "correctAnswer": "None of the above",
          "answers": [
            "MANNY EDELSTEIN",
            "LISA MCKITRICK",
            "ANTHONY BROWN",
            "None of the above"
          ]
        },
        {
          "type": "property.size",
          "prompt": "What is the approximate square footage of the property at 222333 PEACHTREE PLACE?",
          "correctAnswer": "1,000 or less",
          "answers": [
            "1,000 or less",
            "1,001 - 1,500",
            "1,501 - 2,000",
            "2,001 - 2,500",
            "Over 2,500",
            "None of the above"
          ]
        }
      ]
    }
  ],
  "id": 1
}

A response contains the following fields:

Field

Type

Description

idologySuccess

boolean

If true then Identity check passed successfully

challenge

boolean

If true then extra set of challenge questions should be asked

responseId

String

Response ID for reference in future requests

questions

Questions JSON

List of challenge questions that should be asked from user

errorMessage

String

Contains text of error occurred

Sample of response with challenge questions:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "success": true,
    "responseId": "2070588697",
    "questions": [
      {
        "type": "current.county.b",
        "prompt": "In which county have you lived?",
        "answers": [
          "JEWELL",
          "FULTON",
          "FLORENCE",
          "None of the above"
        ]
      }
    ],
    "challenge": true
  }
}

Sample of request with answered challenge questions:

POST /prauth/api HTTP/1.1
Authorization: Bearer fb0ecb5f514a02dbe044d54b8dd29cac
Host: www.healthgorilla.com

{
  "jsonrpc": "2.0",
  "method": "verifyKBAnswers",
  "params": [
    {
      "responseId": "2070588697",
      "answeredQuestions": [
        {
          "type": "current.county.b",
          "prompt": "In which county have you lived?",
          "correctAnswer": "FULTON",
          "answers": [
            "JEWELL",
            "FULTON",
            "FLORENCE",
            "None of the above"
          ]
        }
      ],
      "challenge": true
    }
  ],
  "id": 1
}

Sample of successful response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "success": true,
    "idologySuccess": true
  }
}

Sample error responses:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "success": false,
    "errorMessage": "Missing 'correctAnswer' field for questions: 1, 3."
  }
}
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "success": false,
    "errorMessage": "Verification failed. Answers to security questions are not correct."
  }
}