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."
  }
}