Diagnostic Network

The Diagnostic Network API allows providers to submit laboratory/radiology orders and receive results electronically from a vast network of diagnostic vendors, including Labcorp, Quest Diagnostics and Bioreference.

Resources

Health Gorilla provides RESTful API that can be used to place orders and get results with diagnostic laboratories and radiology centers. This API is based on FHIR STU3 and uses common FHIR resources and operations.

The following FHIR resources are involved in the requisitioning process:

  • RequestGroup
  • ProcedureRequest
  • Account
  • Coverage
  • Organization
  • Location
  • Practitioner
  • Patient
  • RelatedPerson
  • Specimen

What's New

Date

Change

11/30/2019

  • Organization resource endpoint was extended to support retrieval of requisition settings for a given diagnostic facility.

5/01/2020

  • RequestGroup resource endpoint was extended to return information about ABN forms for the given order

RequestGroup

Health Gorilla uses RequestGroup resource to describe an order. RequestGroup refers to nested ProcedureRequest resources via RequestGroup.action.resource attribute. Each ProcedureRequest is a single test ordered within the parent order. Multiple tests can be ordered in the scope of an order.

RequestGroup must implement the Health Gorilla Order profile.

https://api.healthgorilla.com/fhir/StructureDefinition/hg-order

RequestGroup and nested resources may contain references. These references should refer to resources hosted on the same Health Gorilla FHIR server or internal resources (“contained”). Do not include references to external resources into the request. See https://www.hl7.org/fhir/references.html for details.

Below you can find a list of attributes that are used to submit a new order.

RequestGroup.status

This attribute must have the following value:
System: http://hl7.org/fhir/request-status

Code

Display

Definition

active

Active

The request is ready to be acted upon

RequestGroup.intent

This attribute must have the following value:
System: http://hl7.org/fhir/request-intent

Code

Display

Definition

order

Order

The request represents a request/demand and authorization for action

RequestGroup.priority

This is an optional attribute. You can use the following values to indicate the certain order has a high priority:

System: http://hl7.org/fhir/request-priority

Code

Display

Definition

urgent

urgent

The request should be actioned promptly - higher priority than routine

asap

ASAP

The request should be actioned as soon as possible - higher priority than urgent

stat

STAT

The request should be actioned immediately - highest possible priority. E.g. an emergency

RequestGroup.subject

Patient the tests are ordered for. This must be a reference to an existing Patient resource.

RequestGroup.author

The practitioner that authored the order - author, creator. This must be a reference to an existing Practitioner resource.

RequestGroup - authorizedBy

https://api.healthgorilla.com/fhir/StructureDefinition/requestgroup-authorizedBy

The healthcare organization or department that authored the order. This must be a reference to an existing Organization resource. If known, this should be a certain healthcare organization location (Practice Location).

The target Organization must have one of the following types:
System: https://www.healthgorilla.com/fhir/organization-type

Code

Display

Definition

PR

Practice

Practice

PRL

Practice Location

Practice Location

RequestGroup.action

This is a list of tests ordered within the given order.
Each action element should contain resource attribute, that should be a link to an internal ProcedureRequest resource.

RequestGroup - account

https://api.healthgorilla.com/fhir/StructureDefinition/requestgroup-account

This is billing preferences for the order. This must be an internal reference to Account resource. Required to be specified.

RequestGroup - patientLocation

https://api.healthgorilla.com/fhir/StructureDefinition/requestgroup-location

Patient’s physical location - Room/Bed. This should be an internal reference to Location resource. This attribute may be mandatory for some laboratories. If present then Location.physicalType is mandatory and must contain one of the following values:

System: http://hl7.org/fhir/location-physical-type

Code

Display

Definition

ro

Room

A space that is allocated as a room, it may have walls/roof etc., but does not require these.

bd

Bed

A space that is allocated for sleeping/laying on. This is not the physical bed/trolley that may be moved about, but the space it may occupy.

Example:

{
 "resourceType": "RequestGroup",
 "contained": [
   {
     "resourceType": "Location",
     "id": "room",
     "name": "1A / 28",
     "mode": "instance",
     "physicalType": {
       "coding": [
         {
           "system": "http://hl7.org/fhir/location-physical-type",
           "code": "bd",
           "display": "Bed"
         }
       ],
       "text": "Room/Bed"
     }
   },
   ...
 ],
 ...
 "extension": [
   {
     "url": "https://www.healthgorilla.com/fhir/StructureDefinition/patient-location",
     "valueReference": {
       "reference": "#room"
     }
   },
   ...
 ]
}

RequestGroup - performer

https://api.healthgorilla.com/fhir/StructureDefinition/requestgroup-performer

The desired performer for doing the diagnostic testing - laboratory, radiology imaging center, etc.
This must be a reference to an existing Organization resource. This is not a physical location, but an abstract Organization.

The target Organization must have one of the following types:
System: https://www.healthgorilla.com/fhir/organization-type

Code

Display

F

Facility

RequestGroup - performerLocation

https://api.healthgorilla.com/fhir/StructureDefinition/performer-location

The service provider location where the requested diagnostic procedure should be performed.
This must be a reference to an existing Location resource. Referenced location must be linked to the specified performer via Location.managingOrganization attribute.

Examples

Electronic order to LabCorp (no location)

{
 "resourceType": "RequestGroup",
 ...
 "extension": [
   {
     "url": "https://www.healthgorilla.com/fhir/StructureDefinition/requestgroup-performer",
     "valueReference": {
       "reference": "Organization/f-d8da43521fe28b2afddbd465",
       "display": "LabCorp"
     }
   },
   ...
 ]
}

Radiology order to RADNet PSC (location chosen)

{
 "resourceType": "RequestGroup",
 ...
 "extension": [
 {
   "url": "https://www.healthgorilla.com/fhir/StructureDefinition/requestgroup-performer",
   "valueReference": {
     "reference": "Organization/f-d8da4352bfba8331b622682c",
     "display": "RADNet"
   }
 },
 {
   "url": "https://www.healthgorilla.com/fhir/StructureDefinition/performer-location",
   "valueReference": {
     "reference": "Location/fl-ade96d557573db6d2eabcc72",
     "display": "RADNet"
   }
 },
 ...
]
}

RequestGroup - requester

https://api.healthgorilla.com/fhir/StructureDefinition/requestgroup-requester

The physician who requests diagnostic procedures for the patient and responsible for the order.
This extension has two attributes - agent and onBehalfOf.
requester.agent is the individual who sent the order.
There are two options to go:

  1. If performer does not require Account Number to be passed for physician, then it should be a reference to an existing Practitioner resource.
  2. If Account Number is required to be included into request, then it must be an internal reference to Practitioner resource. An embedded resource must contain two identifiers:
  • Health Gorilla identifier that can be used to obtain an existing Health Gorilla practitioner
  • Account Number

requester.onBehalfOf is the practice the physician was acting on behalf of. This attribute is required to be set, if Account Number for practice is mandatory. In this case, it must be an internal reference to Organization resource. An embedded resource must contain Account Number.

Examples

Laboratory does not require any Account Number to be passed

{
 "resourceType": "RequestGroup",
 "meta": {
   "profile": [
     "https://healthgorilla.com/fhir/StructureDefinition/hg-order"
   ]
 },
 ...
 "extension": [
   {
     "url": "https://www.healthgorilla.com/fhir/StructureDefinition/requestgroup-requester",
     "extension": [
       {
         "url": "agent",
         "valueReference": {
           "reference": "Practitioner/fc076a524383b188ffc10051",
           "display": "Robert Kelso, M.D."
         }
       },
       {
         "url": "onBehalfOf",
         "valueReference": {
           "reference": "Organization/t-d5da4352af2201ace56ca725",
           "display": "Dr. Doe Practice"
         }
       }
     ]
   },
   ...
 ],
 ...
}

Both physician and practice Account Number are required

{
 "resourceType": "RequestGroup",
 "meta": {
   "profile": [
     "https://healthgorilla.com/fhir/StructureDefinition/hg-order"
   ]
 },
 "contained": [
   {
     "resourceType": "Practitioner",
     "id": "1",
     "identifier": [
       {
         "type": {
           "coding": [
             {
               "system": "http://hl7.org/fhir/v2/0203",
               "code": "PRN",
               "display": "Passport number"
             }
           ]
         },
         "system": "http://hl7.org/fhir/sid/us-npi",
         "value": "1234567893"
       },
       {
         "type": {
           "coding": [
             {
               "system": "http://hl7.org/fhir/v2/0203",
               "code": "AN",
               "display": "Account number"
             }
           ],
           "text": "Account Number"
         },
         "value": "04843980"
       }
     ],
     "active": true,
     "name": [
       {
         "family": "Doe",
         "given": [
           "John"
         ],
         "suffix": [
           "M.D."
         ]
       }
     ]
   },
   {
     "resourceType": "Organization",
     "id": "2",
     "identifier": [
       {
         "type": {
           "coding": [
             {
               "system": "http://hl7.org/fhir/v2/0203",
               "code": "AN",
               "display": "Account number"
             }
           ],
           "text": "Account Number"
         },
         "value": "1A45HT6"
       }
     ],
     "name": "Dr. Doe Practice - 1825 Somestreet st, Sacramento, CA"
   },
   ...
 ],
 "extension": [
   {
     "url": "https://www.healthgorilla.com/fhir/StructureDefinition/requestgroup-requester",
     "extension": [
       {
         "url": "agent",
         "valueReference": {
           "reference": "#1"
         }
       },
       {
         "url": "onBehalfOf",
         "valueReference": {
           "reference": "#2"
         }
       }
     ]
   },
   ...
 ],
 ...
}

RequestGroup - reasonCode

https://api.healthgorilla.com/fhir/StructureDefinition/requestgroup-reasoncode

An explanation or justification for why this diagnostic investigation is being requested in coded or textual form.

RequestGroup - specimen

https://api.healthgorilla.com/fhir/StructureDefinition/requestgroup-specimen

One or more specimens that the laboratory procedure will use.
Currently only collection date is used in this attribute.

Example

{
 "resourceType": "RequestGroup",
 "contained": [
   {
     "resourceType": "Specimen",
     "id": "specimen",
     "subject": {
       "reference": "Patient/03db43522cc01432572e0a53",
       "display": "Bart Simpson"
     },
     "collection": {
       "collectedDateTime": "2018-09-27T11:41:30+03:00"
     }
   },
   ...
 ],
 ...
 "extension": [
   {
     "url": "https://www.healthgorilla.com/fhir/StructureDefinition/requestgroup-specimen",
     "valueReference": {
       "reference": "#specimen"
     }
   },
   ...
 ]
}

RequestGroup - deliveryOptions

https://api.healthgorilla.com/fhir/StructureDefinition/requestgroup-deliveryOptions

The delivery options for the given order.
There are three possible ways to send an order:

  1. Send electronically
  2. Send by fax
  3. Print requisition form

If the specified performer does not support the selected mode, then the order will be rejected.

Examples

Send electronically

{
 "resourceType": "RequestGroup",
 ...
 "extension": [
   {
     "url": "https://www.healthgorilla.com/fhir/StructureDefinition/requestgroup-deliveryOptions",
     "extension": [
       {
         "url": "electronic",
         "valueBoolean": true
       }
     ]
   },
   ...
 ],
 ...
}

Fax Requisition Form to the Service Provider

{
 "resourceType": "RequestGroup",
 ...
 "extension": [
   {
     "url": "https://www.healthgorilla.com/fhir/StructureDefinition/requestgroup-deliveryOptions",
     "extension": [
       {
         "url": "location",
         "valueReference": {
           "reference": "Location/fl-03db43522cc01432572e0a53"
         }
       },
       {
         "url": "method",
         "valueContactPoint": {
           "system": "fax",
           "value": "000 000 0000"
         }
       }
     ]
   },
   ...
 ],
 ...
}

Print requisition form

{
 "resourceType": "RequestGroup",
 ...
 "extension": [
   {
     "url": "https://www.healthgorilla.com/fhir/StructureDefinition/requestgroup-deliveryOptions",
     "extension": [
       {
         "url": "electronic",
         "valueBoolean": false
       }
     ]
   },
   ...
 ],
 ...
}

RequestGroup.note

An order note - any comments that should be included in the requisition.

Account

Account resource defines billing preferences for the given order.
Account must implement the Health Gorilla Order Billing Account profile.

https://api.healthgorilla.com/fhir/StructureDefinition/hg-order-account

Below you can find attributes that Account resource may contain.

Account.type

Which individual or organization will pay for the given order. Also known as ‘bill to’ option. Always required and must contain code from the following ValueSet:
https://developer.healthgorilla.com/docs/fhir-value-sets#order-billto

Account.coverage

A list of insurances that can be used to pay the order. Up to three insurances supported. If there are more than one insurance in the list, then priority attribute should be set.
Mandatory if account.type is ‘thirdParty’, ignored otherwise.

Account.guarantor

A person who will pay for the given order.
Mandatory if account.type is ‘guarantor’, ignored otherwise.

Account - workerCompensation

https://api.healthgorilla.com/fhir/StructureDefinition/account-wc

Set to True in case of worker compensation.
These extensions are used if account.type is ‘thirdParty’, ignored otherwise.

Examples

BillTo Self

{
 "resourceType": "RequestGroup",
 "contained": [
   {
     "resourceType": "Account",
     "id": "1",
     "meta": {
       "profile": [
         "https://healthgorilla.com/fhir/StructureDefinition/hg-order-account"
       ]
     },
     "type": {
       "coding": [
         {
           "system": "https://www.healthgorilla.com/order-billto",
           "code": "self",
           "display": "Client (Our Account)"
         }
       ],
       "text": "Client (Our Account)"
     }
   },
   ...
 ],
 "extension": [
   {
     "url": "https://www.healthgorilla.com/fhir/StructureDefinition/requestgroup-account",
     "valueReference": {
       "reference": "#1"
     }
   },
   ...
 ],
 ...
}

BillTo Patient

{
 "resourceType": "RequestGroup",
 "contained": [
   {
     "resourceType": "Account",
     "id": "1",
     "meta": {
       "profile": [
         "https://healthgorilla.com/fhir/StructureDefinition/hg-order-account"
       ]
     },
     "type": {
       "coding": [
         {
           "system": "https://www.healthgorilla.com/order-billto",
           "code": "patient",
           "display": "Patient"
         }
       ],
       "text": "Patient"
     },
     "guarantor": [
       {
         "party": {
           "reference": "Patient/03db43522cc01432572e0a53",
           "display": "Bart Simpson"
         }
       }
     ]
   },
   ...
 ],
 "extension": [
   {
     "url": "https://www.healthgorilla.com/fhir/StructureDefinition/requestgroup-account",
     "valueReference": {
       "reference": "#1"
     }
   },
   ...
 ],
 ...
}

BillTo Guarantor

{
 "resourceType": "RequestGroup",
 "contained": [
   {
     "resourceType": "Account",
     "id": "1",
     "meta": {
       "profile": [
         "https://healthgorilla.com/fhir/StructureDefinition/hg-order-account"
       ]
     },
     "type": {
       "coding": [
         {
           "system": "https://www.healthgorilla.com/order-billto",
           "code": "guarantor",
           "display": "Guarantor"
         }
       ],
       "text": "Guarantor"
     },
     "guarantor": {
       "reference": "#guarantor"
     }
   },
   {
     "resourceType": "RelatedPerson",
     "id": "guarantor",
     "extension": [
       {
         "url": "https://www.healthgorilla.com/fhir/StructureDefinition/relatedperson-employer",
         "valueString": "Springfield Nuclear Plant"
       }
     ],
     "patient": {
       "reference": "Patient/03db43522cc01432572e0a53",
       "display": "Bart Simpson"
     },
     "relationship": {
       "coding": [
         {
           "system": "http://hl7.org/fhir/policyholder-relationship",
           "code": "parent",
           "display": "Parent"
         }
       ],
       "text": "Parent"
     },
     "name": [
       {
         "family": "Simpson",
         "given": [
           "Homer"
         ]
       }
     ],
     "telecom": [
       {
         "system": "phone",
         "value": "000 000 0000",
         "use": "home"
       }
     ],
     "gender": "male",
     "birthDate": "1960-02-20",
     "address": [
       {
         "text": "742 Evergreen Terrace, Springfield, USA, CT 11111",
         "line": [
           "742 Evergreen Terrace"
         ],
         "city": "Springfield",
         "state": "CT",
         "postalCode": "111111",
         "country": "USA"
       }
     ]
   },
   ...
 ],
 "extension": [
   {
     "url": "https://www.healthgorilla.com/fhir/StructureDefinition/requestgroup-account",
     "valueReference": {
       "reference": "#1"
     }
   },
   ...
 ],
 ...
}

BillTo ThirdParty

{
 "resourceType": "RequestGroup",
 "contained": [
   {
     "resourceType": "Account",
     "id": "1",
     "meta": {
       "profile": [
         "https://healthgorilla.com/fhir/StructureDefinition/hg-order-account"
       ]
     },
     "extension": [
       {
         "url": "https://www.healthgorilla.com/fhir/StructureDefinition/account-wc",
         "valueBoolean": true
       }
     ],
     "type": {
       "coding": [
         {
           "system": "https://www.healthgorilla.com/order-billto",
           "code": "thirdParty",
           "display": "Third Party"
         }
       ],
       "text": "Third Party"
     },
     "coverage": [
       {
         "coverage": {
           "reference": "#2"
         },
         "priority": 1
       }
     ]
   },
   {
     "resourceType": "Coverage",
     "id": "2",
     "identifier": [
       {
         "value": "619A988989"
       }
     ],
     "status": "active",
     "subscriber": {
       "reference": "#3"
     },
     "beneficiary": {
       "reference": "Patient/03db43522cc01432572e0a53",
       "display": "Bart Simpson"
     },
     "relationship": {
       "coding": [
         {
           "system": "http://hl7.org/fhir/policyholder-relationship",
           "code": "parent",
           "display": "Parent"
         }
       ],
       "text": "Parent"
     },
     "payor": [
       {
         "reference": "Organization/ip-5",
         "display": "ANTHEM BLUE CROSS OF CALIFORNI"
       }
     ],
     "grouping": {
       "group": "GOOGLEPLEX"
     }
   },
   {
     "resourceType": "RelatedPerson",
     "id": "3",
     "extension": [
       {
         "url": "https://www.healthgorilla.com/fhir/StructureDefinition/relatedperson-employer",
         "valueString": "Springfield Nuclear Plant"
       }
     ],
     "patient": {
       "reference": "Patient/03db43522cc01432572e0a53",
       "display": "Bart Simpson"
     },
     "relationship": {
       "coding": [
         {
           "system": "http://hl7.org/fhir/policyholder-relationship",
           "code": "parent",
           "display": "Parent"
         }
       ],
       "text": "Parent"
     },
     "name": [
       {
         "family": "Simpson",
         "given": [
           "Homer"
         ]
       }
     ],
     "telecom": [
       {
         "system": "phone",
         "value": "000 000 0000",
         "use": "home"
       }
     ],
     "gender": "male",
     "birthDate": "1960-02-20",
     "address": [
       {
         "text": "742 Evergreen Terrace, Springfield, USA, CT 11111",
         "line": [
           "742 Evergreen Terrace"
         ],
         "city": "Springfield",
         "state": "CT",
         "postalCode": "111111",
         "country": "USA"
       }
     ]
   },
   ...
 ],
 "extension": [
   {
     "url": "https://www.healthgorilla.com/fhir/StructureDefinition/requestgroup-account",
     "valueReference": {
       "reference": "#1"
     }
   },
   ...
 ],
 ...
}

Procedure Request

ProcedureRequest describes the diagnostic procedure requested within the order. It should be an internal resource referenced in RequestGroup.action.resource. Each laboratory supports the certain set of tests that can be ordered. Health Gorilla provides API that should be used to obtain available tests for the given facility.

Here you can find attributes that are expected to be specified.

ProcedureRequest.category

This attribute must have the following value:

...
"category": [
       {
         "coding": [
           {
             "system": "http://snomed.info/sct",
             "code": "103693007",
             "display": "Diagnostic procedure"
           }
         ]
       }
     ]
...

ProcedureRequest.status

This attribute must have the following value:
System: http://hl7.org/fhir/request-status

Code

Display

Definition

active

Active

The request is ready to be acted upon

ProcedureRequest.intent

This attribute must have the following value:
System: http://hl7.org/fhir/request-intent

Code

Display

Definition

order

Order

The request represents a request/demand and authorization for action

ProcedureRequest.priority

This attribute allows to set priority for the given test within the order. This is an optional attribute.
You can use the following values, if the certain test should be submitted with high priority:
System: http://hl7.org/fhir/request-priority

Code

Display

Definition

urgent

urgent

The request should be actioned promptly - higher priority than routine

asap

ASAP

The request should be actioned as soon as possible - higher priority than urgent

stat

STAT

The request should be actioned immediately - highest possible priority. E.g. an emergency

You can use the following values, if it should be indicated, that the certain test has ‘unscheduled’ priority:
System: http://hl7.org/fhir/request-priority

Code

Display

Definition

routine

Routine

The request has normal priority

ProcedureRequest.code

This is the code, that identifies the particular test ordered. Mandatory.

Example

{
 "code": {
   "coding": [
     {
       "code": "074666",
       "display": "074666 9 Drug-Scr"
     }
   ],
   "text": "074666 9 Drug-Scr"
 }
}

ProcedureRequest.supportingInfo

This is a reference to an internal QuestionnaireResponse resource that contains list of ‘order entry questions’ (AOEs) answers related to the given diagnostic procedure.

AOE can be required to be answered, or may be optional. If AOE is required for the specified configuration (performer, test, specimen), but missed in the request, then the whole order will be rejected. Only answered AOEs should be included into request.

If different tests refer to the same order-level AOE, then the answer should be the same for all tests.

There are different types of AOE answers supported:

  • Date
  • String
  • Boolean
  • Coding

Examples

{
 "resourceType": "RequestGroup",
 "meta": {
   "profile": [
     "https://healthgorilla.com/fhir/StructureDefinition/hg-order"
   ]
 },
 "contained": [
   {
     "resourceType": "QuestionnaireResponse",
     "id": "aoes",
     "status": "completed",
     "item": [
       {
         "linkId": "ZBL-1",
         "answer": [
           {
             "valueCoding": {
               "code": "1",
               "display": "White/Caucasian"
             }
           }
         ]
       },
       {
         "linkId": "ZBL-2",
         "answer": [
           {
             "valueCoding": {
               "code": "1",
               "display": "Yes"
             }
           }
         ]
       },
       {
         "linkId": "ZBL-3",
         "answer": [
           {
             "valueCoding": {
               "code": "V",
               "display": "Venous (blood)"
             }
           }
         ]
       },
       {
         "linkId": "ZBL-4",
         "answer": [
           {
             "valueCoding": {
               "code": "R",
               "display": "Repeat"
             }
           }
         ]
       }
     ]
   },
   {
     "resourceType": "ProcedureRequest",
     "id": "test",
     "status": "active",
     "intent": "order",
     "priority": "stat",
     "category": [
       {
         "coding": [
           {
             "system": "http://snomed.info/sct",
             "code": "103693007",
             "display": "Diagnostic procedure"
           }
         ]
       }
     ],
     "code": {
       "coding": [
         {
           "code": "007625",
           "display": "Lead, Blood (Adult)"
         }
       ],
       "text": "Lead, Blood (Adult)"
     },
     "supportingInfo": [
       {
         "reference": "#aoes"
       }
     ]
   },
   ...
 ],
 ...
 "action": [
   {
     "resource": {
       "reference": "#test",
       "display": "074666 9 Drug-Scr"
     }
   }
 ],
 ...
}

Answer of type String

{
 "linkId": "AOE-001",
 "test": "Topography",
 "answer": [
   {
     "valueString": "Yes"
   }
 ]
}

Answer of type Boolean

{
 "linkId": "AOE-002",
 "test": "Topography",
 "answer": [
   {
     "valueBoolean": true
   }
 ]
}

Answer of type Coding

{
 "linkId": "AOE-003",
 "answer": [
   {
     "valueCoding": {
       "code": "1",
       "display": "Yes"
     }
   }
 ]
}

Answer of type Date

{
 "linkId": "AOE-004",
 "answer": [
   {
     "valueDate": "2016-01-15"
   }
 ]
}

ProcedureRequest.note

Any notes and comments related to the given test.

Endpoint

The FHIR Create interaction (https://www.hl7.org/fhir/http.html#create) should be used to submit an order:

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

Endpoint accepts HTTP POST request, and expects RequestGroup resource passed (json or xml).

🚧

This operations can take a long time to complete, therefore it must be performed asynchronously.

Once order submitted, then HTTP 201 will be returned and newly created resource location included into the response header.
Location ->

http://api.healthgorilla.com/fhir/RequestGroup/0fb0ac5b2a203b8a3f078400

Splitting Orders

If there are too many tests ordered within the order, or selected tests cannot be included into a single order, then server rejects the request and suggests the way of grouping.
In this case, HTTP 200 OK is returned, OperationOutcome included and contains
‘order-splitting-required’ issue and https://www.healthgorilla.com/fhir/StructureDefinition/operationoutcome-order-splitting’ extension with suggested grouping.

009001|488162;500199

Example

The LabCorp order submitted and the following test are ordered:

  • 009001 Fine-Needle Aspiration
  • 488162 Prostate Biopsies
  • 500199 Human Papillomavirus, Biopsy
    Server returns HTTP 200 response:
{
    "resourceType": "OperationOutcome",
    "extension": [
        {
            "url": "https://www.healthgorilla.com/fhir/StructureDefinition/operationoutcome-order-splitting",
            "valueString": "009001|488162;500199"
        }
    ],
    "issue": [
        {
            "severity": "fatal",
            "code": "processing",
            "details": {
                "coding": [
                    {
                        "code": "order-splitting-required"
                    }
                ],
                "text": "Splitting required"
            }
        }
    ]
}

This means that the client should split the initial order into two and include test in the way below:

  • RequestGroup (009001)
  • RequestGroup (488162 and 500199)

HTTP 201 and Warning

Sometimes server may return a warning. It means that the order has been submitted, but something went wrong and end-user should be notified.

{
 "resourceType": "OperationOutcome",
 "issue": [
   {
     "severity": "error",
     "code": "informational",
     "details": {
       "coding": [
         {
           "code": "order-warning"
         }
       ],
       "text": "Your order has been submitted, but we were not able to fax it due to an unexpected error."
     }
   }
 ]
}

Errors

When the order is submitted, then two phase validation is performed on the server side.
Firstly server checks that the data structure is correct and all required attributes are in place. Server checks that all links are valid. If any errors occurred then common-FHIR error returned to the client.

Secondly server processes the request and checks, that the given order matches all business rules depending on the specified performer, requester and ordered tested.

Resource Validation Errors

Common FHIR-related errors

HTTP Status

Details

400 Bad Request

resource could not be parsed or failed basic FHIR validation rules - Content

404 Not Found

resource type not supported, or not a FHIR end-point

422 Unprocessable Entity

the proposed resource violated applicable FHIR profiles or server business rules. This should be accompanied by an OperationOutcome resource providing additional detail

Examples:

Performer missed in the request - HTTP 422

{
 "resourceType": "OperationOutcome",
 "issue": [
   {
     "severity": "error",
     "code": "processing",
     "diagnostics": "No performer supplied"
   }
 ]
}

Patient cannot be recognized by server - HTTP 422

{
 "resourceType": "OperationOutcome",
 "issue": [
   {
     "severity": "error",
     "code": "processing",
     "diagnostics": "Supplied Patient is unknown."
   }
 ]
}

Unknown test ordered - HTTP 422

{
 "resourceType": "OperationOutcome",
 "issue": [
   {
     "severity": "error",
     "code": "processing",
     "diagnostics": "Ordered tests cannot be found."
   }
 ]
}

Processing Errors

If the verification of business rules failed or an error occurred then HTTP 200 OK with OperationOutcome resource returned.

The following error codes are supported:

Code

Details

order-validity-unknown

Validation failed, reason is unknown.

order-error

Unexpected error occured during submitting.

order-practice-an-required

Practice Account Number required to be set.

order-invalid

Validation failed, order cannot be submitted.

order-aoes-notanswered

Required AOEs are not answered.

order-el-notpossible

Electronic ordering is not possible for the given laboratory and physician.

order-el-connectionfailed

Order cannot be submitted electronically due to a communication error.

order-el-error

An error occurred

order-abn-required

ABN form must be printed

Examples:

Doctor Account Number required, but missed - HTTP 200

{
 "resourceType": "OperationOutcome",
 "issue": [
   {
     "severity": "error",
     "code": "invalid",
     "details": {
       "coding": [
         {
           "code": "order-invalid"
         }
       ],
       "text": "Account/Client Number must be 8 digits long number"
     }
   }
 ]
}

Examples

Submit LabCorp order

{
 "resourceType": "RequestGroup",
 "meta": {
   "profile": [
     "https://healthgorilla.com/fhir/StructureDefinition/hg-order"
   ]
 },
 "contained": [
   {
     "resourceType": "QuestionnaireResponse",
     "id": "aoes",
     "status": "completed",
     "item": [
       {
         "linkId": "ZBL-1",
         "answer": [
           {
             "valueCoding": {
               "code": "1",
               "display": "White/Caucasian"
             }
           }
         ]
       },
       {
         "linkId": "ZBL-2",
         "answer": [
           {
             "valueCoding": {
               "code": "1",
               "display": "Yes"
             }
           }
         ]
       },
       {
         "linkId": "ZBL-3",
         "answer": [
           {
             "valueCoding": {
               "code": "V",
               "display": "Venous (blood)"
             }
           }
         ]
       },
       {
         "linkId": "ZBL-4",
         "answer": [
           {
             "valueCoding": {
               "code": "R",
               "display": "Repeat"
             }
           }
         ]
       }
     ]
   },
   {
     "resourceType": "ProcedureRequest",
     "id": "test",
     "status": "active",
     "intent": "order",
     "priority": "stat",
     "category": [
       {
         "coding": [
           {
             "system": "http://snomed.info/sct",
             "code": "103693007",
             "display": "Diagnostic procedure"
           }
         ]
       }
     ],
     "code": {
       "coding": [
         {
           "code": "007625",
           "display": "Lead, Blood (Adult)"
         }
       ],
       "text": "Lead, Blood (Adult)"
     },
     "supportingInfo": [
       {
         "reference": "#aoes"
       }
     ]
   },
   {
     "resourceType": "Account",
     "id": "1",
     "meta": {
       "profile": [
         "https://healthgorilla.com/fhir/StructureDefinition/hg-order-account"
       ]
     },
     "type": {
       "coding": [
         {
           "system": "https://www.healthgorilla.com/order-billto",
           "code": "patient",
           "display": "Patient"
         }
       ],
       "text": "Patient"
     }
   },
   {
     "resourceType": "Practitioner",
     "id": "4",
     "identifier": [
       {
         "type": {
           "coding": [
             {
               "system": "http://hl7.org/fhir/v2/0203",
               "code": "PRN",
               "display": "Passport number"
             }
           ]
         },
         "system": "http://hl7.org/fhir/sid/us-npi",
         "value": "1234567893"
       },
       {
         "type": {
           "coding": [
             {
               "system": "http://hl7.org/fhir/v2/0203",
               "code": "AN",
               "display": "Account number"
             }
           ],
           "text": "Account Number"
         },
         "value": "04843980"
       }
     ],
     "active": true,
     "name": [
       {
         "family": "Doe",
         "given": [
           "John"
         ],
         "suffix": [
           "M.D."
         ]
       }
     ]
   },
   {
     "resourceType": "Organization",
     "id": "5",
     "identifier": [
       {
         "type": {
           "coding": [
             {
               "system": "http://hl7.org/fhir/v2/0203",
               "code": "AN",
               "display": "Account number"
             }
           ],
           "text": "Account Number"
         },
         "value": "1A45HT6"
       }
     ],
     "name": "Dr. Doe Practice - 1825 Somestreet st, Sacramento, CA"
   },
   {
     "resourceType": "Specimen",
     "id": "6",
     "collection": {
       "collectedDateTime": "2018-09-20T12:21:26+03:00"
     }
   }
 ],
 "extension": [
   {
     "url": "https://www.healthgorilla.com/fhir/StructureDefinition/requestgroup-authorizedBy",
     "valueReference": {
       "reference": "Organization/tl-d5da4352af2201ace56ca725-01db4352f2deaeb1173e0444",
       "display": "Dr. Doe Practice"
     }
   },
   {
     "url": "https://www.healthgorilla.com/fhir/StructureDefinition/requestgroup-account",
     "valueReference": {
       "reference": "#1"
     }
   },
   {
     "url": "https://www.healthgorilla.com/fhir/StructureDefinition/requestgroup-performer",
     "valueReference": {
       "reference": "Organization/f-d5da4352df37dd00cfb1e115",
       "display": "LabCorp"
     }
   },
   {
     "url": "https://www.healthgorilla.com/fhir/StructureDefinition/requestgroup-requester",
     "extension": [
       {
         "url": "agent",
         "valueReference": {
           "reference": "#4"
         }
       },
       {
         "url": "onBehalfOf",
         "valueReference": {
           "reference": "#5"
         }
       }
     ]
   },
   {
     "url": "https://www.healthgorilla.com/fhir/StructureDefinition/requestgroup-reasoncode",
     "valueCodeableConcept": {
       "coding": [
         {
           "system": "http://hl7.org/fhir/sid/icd-10",
           "code": "Z79.4",
           "display": "Long term (current) use of insulin"
         }
       ],
       "text": "Long term (current) use of insulin"
     }
   },
   {
     "url": "https://www.healthgorilla.com/fhir/StructureDefinition/requestgroup-reasoncode",
     "valueCodeableConcept": {
       "coding": [
         {
           "system": "http://hl7.org/fhir/sid/icd-10",
           "code": "E09.51",
           "display": "Drug or chemical induced diabetes mellitus with diabetic peripheral angiopathy without gangrene"
         },
         {
           "system": "http://snomed.info/sct",
           "code": "8801005",
           "display": "Secondary diabetes mellitus"
         }
       ],
       "text": "Drug or chemical induced diabetes mellitus with diabetic peripheral angiopathy without gangrene"
     }
   },
   {
     "url": "https://www.healthgorilla.com/fhir/StructureDefinition/requestgroup-specimen",
     "valueReference": {
       "reference": "#6"
     }
   },
   {
     "url": "https://www.healthgorilla.com/fhir/StructureDefinition/requestgroup-deliveryOptions",
     "extension": [
       {
         "url": "electronic",
         "valueBoolean": true
       }
     ]
   }
 ],
 "status": "active",
 "intent": "order",
 "subject": {
   "reference": "Patient/03db43522cc01432572e0a53",
   "display": "Bart Simpson"
 },
 "author": {
   "reference": "Practitioner/fc076a524383b188ffc10051",
   "display": "Robert Kelso, M.D."
 },
 "note": [
   {
     "text": "Patient claims that his skin is yellow."
   }
 ],
 "action": [
   {
     "resource": {
       "reference": "#test",
       "display": "074666 9 Drug-Scr"
     }
   }
 ]
}

Compendium

Health Gorilla provides API that can be used to obtain procedures/tests supported by the given diagnostic provider.

The following FHIR resources are involved:

Organization and Location

If Organization or Location supports ordering, then it has reference to related compendium.
This is a link to ValueSet resource, that contains compendium items available for ordering in the certain Organization or Location.

Organization - compendium

https:/api.healthgorilla.com/fhir/StructureDefinition/provider-compendium

Example:

{
    "resourceType": "Organization",
    "id": "f-d5da4352df37dd00cfb1e115",
    ...
    "extension": [
        {
            "url": "https://www.healthgorilla.com/fhir/StructureDefinition/provider-compendium",
            "valueReference": {
                "reference": "ValueSet/f-d5da4352df37dd00cfb1e115"
            }
        }
    ],
    "name": "LabCorp",
    ...
}

The example above contains link to tests that can be ordered in LabCorp:

https://api.healthgorilla.com/fhir/ValueSet/f-d5da4352df37dd00cfb1e115

CodeSystem

As per https://www.hl7.org/fhir/codesystem.html CodeSystem declares the existence of and describes a code system and its key properties. Also known as Ontology, Terminology, or Enumeration. Code systems define which codes (symbols and/or expressions) exist, and how they are understood. Our CodeSystem endpoint implements the common FHIR lookup operation that can be used to get information about the specific test.
Available properties:

Property

Cardinality

Type

Description

display

1..1

String

Display string

definition

0..1

String

Detailed description

property.aoe

0..1

Boolean

AOEs required

property.specimen-type

0..1

String

Specimen Type

property.specimen-container

0..1

String

Specimen Container

property.specimen-collection

0..1

String

Specimen Collection

property.specimen-storage

0..1

String

Specimen Storage

property.linked-compendium-required

0..*

Coding

Test that must be included to the same order.

property.linked-compendium-recommended

0..*

Coding

Test that should be included to the same order.

property.cpt

0..*

Coding

Related CPT codes

property.group

0..1

Coding

Radiology Group

property.homeDraw

0..1

Boolean

Is procedure available for home draw

property.procedure-request

0..*

Coding

Individual tests included in the panel, if any.

If ‘aoe’ property of CodeSystem element is ‘True’ then it means that it has Ask at Order Entry (AOE) questions related to this test and answers should be included in the RequestGroup that includes corresponding ProcedureRequest.

Example:

https://api.healthgorilla.com/fhir/CodeSystem/$lookup?system=urn:uuid:d5da4352df37dd00cfb1e115&code=085928
{
    "resourceType": "Parameters",
    "parameter": [
        {
            "name": "name",
            "valueString": "LabCorp Compendium Items"
        },
        {
            "name": "display",
            "valueString": "Immunoglobulin G,Syn Rate,CSF"
        },
        {
            "name": "property",
            "part": [
                {
                    "name": "code",
                    "valueString": "specimen-type"
                },
                {
                    "name": "value",
                    "valueString": "Serum AND cerebrospinal fluid (CSF)"
                }
            ]
        },
        {
            "name": "property",
            "part": [
                {
                    "name": "code",
                    "valueString": "specimen-container"
                },
                {
                    "name": "value",
                    "valueString": "Red-top tube or gel-barrier tube AND sterile (CSF) container"
                }
            ]
        },
        {
            "name": "property",
            "part": [
                {
                    "name": "code",
                    "valueString": "specimen-storage"
                },
                {
                    "name": "value",
                    "valueString": "Refrigerate"
                }
            ]
        },
        {
            "name": "property",
            "part": [
                {
                    "name": "code",
                    "valueString": "cpt"
                },
                {
                    "name": "value",
                    "valueCoding": {
                        "system": "http://www.ama-assn.org/go/cpt",
                        "code": "82040 001"
                    }
                }
            ]
        },
        {
            "name": "property",
            "part": [
                {
                    "name": "code",
                    "valueString": "cpt"
                },
                {
                    "name": "value",
                    "valueCoding": {
                        "system": "http://www.ama-assn.org/go/cpt",
                        "code": "82042 001"
                    }
                }
            ]
        },
        {
            "name": "property",
            "part": [
                {
                    "name": "code",
                    "valueString": "cpt"
                },
                {
                    "name": "value",
                    "valueCoding": {
                        "system": "http://www.ama-assn.org/go/cpt",
                        "code": "82784 002"
                    }
                }
            ]
        }
    ]
}

ValueSet

Value Sets select a set of codes from one or more code systems to specify which codes can be used in a particular context.

Expand

Our ValueSet endpoint implements the common FHIR expand operation, that can be used to lookup a specific test in the specified ValueSet

The following attributes are supported:

Attribute

Cardinality

Type

Description

filter

1..1

string

Text filter that is applied to restrict the codes that are returned.

procedure

0..*

token

Return only those compendium items that are associated with the specified CPT codes.

offset

0..1

integer

Paging support - where to start if a subset is queried.

count

0..1

integer

Paging support - how many codes should be provided in a partial page view.

includeParameters

0..1

boolean

Indicates that test parameters should be included into the response.
Default: false

Example:

Find first five tests that match the query ‘Immunoglobulin’ in the CodeSystem of organization with "f-d5da4352df37dd00cfb1e115" id.

https://api.healthgorilla.com/fhir/ValueSet/f-d5da4352df37dd00cfb1e115/$expand?filter=Immunoglobulin&count=5
{
    "resourceType": "ValueSet",
    "status": "active",
    "expansion": {
        "identifier": "c377b75b3d16a7de376f2f77",
        "timestamp": "2018-10-05T17:40:03+03:00",
        "total": 14,
        "parameter": [
            {
                "name": "query",
                "valueString": "Immunoglobulin"
            }
        ],
        "contains": [
            {
                "system": "urn:uuid:d5da4352df37dd00cfb1e115",
                "code": "001784",
                "display": "Immunoglobulin A, Qn, Serum"
            },
            {
                "system": "urn:uuid:d5da4352df37dd00cfb1e115",
                "code": "100115",
                "display": "Immunoglobulin A, Quant, CSF"
            },
            {
                "system": "urn:uuid:d5da4352df37dd00cfb1e115",
                "code": "002162",
                "display": "Immunoglobulin D, Quant, Serum"
            },
            {
                "system": "urn:uuid:d5da4352df37dd00cfb1e115",
                "code": "002170",
                "display": "Immunoglobulin E, Total"
            },
            {
                "system": "urn:uuid:d5da4352df37dd00cfb1e115",
                "code": "002238",
                "display": "Immunoglobulin G Index"
            }
        ]
    }
}

Search in generic radiology compendium by test code 'CT63' and return test parameters in the response.

https://api.healthgorilla.com/fhir/ValueSet/compendium-radiology/$expand?
filter=CT63&includeParameters=true&_format=json
{
    "resourceType": "ValueSet",
    "contained": [
        {
            "resourceType": "Parameters",
            "id": "1",
            "parameter": [
                {
                    "name": "name",
                    "valueString": "Compendium Items"
                },
                {
                    "name": "display",
                    "valueString": "Head"
                },
                {
                    "name": "property",
                    "part": [
                        {
                            "name": "code",
                            "valueString": "aoe"
                        },
                        {
                            "name": "value",
                            "valueBoolean": true
                        }
                    ]
                },
                {
                    "name": "property",
                    "part": [
                        {
                            "name": "code",
                            "valueString": "group"
                        },
                        {
                            "name": "value",
                            "valueCoding": {
                                "code": "CT_Scan",
                                "display": "CT Scan"
                            }
                        }
                    ]
                }
            ]
        }
    ],
    "status": "active",
    "expansion": {
        "identifier": "75e9515f0f5a60ec8f3cc0fd",
        "timestamp": "2020-09-04T07:15:01+00:00",
        "total": 1,
        "parameter": [
            {
                "name": "query",
                "valueString": "CT63"
            }
        ],
        "contains": [
            {
                "extension": [
                    {
                        "url": "parameters",
                        "valueReference": {
                            "reference": "#1"
                        }
                    }
                ],
                "system": "https://www.healthgorilla.com/compendium-radiology",
                "code": "CT63",
                "display": "Head"
            }
        ]
    }
}

Lookup in generic radiology compendium by procedure name 'axillae' that are also associated with the given CPT codes.

https://api.healthgorilla.com/fhir/ValueSet/compendium-radiology/$expand?
?filter=axillae&procedure=12032,25515

Search

Health Gorilla also provides custom operation to search compendium items with a wide range of parameters. If your account was setup with custom compendium or was restricted only to include certain tests then Search operation will return codes from those that available to your account. It doesn't use specific CodeSet to return values and uses only parameters as a filter.

https://api.healthgorilla.com/fhir/ValueSet/$search

Attribute

Cardinality

Type

Description

filter

1..1

string

Text filter that is applied to restrict the ValueSet codes that are returned.

organization

1..*

reference

One or more organization identifier where to search for compendium items.

home-draw

0..1

token

true/false
If true - return only tests available for home draw.

procedure

0..*

token

Return only those compendium items that are associated with the specified CPT codes.

offset

0..1

number

Paging support - where to start if a subset is queried.

count

0..1

number

Paging support - how many codes should be provided in a partial page

includeParameters

0..1

boolean

Indicates that test parameters should be included into the response.
Default: false

Example
Return first 10 results of all 'COVID-19' tests available for home draw from organizations with 'f-01db4352f2deaeb1173e0444' or 'f-d5da43523ded70612e79f479' identifiers

https://api.healthgorilla.com/fhir/ValueSet/$search
?filter=COVID-19
&home-draw=true
&organizaton=f-01db4352f2deaeb1173e0444,f-d5da43523ded70612e79f479
&offset=0
&count=10
{
    "resourceType": "ValueSet",
    "status": "active",
    "expansion": {
        "identifier": "c377b75b3d16a7de376f2f77",
        "timestamp": "2018-10-05T17:40:03+03:00",
        "total": 14,
        "parameter": [
            {
                "name": "query",
                "valueString": "COVID-19"
            }
        ],
        "contains": [
            {
                "system": "urn:uuid:d5da4352df37dd00cfb1e115",
                "code": "0019B7",
                "display": "COVID-19, blood"
            },
            ...
        ]
    }
}

Questionnaire

Questionnaire resource is used to describe Ask at Order Entry (AOE) questions.

Supported item types:
System: http://hl7.org/fhir/item-type

Code

Display

Definition

date

Date

Question with a date answer (valueDate)

string

String

Question with a short (few words to short sentence) free-text entry answer (valueString)

choice

Choice

Question with a Coding drawn from a list of options (specified in either the option property, or via the valueset referenced in the options property) as an answer (valueCoding)

open-choice

Open Choice

Answer is a Coding drawn from a list of options (as with the choice type) or a free-text entry in a string (valueCoding or valueString)

Get AOE questions and answers

HTTP Request

Method

Description

Questionnaire?[parameter={value}]

GET

Lookup for AOE questions/answers for the given compendium item.

Parameters:

Parameter

Cardinality

Type

Description

code

1..1

token

The compendium item code.

procedure

0..*

token

Return only those AOE answers that are associated with the specified CPT codes.

Example:

Get AOE questions for the given laboratory compendium item.

https://api.healthgorilla.com/fhir/Questionnaire?code=urn:uuid:d5da4352df37dd00cfb1e115%7C198330

Get AOE questions for the radiology compendium item with code 'MR28', and return only answers that are associated with the procedure with CPT code 12032.

https://api.healthgorilla.com/fhir/Questionnaire?
code=https://www.healthgorilla.com/compendium-radiology%7CMR28
&procedure=12032
&_format=json
{
 "resourceType": "Questionnaire",
 "id": "e2da43522638191129bd11ca",
 "name": "PapIG, CtNgTvHSV, rfxHPVall AOE questions",
 "status": "active",
 "code": [
   {
     "system": "urn:uuid:d5da4352df37dd00cfb1e115",
     "code": "198330"
   }
 ],
 "subjectType": [
   "Patient"
 ],
 "item": [
   {
     "id": "ZCY-1",
     "extension": [
       {
         "url": "https://www.healthgorilla.com/fhir/StructureDefinition/questionnaire-requiredwhenspecimen",
         "valueBoolean": true
       },
       {
         "url": "https://www.healthgorilla.com/fhir/StructureDefinition/questionnaire-constraints",
         "valueString": "Use: Gynecological source"
       },
       {
         "url": "http://hl7.org/fhir/StructureDefinition/questionnaire-itemControl",
         "valueCodeableConcept": {
           "coding": [
             {
               "code": "textBox"
             }
           ]
         }
       }
     ],
     "code": [
       {
         "code": "ZCY-1"
       }
     ],
     "text": "Cervical",
     "type": "string"
   },
   ...
   {
     "id": "ZCY-12",
     "extension": [
       {
         "url": "https://www.healthgorilla.com/fhir/StructureDefinition/questionnaire-requiredwhenspecimen",
         "valueBoolean": true
       },
       {
         "url": "https://www.healthgorilla.com/fhir/StructureDefinition/questionnaire-constraints",
         "valueString": "Use: Date of patient's last menstrual period or menopausal date."
       },
       {
         "url": "http://hl7.org/fhir/StructureDefinition/questionnaire-itemControl",
         "valueCodeableConcept": {
           "coding": [
             {
               "code": "localDate"
             }
           ]
         }
       }
     ],
     "code": [
       {
         "code": "ZCY-12"
       }
     ],
     "text": "LMP-Meno Date",
     "type": "date"
   },
   ...
   {
     "id": "DEV_AOE",
     "extension": [
       {
         "url": "http://hl7.org/fhir/StructureDefinition/questionnaire-itemControl",
         "valueCodeableConcept": {
           "coding": [
             {
               "code": "multiselect"
             }
           ]
         }
       }
     ],
     "code": [
       {
         "code": "DEV-AOE"
       }
     ],
     "text": "Question",
     "type": "choice",
     "repeat": true,
     "option": [
         {
            "valueCoding": {
                "code": "1",
                "display": "Adenoids"
            }
         },
         ...
         {
            "valueCoding": {
                "code": "9",
                "display": "Nasopharynx"
            }

         },
         ...
     ],
     "initialString": "Bone"
   },
   ...
 ]
}

Extensions

https://www.healthgorilla.com/fhir/StructureDefinition/questionnaire-requiredwhenspecimen
{
   "id":"ZCY-12",
   "extension":[
      {
         "url":"https://www.healthgorilla.com/fhir/StructureDefinition/questionnaire-requiredwhenspecimen",
         "valueBoolean":true
      },
      ...
   ],
   "code":[
      {
         "code":"ZCY-12"
      }
   ],
   "text":"LMP-Meno Date",
   "type":"date"
},
...
https://www.healthgorilla.com/fhir/StructureDefinition/questionnaire-constraints
{
   "id":"ZCY-12",
   "extension":[
      {
         "url":"https://www.healthgorilla.com/fhir/StructureDefinition/questionnaire-constraints",
         "valueString":"Use: Date of patient's last menstrual period or menopausal date."
      },
      ...
   ],
   "code":[
      {
         "code":"ZCY-12"
      }
   ],
   "text":"LMP-Meno Date",
   "type":"date"
},
...
http://hl7.org/fhir/StructureDefinition/questionnaire-itemControl
{
   "id":"ZCY-12",
   "extension":[
      {
         "url":"http://hl7.org/fhir/StructureDefinition/questionnaire-itemControl",
         "valueCodeableConcept":{
            "coding":[
               {
                  "code":"localDate"
               }
            ]
         }
      },
      ...
   ],
   "code":[
      {
         "code":"ZCY-12"
      }
   ],
   "text":"LMP-Meno Date",
   "type":"date"
},
...
https://www.healthgorilla.com/fhir/StructureDefinition/questionnaire-optionEnableWhen
...
"option":[
   {
      "extension":[
         {
            "url":"https://www.healthgorilla.com/fhir/StructureDefinition/questionnaire-optionEnableWhen",
            "valueCoding":{
               "system":"http://www.ama-assn.org/go/cpt",
               "code":"12032"
            }
         }
      ],
      "valueCoding":{
         "code":"left",
         "display":"Left"
      }
   },
   {
      "valueCoding":{
         "code":"right",
         "display":"Right"
      }
   },
   {
      "valueCoding":{
         "code":"bi",
         "display":"Bilateral"
      }
   }
]
},
...

Return CPT codes for the specified question/answers combination

HTTP Request

Method

Action

/Questionnaire/{ID}/$procedures

POST

Get list of CPT codes associated with the specified question/answers.

You send HTTP POST request with QuestionnaireResponse payload to the Questionnaire endpoint.

Example:

https://api.healthgorilla.com/fhir/Questionnaire/e2da43522638191129bd11ca/$procedures
{
   "resourceType":"QuestionnaireResponse",
   "id":"aoes",
   "status":"completed",
   "questionnaire":{
      "reference":"Questionnaire/e2da43522638191129bd11ca"
   },
   "item":[
      {
         "linkId":"side",
         "answer":[
            {
               "valueCoding":{
                  "code":"left",
                  "display":"Left"
               }
            }
         ]
      },
      {
         "linkId":"contrast",
         "answer":[
            {
               "valueCoding":{
                  "code":"V01",
                  "display":"contrast"
               }
            }
         ]
      }
   ]
}
{
    "resourceType": "Parameters",
    "parameter": [
        {
            "name": "procedure",
            "valueCoding": {
                "system": "http://www.ama-assn.org/go/cpt",
                "code": "12032"
            }
        }
    ]
}

Populate AOE answers for the specified patient

Health Gorilla implements Populate Questionnaire operation, that can be used to populate AOE answers for the specified patient based on the known demographic information.

Parameters

Cardinality

Type

Description

local

1..1

token

Always true to use the local patient demographic.

subject

1..1

reference

Reference to the patient.

Example

https://qa.healthgorilla.com/fhir/Questionnaire/fe95305b6e4b6ff3fc91bcca/$populate?subject=03db43522cc01432572e0a53&local=true
{
    "resourceType": "QuestionnaireResponse",
    "questionnaire": {
        "reference": "Questionnaire/fe95305b6e4b6ff3fc91bcca"
    },
    "status": "in-progress",
    "subject": {
        "reference": "Patient/03db43522cc01432572e0a53"
    },
    "item": [
        {
            "linkId": "ZBL-1",
            "text": "Patient Race",
            "answer": [
                {
                    "valueCoding": {
                        "code": "1",
                        "display": "White/Caucasian"
                    }
                }
            ]
        },
        {
            "linkId": "ZBL-2",
            "text": "Hispanic Heritage",
            "answer": [
                {
                    "valueCoding": {
                        "code": "2",
                        "display": "No"
                    }
                }
            ]
        },
        {
            "linkId": "ZBL-3",
            "text": "Blood Lead Type"
        },
        {
            "linkId": "ZBL-4",
            "text": "Blood Lead Purpose"
        }
    ]
}

Diagnostic Providers

Health Gorilla provides API that can be used to lookup diagnostic provider by name, type and location.

Organization

Organization resource describes an abstract HealthCare provider. Some Organizations support electronic ordering and can be assigned as diagnostic procedure performer.

The following parameters can be used in search request:

Name

Type

Description

type

token

A code for the type of organization.

name

string

A portion of the organization's name or alias.

ordering-enabled

token

A ordering-enabled property. Use to get only organizations that support ordering.

_count

number

A positive integer. If passed, then server will not return more then specified.

Examples:

https://api.healthgorilla.com/fhir/Organization
?type=https://www.healthgorilla.com/facility-type|RadiologyImaging
&name=Rad
&ordering-enabled=true

Location

Location resource describes the specific health organization location. Examples of location can be specimen collection site (some times referred as patient service center or simply PSC) or outpatient laboratory.

Available location types:
System: http://hl7.org/fhir/v3/RoleCode

Code

Display

Definition

HUSCS

specimen collection site

A location that plays the role of delivering services which may include collecting specimens and/or samples from patients for laboratory testing purposes, but does not perform any tests or analysis functions.

OUTLAB

outpatient laboratory

A location that plays the role of delivering services which may include tests are done on clinical specimens to get health information about a patient pertaining to the diagnosis, treatment, and prevention of disease for same day visits.

HRAD

radiology unit

A location that plays the role of delivering services which may include the branch of medicine that uses ionizing and non-ionizing radiation to diagnose and treat diseases.

The following parameters can be used in search request:

Name

Type

Description

type

token

Code for the type of location.

name

string

Portion of the location's name or alias.

address-state

string

State specified in address.

address-city

string

City specified in address.

address-postalcode

string

Postal code specified in address.

ordering-enabled

token

Ordering-enabled property. Use to get only locations that support ordering.

near

token

Coordinates expressed as [latitude]:[longitude] (using the WGS84 datum, see notes) to find locations near to. If specified then 'near-distance' parameter is required.

near-distance

quantity

Distance in miles to limit the 'near' search to locations within a specific distance. When specified 'near' parameter must be included as well.

test-code

token

Test or study order code that the requested locations should support.

organization

reference

Searches for locations that are managed by the specified organization.

_count

number

Positive integer. If specified then the server will not return more search results than specified.

Examples:

Find RadNet locations in Sunnyvale that can perform CT Scan: Head/Brain

https://api.healthgorilla.com/fhir/Location
?organization=f-d8da435206d91f303d659ed7
&address-city=Sunnyvale
&test-code=CT64

Find first five LabCorp patient service centers near the specified GEO point.

https://api.healthgorilla.com/fhir/Location
?name=LabCorp
&type=HUSCS
&near=37.3910024:-122.0765676
&near-distance=10
&_count=5

Requisition Settings

As different diagnostic providers have own capabilities and settings for requisitioning Health Gorilla provides API that can be used to get these settings.

https://api.healthgorilla.com/fhir/Organization/ORGANIZATION_RESOURCE_ID

The following optional parameters can be specified depending on which the response might differ:

Name

Type

Description

requester

reference

The physician who is authorizing the order.
The Practitioner resource logical identifier.

requester.identifier

token

The physician who is authorizing the order.
The Practitioner's NPI identifier.

Response contains the following properties:

Property

Type

Description

orderingEnabled

Boolean

True if orders can be submitted for the given organization.

doctorAccountRequired

Boolean

True if physician's account is a required parameter when placing an order.

practiceAccountRequired

Boolean

True if clinic's account is a required parameter when placing an order.

compendiumUrl

ID

The ID of the value set that contains compendium for the given laboratory. If applicable.

electronicOrdering

Boolean

True if electronic ordering is supported for a given diagnostic vendor and physician/requester.

Examples:

Get laboratory requisition setting for the practitioner with NPI '1234567893'

https://api.healthgorilla.com/fhir/Organization/f-d8da43521fe28b2afddbd465/$requisition-settings?
requester.identifier=http://hl7.org/fhir/sid/us-npi|1234567893

Get laboratory requisition settings for the specified practitioner

https://api.healthgorilla.com/fhir/Organization/f-d8da43521fe28b2afddbd465/$requisition-settings?
requester=ceda4352e8f6405dd2e42f09

Get laboratory requisition settings that are not practitioner specific

https://api.healthgorilla.com/fhir/Organization/f-d8da43521fe28b2afddbd465/$requisition-settings

Example of returned requisition settings

{
    "resourceType": "Parameters",
    "parameter": [
        {
            "name": "orderingEnabled",
            "valueBoolean": true
        },
        {
            "name": "doctorAccountRequired",
            "valueBoolean": true
        },
        {
            "name": "practiceAccountRequired",
            "valueBoolean": false
        },
        {
            "name": "compendiumUrl",
            "valueId": "ValueSet/f-d8da43521fe28b2afddbd465"
        },
        {
            "name": "electronicOrdering",
            "valueBoolean": false
        }
    ]
}

ABN

Some diagnostic vendors require Advance Beneficiary Notice (ABN) form to be printed and signed by the patient to make requisition valid.

If the newly created order requires the ABN form to be printed, then the endpoint returns the following response.

{
    "resourceType": "OperationOutcome",
    "issue": [
        {
            "severity": "information",
            "code": "business-rule",
            "details": {
                "coding": [
                    {
                        "code": "order-abn-required"
                    }
                ],
                "text": "ABN is required."
            }
        }
    ]
}

Check ABN required

Health Gorilla provides $abn operation that allows you to check whether ABN form is needed for the given requisition or not.

Response contains the following properties:

Property

Type

Description

abnRequired

Boolean

url

String

Link to a Binary resource.
There are may be multiple ABN forms.

Check if ABN required for an existing order

https://api.healthgorilla.com/fhir/RequestGroup/REQUEST_GROUP_ID/$abn

Example:

GET /fhir/RequestGroup/3989aa5e5e9de54f3c22a8dc/$abn HTTP/1.1 
Host: api.healthgorilla.com 
Authorization: Bearer sldfksgkkG78dsdff787
HTTP/1.1 200 OK
Server: Apache-Coyote/1.1
X-Hg-Request-Id: 15e2305e94845d4d2f3f7796

{
    "resourceType": "Parameters",
    "parameter": [
        {
            "name": "abnRequired",
            "valueBoolean": true
        },
        {
            "name": "url",
            "valueString": "https://api.healthgorilla.com/fhir/Binary/3a89aa5ee4624e6f7e90903e"
        },
        {
            "name": "url",
            "valueString": "https://api.healthgorilla.com/fhir/Binary/3989aa5e5e9de54f3c22a8dc"
        }
    ]
}

Check if ABN required for the given RequestGroup

You can check if the ABN form is required for the given requisition order before submitting.

https://api.healthgorilla.com/fhir/RequestGroup/$abn
{
    "meta": {
        "profile": [
            "https://healthgorilla.com/fhir/StructureDefinition/hg-order"
        ]
    },
    "resourceType": "RequestGroup",
    "status": "active",
    ...
}

Example:

POST /fhir/RequestGroup/$abn HTTP/1.1 
Host: api.healthgorilla.com 
Authorization: Bearer sldfksgkkG78dsdff787
Content-Type: application/json 
[...omitted for brevity...]
HTTP/1.1 200 OK
Server: Apache-Coyote/1.1
X-Hg-Request-Id: 15e2305e94845d4d2f3f7796

{
    "resourceType": "Parameters",
    "parameter": [
        {
            "name": "abnRequired",
            "valueBoolean": false
        }
    ]
}