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
- 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 |
An email address. Optional | The valid email address. | |
contactMethod | One of the following constants: phone 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
{
"jsonrpc": "2.0",
"method": "placeOrder",
"params": [{
"facilityType" : "DiagnosticLaboratories",
"callbackUrl" : "https://yourapp.com/neworder/callback",
"state" : "1",
"tz-offset" : 720
"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:
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. |
OrderSnapshot JSON
Contains the following fields (case sensitive):
Field | Values | Description |
---|---|---|
orderId | String. Mandatory | Internal HealthGorilla order identifier. |
labReferenceId | Number. Mandatory | Order number for reference by facility performing order. Has label ‘Lab Reference ID’ on the requisition form. |
status | One of the following constants: submitted submitFailed sent scheduled Mandatory | Order status |
electronicOrdering | Boolean. Mandatory | Electronic submission flag. True indicates that the order was electronically transferred to the vendor. |
destination | One 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’ |
executionDateFormatted | String. Optional | Date test to be performed if applicable. |
executionLength | Number. Optional | Length of surgery (for Surgical Centers only) |
collectionDate | Date. Optional | Specimen collection date/time if applicable |
submissionDate | Date. Mandatory | Order submission / creation date/time |
facilityName | String. Mandatory | vender / facility name that will be performing an order |
clientNumber | String. Optional | Clinic account number given if applicable. Has label ‘Client #’ at requisition form. |
senderName | String. Mandatory | Order creator full name |
senderPracticeName | String. Mandatory | Order creator practice name |
senderPracticeAddressFormatted | String. Mandatory | Order creator practice address formatted as: Field", , "h-1", "Values , |
senderPracticePhone | String. Optional | Order’s creator practice phone |
senderPracticeFax | String. Optional | Order’s creator practice fax |
refPhysicianProviderName | String. Mandatory | Order’s referring physician full name. |
refPhysicianProviderNPI | String. Optional | Order’s referring physician NPI number |
refPhysicianProviderAccountNumber | String. Optional | Order’s referring physician personal account number given by order vendor if applicable |
billTo | One of the following constants: self patient guarantor thirdParty Optional | Order billing type, determines who is the payer for an order. ‘Self’ means ordering practice. |
orderNote | String. Optional | Order note specified by order creator |
highPriority | Boolean. Optional | High priority/STAT order flag |
patient | PatientSnapshot object | Order’s patient information |
diagnoses | List of DiagnosisSnapshot object | List of patient diagnoses specified in order |
orderTests | List of OrderTestSnapshot objects | List of order test items |
guarantor | GuarantorSnapshot object | Patient guarantor info if order’s ‘billTo’ has ‘guarantor’ value |
insurances | List of InsuranceSnapshot | List of insurances available for patient in case order ‘billTo’ has ‘thirdParty’ value. Maximum 3 insurances |
orderAoes | List of AoeSnapshot | List of Ask-on-Entry questions (order level) required for some order tests |
PatientSnapshot JSON
Contains the following fields:
Field | Values | Description |
---|---|---|
altId | Number. | Human readable ID of patient for future reference. Has ‘Pat ID #’ label on the requisition form |
fullname | Patient’s full name | |
dobFormatted | Patient’s Date-of-Birth formatted as MM/DD/YYYY | |
gender | One of the following values: male female Mandatory | Patient’s gender |
addressFormatted | String. Optional | Patient’s address formatted as: "h-0, "Fiel, , " zip |
phone | String. Optional | Patient’s phone |
DiagnosisSnapshot JSON
Contains the following fields:
Field | Values | Description |
---|---|---|
code | String. Mandatory | ICD Diagnosis code |
description | String. Mandatory | Short diagnosis description |
OrderTestSnapshot JSON
Contains the following fields:
Field | Values | Description |
---|---|---|
code | String. Mandatory | Order test code |
name | String. Mandatory | Order test name |
note | String. Optional | Short comment specified for ordered test |
priority | One of the following values: STAT Unscheduled Optional | Order test priority flag |
aoes | List of AoeSnapshot objects. Optional | List of ask at order entry questions and answers (test level) |
GuarantorSnapshot JSON
Contains the following fields:
Field | Values | Description |
---|---|---|
name | String | Guarantor’s fullname |
addressFormatted | String | Guarantor’s address formatted as: "h-0":, Field", "h- zip |
phone | String | Guarantor’s contact phone |
relationship | One of the following values: self spouse parent other Mandatory | relationship of guarantor to patient |
InsuranceSnapshot JSON
Contains the following fields:
Field | Values | Description |
---|---|---|
primacy | One of the following value: primary secondary * tertiary Mandatory | Insurance primacy constant |
insured | GuarantorSnapshot | Information about insurance holder |
insurer | String. Mandatory | Insurance provider name |
insuranceNumber | String. Mandatory | Insurance policy number |
AoeSnapshot JSON
Contains the following fields:
Field | Values | Description |
---|---|---|
question | String. Mandatory | AoE question |
answer | String. Mandatory | Provided 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
}
}
}
Updated 8 months ago