Guides

Lab Network

Suggest Edits

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

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

CodeDisplayDefinition
activeActiveThe request is ready to be acted upon

RequestGroup.intent

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

CodeDisplayDefinition
orderOrderThe 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

CodeDisplayDefinition
urgenturgentThe request should be actioned promptly - higher priority than routine
asapASAPThe request should be actioned as soon as possible - higher priority than urgent
statSTATThe 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 - supervisingprovider

https://www.healthgorilla.com/fhir/StructureDefinition/requestgroup-supervisingprovider

This extension is used when a supervising provider's signature is required on a requisition form. This is the case in some states for radiology orders and specific to certain radiology centers.

The extension references an existing practitioner FHIR resource ID inside of your tenant. 

{
            "url": "https://www.healthgorilla.com/fhir/StructureDefinition/requestgroup-supervisingprovider",
            "valueReference": {
                "reference": "Practitioner/063e946057a62f75d26e11aba",
                "display": "Joe Gorilla"
            }
 },

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

CodeDisplayDefinition
PRPracticePractice
PRLPractice LocationPractice 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

CodeDisplay
FFacility

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

CodeDisplayDefinition
activeActiveThe request is ready to be acted upon

ProcedureRequest.intent

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

CodeDisplayDefinition
orderOrderThe 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

CodeDisplayDefinition
urgenturgentThe request should be actioned promptly - higher priority than routine
asapASAPThe request should be actioned as soon as possible - higher priority than urgent
statSTATThe 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

CodeDisplayDefinition
routineRoutineThe 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 StatusDetails
400 Bad Requestresource could not be parsed or failed basic FHIR validation rules - Content
404 Not Foundresource type not supported, or not a FHIR end-point
422 Unprocessable Entitythe 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:

CodeDetailsHTTP response status code *
order-validity-unknownValidation failed, reason is unknown.422
order-errorUnexpected error occured during submitting.500
order-practice-an-requiredPractice Account Number required to be set.422
order-invalidValidation failed, order cannot be submitted.422
order-aoes-notansweredRequired AOEs are not answered.422
order-el-notpossibleElectronic ordering is not possible for the given laboratory and physician.422
order-el-connectionfailedOrder cannot be submitted electronically due to a communication error.500
order-el-errorAn error occurred500
order-abn-requiredABN form must be printed422

* 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

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:

PropertyCardinalityTypeDescription
display1..1StringDisplay string
definition0..1StringDetailed description
property.aoe0..1BooleanAOEs required
property.specimen-type0..1StringSpecimen Type
property.specimen-container0..1StringSpecimen Container
property.specimen-collection0..1StringSpecimen Collection
property.specimen-storage0..1StringSpecimen Storage
property.linked-compendium-required0..*CodingTest that must be included to the same order.
property.linked-compendium-recommended0..*CodingTest that should be included to the same order.
property.cpt0..*CodingRelated CPT codes
property.group0..1CodingRadiology Group
property.homeDraw0..1BooleanIs procedure available for home draw
property.procedure-request0..*CodingIndividual 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:

AttributeCardinalityTypeDescription
filter1..1stringText filter that is applied to restrict the codes that are returned.
procedure0..*tokenReturn only those compendium items that are associated with the specified CPT codes.
offset0..1integerPaging support - where to start if a subset is queried.
count0..1integerPaging support - how many codes should be provided in a partial page view.
includeParameters0..1booleanIndicates 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
AttributeCardinalityTypeDescription
filter1..1stringText filter that is applied to restrict the ValueSet codes that are returned.
organization1..*referenceOne or more organization identifier where to search for compendium items.
home-draw0..1tokentrue/false
If true - return only tests available for home draw.
procedure0..*tokenReturn only those compendium items that are associated with the specified CPT codes.
offset0..1numberPaging support - where to start if a subset is queried.
count0..1numberPaging support - how many codes should be provided in a partial page
includeParameters0..1booleanIndicates 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

CodeDisplayDefinition
dateDateQuestion with a date answer (valueDate)
stringStringQuestion with a short (few words to short sentence) free-text entry answer (valueString)
choiceChoiceQuestion 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-choiceOpen ChoiceAnswer 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 RequestMethodDescription
Questionnaire?[parameter={value}]GETLookup for AOE questions/answers for the given compendium item.

Parameters:

ParameterCardinalityTypeDescription
code1..1tokenThe compendium item code.
procedure0..*tokenReturn 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 RequestMethodAction
/Questionnaire/{ID}/$proceduresPOSTGet 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.

ParametersCardinalityTypeDescription
local1..1tokenAlways true to use the local patient demographic.
subject1..1referenceReference 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:

NameTypeDescription
typetokenA code for the type of organization.
namestringA portion of the organization's name or alias.
ordering-enabledtokenA ordering-enabled property. Use to get only organizations that support ordering.
_countnumberA 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

CodeDisplayDefinition
HUSCSspecimen collection siteA 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.
OUTLABoutpatient laboratoryA 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.
HRADradiology unitA 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:

NameTypeDescription
typetokenCode for the type of location.
namestringPortion of the location's name or alias.
address-statestringState specified in address.
address-citystringCity specified in address.
address-postalcodestringPostal code specified in address.
ordering-enabledtokenOrdering-enabled property. Use to get only locations that support ordering.
neartokenCoordinates expressed as [latitude]:[longitude] (using the WGS84 datum, see notes) to find locations near to. If specified then 'near-distance' parameter is required.
near-distancequantityDistance in miles to limit the 'near' search to locations within a specific distance. When specified 'near' parameter must be included as well.
test-codetokenTest or study order code that the requested locations should support.
organizationreferenceSearches for locations that are managed by the specified organization.
_countnumberPositive 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:

NameTypeDescription
requesterreferenceThe physician who is authorizing the order.
The Practitioner resource logical identifier.
requester.identifiertokenThe physician who is authorizing the order.
The Practitioner's NPI identifier.

Response contains the following properties:

PropertyTypeDescription
orderingEnabledBooleanTrue if orders can be submitted for the given organization.
doctorAccountRequiredBooleanTrue if physician's account is a required parameter when placing an order.
practiceAccountRequiredBooleanTrue if clinic's account is a required parameter when placing an order.
compendiumUrlIDThe ID of the value set that contains compendium for the given laboratory. If applicable.
electronicOrderingBooleanTrue 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:

PropertyTypeDescription
abnRequiredBoolean
urlStringLink 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
        }
    ]
}

Updated 5 months ago