Diagnostic 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:

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

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

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

{     
    "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:

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: [address], [city], [state] [zip]

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

roomBed

String. Optional

Patient’s room/bed if available

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: [address], [city], [state] 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: [address], [city], [state] 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
        }
    }
}