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 - 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
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
}
]
}
Updated 5 months ago