Lab Network iframe

The Diagnostic Network iframe allows developers to embed our lab ordering portal UI into their own products. This functionality enables users (providers or assisting staff) to submit lab orders and receive results through Health Gorilla without leaving your product's UI. This guide describes the iframe API and contains simple examples of requests to the corresponding endpoints.

Resources

OAuth 2.0
JSON-RPC Protocol Specification - http://www.jsonrpc.org/specification

1. Using OAuth 2.0 to Access Health Gorilla Diagnostic Network iframe

OAuth 2.0 protocol is used to secure Health Gorilla's API.
Your application must get an access token to access private data using Health Gorilla's API.

The place_orders scope is required to be granted to your client application to submit orders via Health Gorilla API.

You must follow 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. Diagnostic Network iframe API Endpoint

This service is based on the JSON-RPC protocol. You should be familiar with JSON-RPC protocol specification to clarify the common rules and error handling.
Health Gorilla healthcare providers endpoint is:

https://api.healthgorilla.com/doctor/api

3. API Definition

3.1. Place Order Request

To begin the application makes JSON-RPC call to Diagnostic Network iframe API Endpoint.

Request contains the following fields:

Field	Values	Description
facilityType	One of the facility types available for ordering.	Identifies the type of the order.
patient	Patient JSON.	Defines the patient for the order.
callbackUrl	The callback URL. It is required to use https scheme for security reasons	Determines where the response will be sent to. Read more about the response. You can include some additional parameters to that URL. Any you need to pass to the callback.
state	Any string. Optional.	A value used by the client to maintain state between the request and callback. Recommended to prevent XSRF attacks. If specified then the value will be included to the callback invocation. See Chapter 3.2. Place Order Callback
tz-offset	Optional.	Timezone offset as minutes from UTC

Supported facility types

Facility Type	Description
DiagnosticLaboratories	Diagnostic Laboratories
RadiologyImaging	Radiology Imaging
GeneticTesting	Genetic Testing
SurgicalCenter	Surgical Centers
PhysicalTherapy	Physical Therapy (PT)
SkilledNursingFacilities	Skilled Nursing Facilities
HomeHealthAgencies	Home Health Agencies (HHA)
SleepCenters	Sleep Centers
Hospice	Hospices
AssistedLivingFacilities	Assisted Living Facilities
Specialist	Specialists

A patient JSON

Contains the following fields (case sensitive)

Field	Values	Description
id2	Optional	MRN in your system or External ID
className	Required	Will always be "com.informedika.common.shared.vo.PatientVO"
firstName	Any string. Required	The given name of the patient.
middleName	Any string. Optional	The middle name of the patient.
lastName	Any string. Required.	The surname of the patient.
title	One of the following constants: mr ms Optional	The desired patient’s title.
gender	One of the following constants: male female Required	The gender of the guarantor.
dateOfBirth	Local Date JSON Required.	The date of birth of the patient.
address	JSON Address Optional	Patient address.
license	Optional string	License ID
ssn	Optional string	Social Security Number
maritalStatus	One of the following constants: married single divorced widowed separated domesticPartner livingTogether unknown Optional	The marital status of the patient.
language	One of the following constants: en es pt zh ru fr de it jp un * dc Optional	Language preference
needTranslator	True or False Optional	Determines if patient needs a translator services
races	One or several of the following constants: indian asian black hawaiian white unknown * declined Optional	The list of races of the patient.
ethnicity	One of the following constants: hispanicLatino notHispanicLatino unknown declined Optional
homePhone	A phone number. Optional	Home phone number.
mobilePhone	A phone number. Optional	Mobile phone number.
workPhone	A phone number. Optional	Work phone number.
workPhoneExt	Any digits. Optional	Work phone extension
email	An email address. Optional	The valid email address.
contactMethod	One of the following constants: email phone * mail Optional	Prefered contact method.
primaryInsurance	An insurance JSON Optional	Primary insurance.
secondaryInsurance	An insurance JSON Optional	Secondary insurance.
tertiaryInsurance	An insurance JSON Optional	Tertiary insurance.

An insurance JSON

Contains the following fields

Field	Values	Description
provider	Any string. Required	The name of the insurance provider.
policyId	Any string. Required	Policy number/id
groupNumber	Any string. Optional	Policy group number if available
providerInfo	A provider JSON Required	Describes the payer for the given insurance plan.
insured	A guarantor JSON Required	Defines the guarantor.

An insurance provider JSON

Contains the following fields

Field	Values	Description
name	Any string. Required.	The name of the insurer.
phone	A phone number.	A valid US phone number.
address	JSON Address	The claims address of the insurance provider.

A guarantor JSON

Contains the following fields

Field	Values	Description
firstName	Any string. Mandatory.	Given name of the guarantor.
lastName	Any string. Mandatory.	Last name of the guarantor.
gender	One of the following constants: male female Required	Gender of the guarantor.
dateOfBirth	Local Date JSON Required	Date of birth of the guarantor.
employer	Any string. Optional	Company name where the guarantor works if available.
relationship	One of the following constants: self spouse parent other Mandatory.	Identifies the relationship between the patient and the guarantor.
phone	A phone number. Required	Valid US phone number.
address	JSON Address Required	Guarantor’s mailing address.

An address JSON

Contains the following fields

Field	Values	Description
address1	Any string Required	Address 1
address2	Any string Optional	Address 2
city	Any string Required	City name.
state	A state code Required	Two-letters state code.
zip	5-digit ZIP code. Required	Postal ZIP code.
country	USA Required	Country code. A predefined constant.

A local date JSON

Contains the following fields

Field	Values	Description
year	> 1900 > Required > Mandatory	Year.
month	1 - 12 Required Mandatory	Month number.
day	1 - 31 Required Mandatory	Day of the month.

Below you can find an example of a such request:

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

{     
    "id": 8,
    "jsonrpc": "2.0", 
    "method": "placeOrder",
    "params": [{
        "facilityType" : "DiagnosticLaboratories",          
        "callbackUrl" : "https://yourapp.com/neworder/callback", 
        "state" : "1",
        "patient" : {
            "className" : "com.informedika.common.shared.vo.PatientVO",
            "firstName" : "Marcy",
            "lastName" : "Pop",
            "title" : "mrs",
            "gender" : "female",
            "dateOfBirth" : {
                "year" : 1990,
                "month" : 12,
                "day" : 28
            },
            "address" : {
                "address1" : "555 River Road",
                "city" : "Washougal",
                "state" : "WA",
                "zip" : "98671"
            },
            "maritalStatus" : "married",
            "races" : ["white"],
            "email" : "[email protected]",
            "homePhone" : "777-777-7777",
            "workPhone" : "888-446-7455",
            "primaryInsurance" : {
                "className" : "com.informedika.common.shared.vo.InsuranceVO",
                "provider" : "MediCare",
                "policyId" : "123456789",
                "providerInfo" : {
                    "className" : "com.informedika.common.shared.vo.BaseInsurerVO",
                    "name" : "MediCare",
                    "address" : {
                        "address1" : "PO BOX 272855",
                        "city" : "Chico",
                        "state" : "CA",
                        "zip" : "95927"}
                    },
                "insured" : {
                    "className" : "com.informedika.common.shared.vo.GuarantorVO",
                    "firstName" : "Jim",
                    "lastName" : "Pop",
                    "relationship" : "other",
                    "employer" : "Health Gorilla Inc.",
                    "address" : {
                        "address1" : "555 River Road",
                        "city" : "Washougal",
                        "state" : "WA",
                        "zip" : "98671"
                    },
                    "homePhone" : "844-446-7455",
                    "gender" : "male",
                    "dateOfBirth" : {
                        "year" : 1990,
                        "month" : 10,
                        "day" : 22}
                    }
            },
            "secondaryInsurance" : {
                "className" : "com.informedika.common.shared.vo.InsuranceVO",
                "provider" : "ANTHEM BLUE CROSS OF CALIFORNIA",
                "policyId" : "619A988989",
                "groupNumber" : "54545454",
                "providerInfo" : {
                    "className" : "com.informedika.common.shared.vo.BaseInsurerVO",
                    "name" : "ANTHEM BLUE CROSS OF CALIFORNIA",
                    "phone" : "877-800-4725",
                    "address" : {
                        "address1" : "PO BOX 60007",
                        "city" : "Los Angeles",
                        "state" : "CA",
                        "zip" : "90060"}
                    },
                "insured" : {
                    "className" : "com.informedika.common.shared.vo.GuarantorVO",
                    "firstName" : "Jim",
                    "lastName" : "Pop",
                    "relationship" : "other",
                    "employer" : "Health Gorilla Inc.",
                    "address" : {
                        "address1" : "555 River Road",
                        "city" : "Washougal",
                        "state" : "WA",
                        "zip" : "98671"
                    },
                    "homePhone" : "844-446-7455",
                    "gender" : "male",
                    "dateOfBirth" : {
                        "year" : 1990,
                        "month" : 10,
                        "day" : 22}
                    }
        }
    }
    }]
}

A successful response contains the following fields:

Field	Description
callbackUrl	The URL to open the New Order wizard.

Below you can find an example of such a response:

{ 
  "jsonrpc": "2.0", 
  "result": [
    {
      "callbackUrl" : "https://healthgorilla.com/newsession?go=https%3A%2F%healthgorilla%2Fmarketplace%23new%2Forder%2Flab%26processId%3D62631e55e85ee9304c9bad80%26mode%3Dembedded%26patientIds%3Dd03d19550d4e030ad9bea63b"
    }
  ], 
  "id": 8
}

Callback URl is a URL to access Health Gorilla New Order wizard. Your application should take this URL from the response, append OAuth access token (access_token parameter) and then open it in a separate window or in a frame.

3.1.1. Example

Below you can see how to call JSON-RPC with curl tool.

curl -X POST -k -H "Content-Type: application/json" -H "Authorization: Bearer b0d14637fa9e47541e3e55c32828c307" --data-binary @path\to\file.json  https://api.healthgorilla.com/doctor/api

Where @path\to\file.json is the the path to the file that contains JSON request.
For example: @C:\tmp\placeOrder.json
Then copy JSON example from 3.1 to the file and execute the command.

Once you get successful response to your call you can use value of callbackUrl response parameter to navigate iframe or new browser window to

https://healthgorilla.com/newsession?go=https%3A%2F%healthgorilla%2Fmarketplace%23new%2Forder%2Flab%26processId%3D62631e55e85ee9304c9bad80%26mode%3Dembedded%26patientIds%3Dd03d19550d4e030ad9bea63b&access_token=b0d14637fa9e47541e3e55c32828c307

3.2. Place Order Callback

Once Place New Order Wizard finishes it will be redirected to the callbackUrl you have provided. It will pass the following parameters:

Parameter	Description
responseCode	The result of Place New Order Wizard. Possible values are: success -- a new order has been successfully placed; canceled -- the process has been canceled by the user; * error -- an error has occurred during the process.
responseMessage	Optional. Can provide error description in case when responseCode = error
state	The state parameter, if it was included to the initial request.
orderId	Optional. Placed order ID in case when responseCode = success for use in Get Order Request. See Chapter 3.3. Get Order Request
orderIds	Optional. Contains joined string (separated by ‘\|’) of placed orders IDs in case if order was splitted during placement

Examples:

https://yourapp.com/neworder/callback?responseCode=success&orderId=c0ef7755a39e3e76a91d00ba

https://yourapp.com/neworder/callback?responseCode=error&responseMessage=Failed%20while%20getting%20EMR%20Integration%20data

https://yourapp.com/neworder/callback?youCanHave=yourOwnParameters&responseCode=canceled

3.3. Get Order Request

3.3.1. Read order using FHIR API

HealthGorilla provides the FHIR RequestGroup endpoint that should be called to read a newly submitted order.

https://api.healthgorilla.com/fhir/RequestGroup/ORDER_ID

You can find request details and response description in the related documentation.

3.3.2. Read order using JSON-RPC (deprecated)

This method of reading information about the placed order is deprecated, please use RequestGroup instead.

The get_orders scope is required to be granted to your client application to read orders.

To begin the application makes JSON-RPC call to Diagnostic Network iframe Endpoint.

Request contains the following fields:

Field	Values	Description
orderId	String. Required.	Requested order ID returned by callback url after successful order placement. See Chapter 3.2. Place Order Callback

Below you can find an example of such a request:

{
 "jsonrpc":"2.0",
 "method": "getOrder",
 "id": "5",
 "params": [{
 "orderId" : "c0ef7755a39e3e76a91d00ba"
 }]
}

A successful response includes information about the placed order and contains the
following fields:

Field	Description
orderSnapshot	OrderSnapshot JSON.