Lab 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

FHIR http://hl7.org/fhir/
SMART on FHIR http://docs.smarthealthit.org/
Health Gorilla FHIR Profiles
Health Gorilla FHIR Extensions
Health Gorilla FHIR Value Sets

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

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

If performer does not require Account Number to be passed for physician, then it should be a reference to an existing Practitioner resource.
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:

Send electronically
Send by fax
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 server returns the following responses:

Code	Details	HTTP response status code *
order-validity-unknown	Validation failed, reason is unknown.	422
order-error	Unexpected error occured during submitting.	500
order-practice-an-required	Practice Account Number required to be set.	422
order-invalid	Validation failed, order cannot be submitted.	422
order-aoes-notanswered	Required AOEs are not answered.	422
order-el-notpossible	Electronic ordering is not possible for the given laboratory and physician.	422
order-el-connectionfailed	Order cannot be submitted electronically due to a communication error.	500
order-el-error	An error occurred	500
order-abn-required	ABN form must be printed	422

* If API version greater than 12-01-2022. For older versions, the server will return HTTP 500 for an "order-el-connectionfailed" error, and HTTP 200 for other errors.

Examples:

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

{
    "resourceType": "OperationOutcome",
    "issue": [
        {
            "severity": "error",
            "code": "exception",
            "details": {
                "coding": [
                    {
                        "code": "order-el-connectionfailed"
                    }
                ],
                "text": "Electronic ordering is not possible due to a communication error talking to a third party infrastructure."
            }
        }
    ]
}

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
These resources contain link to compendium items that can be ordered (see ValueSet for more details).
CodeSystem
As per https://www.hl7.org/fhir/codesystem.html this resource represents the whole compendium supported by the given diagnostic provider.
ValueSet
As per https://www.hl7.org/fhir/codesystem.html this resource represents a set of codes or provider's compendium items from the given source CodeSystem, that are available for ordering in the certain diagnostic provider location.
[Questionnaire] (#questionnaire)
AOE questions for the given diagnostic test.

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. If not specified, default value is 10.

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
        }
    ]
}