Lab Network iframe

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

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

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:

FieldValuesDescription
facilityTypeOne of the facility types available for ordering.Identifies the type of the order.
patientPatient JSON.Defines the patient for the order.
callbackUrlThe 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.
stateAny 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

Supported facility types

Facility TypeDescription
DiagnosticLaboratoriesDiagnostic Laboratories
RadiologyImagingRadiology Imaging
GeneticTestingGenetic Testing
SurgicalCenterSurgical Centers
PhysicalTherapyPhysical Therapy (PT)
SkilledNursingFacilitiesSkilled Nursing Facilities
HomeHealthAgenciesHome Health Agencies (HHA)
SleepCentersSleep Centers
HospiceHospices
AssistedLivingFacilitiesAssisted Living Facilities
SpecialistSpecialists

A patient JSON

Contains the following fields (case sensitive)

FieldValuesDescription
id2OptionalMRN in your system or External ID
firstNameAny string.
Required
The given name of the patient.
middleNameAny string.
Optional
The middle name of the patient.
lastNameAny string.
Required.
The surname of the patient.
titleOne 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.
dateOfBirthLocal Date JSON
Required.
The date of birth of the patient.
addressJSON Address
Optional
Patient address.
licenseOptional stringLicense ID
ssnOptional stringSocial Security Number
maritalStatusOne of the following constants:
married
single
divorced
widowed
separated
domesticPartner
livingTogether
unknown
Optional
The marital status of the patient.
languageOne of the following constants:
en
es
pt
zh
ru
fr
de
it
jp
un
* dc
Optional
Language preference
needTranslatorTrue or False
Optional
Determines if patient needs a translator services
racesOne or several of the following constants:
indian
asian
black
hawaiian
white
unknown
* declined
Optional
The list of races of the patient.
ethnicityOne of the following constants:
hispanicLatino
notHispanicLatino
unknown
declined
Optional
homePhoneA phone number.
Optional
Home phone number.
mobilePhoneA phone number.
Optional
Mobile phone number.
workPhoneA phone number.
Optional
Work phone number.
workPhoneExtAny digits.
Optional
Work phone extension
emailAn email address.
Optional
The valid email address.
contactMethodOne of the following constants:
email
phone
* mail
Optional
Prefered contact method.
primaryInsuranceAn insurance JSON
Optional
Primary insurance.
secondaryInsuranceAn insurance JSON
Optional
Secondary insurance.
tertiaryInsuranceAn insurance JSON
Optional
Tertiary insurance.

An insurance JSON

Contains the following fields

FieldValuesDescription
providerAny string.
Required
The name of the insurance provider.
policyIdAny string.
Required
Policy number/id
groupNumberAny string.
Optional
Policy group number if available
providerInfoA provider JSON
Required
Describes the payer for the given insurance plan.
insuredA guarantor JSON
Required
Defines the guarantor.

An insurance provider JSON

Contains the following fields

FieldValuesDescription
nameAny string.
Required.
The name of the insurer.
phoneA phone number.A valid US phone number.
addressJSON AddressThe claims address of the insurance provider.

A guarantor JSON

Contains the following fields

FieldValuesDescription
firstNameAny string.
Mandatory.
Given name of the guarantor.
lastNameAny string.
Mandatory.
Last name of the guarantor.
genderOne of the following constants:
male
female
Required
Gender of the guarantor.
dateOfBirthLocal Date JSON
Required
Date of birth of the guarantor.
employerAny string.
Optional
Company name where the guarantor works if available.
relationshipOne of the following constants:
self
spouse
parent
other
Mandatory.
Identifies the relationship between the patient and the guarantor.
phoneA phone number.
Required
Valid US phone number.
addressJSON Address
Required
Guarantor’s mailing address.

An address JSON

Contains the following fields

FieldValuesDescription
address1Any string
Required
Address 1
address2Any string
Optional
Address 2
cityAny string
Required
City name.
stateA state code
Required
Two-letters state code.
zip5-digit ZIP code.
Required
Postal ZIP code.
countryUSA
Required
Country code. A predefined constant.

A local date JSON

Contains the following fields

FieldValuesDescription
year> 1900
Required
Mandatory
Year.
month1 - 12
Required
Mandatory
Month number.
day1 - 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

{     
    "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" : "John",
            "lastName" : "Connor",
            "title" : "mr",
            "gender" : "male",
            "dateOfBirth" : {
                "year" : 1985,
                "month" : 2,
                "day" : 28
            },
            "maritalStatus" : "single",
            "races" : ["white"],
            "email" : "[email protected]",
            "workPhone" : "844-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"
                    }
                }
            },
            "secondaryInsurance" : {
                "className" : "com.informedika.common.shared.vo.InsuranceVO",
                "provider" : "ANTHEM BLUE CROSS OF CALIFORNIA",
                "policyId" : "619A988989",
                "groupNumber" : "GOOGLEPLEX",
                "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" : "Andrei",
                    "lastName" : "Zudin",
                    "relationship" : "other",
                    "employer" : "Health Gorilla Inc.",
                    "phone" : "844-446-7455"
                }
            }
        }
    }],    
    "id": 8 
}

A successful response contains the following fields:

FieldDescription
callbackUrlThe 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:

ParameterDescription
responseCodeThe 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.
responseMessageOptional. Can provide error description in case when responseCode = error
stateThe state parameter, if it was included to the initial request.
orderIdOptional. Placed order ID in case when responseCode = success for use in Get Order Request. See Chapter 3.3. Get Order Request
orderIdsOptional. 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:

FieldValuesDescription
orderIdString. 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:

FieldDescription
orderSnapshotOrderSnapshot JSON.

OrderSnapshot JSON

Contains the following fields (case sensitive):

FieldValuesDescription
orderIdString. MandatoryInternal HealthGorilla order identifier.
labReferenceIdNumber. MandatoryOrder number for reference by facility performing order. Has label ‘Lab Reference ID’ on the requisition form.
statusOne of the following constants:
submitted
submitFailed
sent
scheduled
Mandatory
Order status
electronicOrderingBoolean. MandatoryElectronic submission flag. True indicates that the order was electronically transferred to the vendor.
destinationOne of the following constants:
psc
lab
Mandatory
Type of order destination. If specimen was not collected then destination will be ‘psc’ that stands of Patient Service Center. Otherwise ‘lab’
executionDateFormattedString. OptionalDate test to be performed if applicable.
executionLengthNumber. OptionalLength of surgery (for Surgical Centers only)
collectionDateDate. OptionalSpecimen collection date/time if applicable
submissionDateDate. MandatoryOrder submission / creation date/time
facilityNameString. Mandatoryvender / facility name that will be performing an order
clientNumberString. OptionalClinic account number given if applicable. Has label ‘Client #’ at requisition form.
senderNameString. MandatoryOrder creator full name
senderPracticeNameString. MandatoryOrder creator practice name
senderPracticeAddressFormattedString. MandatoryOrder creator practice address formatted as: [address], [city], [state] [zip]
senderPracticePhoneString. OptionalOrder’s creator practice phone
senderPracticeFaxString. OptionalOrder’s creator practice fax
refPhysicianProviderNameString. MandatoryOrder’s referring physician full name.
refPhysicianProviderNPIString. OptionalOrder’s referring physician NPI number
refPhysicianProviderAccountNumberString. OptionalOrder’s referring physician personal account number given by order vendor if applicable
billToOne of the following constants:
self
patient
guarantor
thirdParty
Optional

Order billing type, determines who is the payer for an order. ‘Self’ means ordering practice.
orderNoteString. OptionalOrder note specified by order creator
highPriorityBoolean. OptionalHigh priority/STAT order flag
patientPatientSnapshot objectOrder’s patient information
diagnosesList of DiagnosisSnapshot objectList of patient diagnoses specified in order
orderTestsList of OrderTestSnapshot objectsList of order test items
guarantorGuarantorSnapshot objectPatient guarantor info if order’s ‘billTo’ has ‘guarantor’ value
insurancesList of InsuranceSnapshotList of insurances available for patient in case order ‘billTo’ has ‘thirdParty’ value.
Maximum 3 insurances
orderAoesList of AoeSnapshotList of Ask-on-Entry questions (order level) required for some order tests

PatientSnapshot JSON

Contains the following fields:

FieldValuesDescription
altIdNumber.Human readable ID of patient for future reference. Has ‘Pat ID #’ label on the requisition form
fullnamePatient’s full name
dobFormattedPatient’s Date-of-Birth formatted as MM/DD/YYYY
genderOne of the following values:
male
female
Mandatory
Patient’s gender
addressFormattedString. OptionalPatient’s address formatted as: [address], [city], [state] zip
phoneString. OptionalPatient’s phone

DiagnosisSnapshot JSON

Contains the following fields:

FieldValuesDescription
codeString. MandatoryICD Diagnosis code
descriptionString. MandatoryShort diagnosis description

OrderTestSnapshot JSON

Contains the following fields:

FieldValuesDescription
codeString. MandatoryOrder test code
nameString. MandatoryOrder test name
noteString. OptionalShort comment specified for ordered test
priorityOne of the following values:
STAT
Unscheduled
Optional
Order test priority flag
aoesList of AoeSnapshot objects. OptionalList of ask at order entry questions and answers (test level)

GuarantorSnapshot JSON

Contains the following fields:

FieldValuesDescription
nameStringGuarantor’s fullname
addressFormattedStringGuarantor’s address formatted as: [address], [city], [state] zip
phoneStringGuarantor’s contact phone
relationshipOne of the following values:
self
spouse
parent
other
Mandatory
relationship of guarantor to patient

InsuranceSnapshot JSON

Contains the following fields:

FieldValuesDescription
primacyOne of the following value:
primary
secondary
* tertiary
Mandatory
Insurance primacy constant
insuredGuarantorSnapshotInformation about insurance holder
insurerString. MandatoryInsurance provider name
insuranceNumberString. MandatoryInsurance policy number

AoeSnapshot JSON

Contains the following fields:

FieldValuesDescription
questionString. MandatoryAoE question
answerString. MandatoryProvided answer

Below you can find an example of such a response:

{
    "jsonrpc": "2.0",
    "id": "5",
    "result": {
        "orderSnapshot": {
            "orderId": "c0ef7755a39e3e76a91d00ba",
            "labReferenceId": "572",
            "status": "Submitted",
            "electronicOrdering": false,
            "destination": "Patient Service Center",
            "executionDateFormatted": "06/11/2015",
            "executionLength": "null",
            "submissionDate": "2015-06-10T12:06:06.398+0400",
            "facilityName": "Quest Diagnostics",
            "clientNumber": "111111",
            "senderName": "John M. Doe, M.D.",
            "refPhysicianProviderName": "John M. Doe, M.D.",
            "refPhysicianProviderNPI": "1234567893",
            "refPhysicianProviderAccountNumber": "",
            "patient": {
                "altId": "6",
                "fullname": "Maggy  Simpson",
                "dobFormatted": "11/05/2010",
                "gender": "Female",
                "addressFormatted": "745 Evergreen Terrace, Springfield, CA 11111",
                "phone": "2222222222"
            },
            "diagnoses": [
                {
                    "code": "661.13",
                    "description": "SEC UTERINE INERTIA ANTEPA"
                }
            ],
            "orderTests": [
                {
                    "code": "TD-16",
                    "name": "TEST-DC-16"
                }
            ],
            "billTo": "Client (Our Account)",
            "highPriority": false
        }
    }
}