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:
- Health Gorilla OAuth 2.0 Guide
- JSON-RPC Protocol Specification - http://www.jsonrpc.org/specification
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."
}
}
Updated 11 months ago