Referral API

The Referral API allows providers to submit referral requests and receive responses electronically.

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 send referral requests and receive responses. This API is built upon FHIR STU3 and uses common FHIR resources and operations.

The following FHIR resources are involved in the referral workflow process:

ReferralRequest
Practitioner
Patient
DirectMessage

ReferralRequest

Health Gorilla uses ReferralRequest resource to describe an individual referral. A referral can have only one recipient, this may be a practitioner or an organization and contain links to supported documents.

Health Gorilla Referral profile required to be set.

https://healthgorilla.com/fhir/StructureDefinition/hg-referral

Below you can find a list of attributes that are used to submit a referral request.

Name	Card.	Type	Description & Constraints
status	1..1	code	active
intent	1..1	code	order
subject	1..1	Reference(Patient)
requester	1..1	BackboneElement	Who is requesting service.
requester.agent	0..1	Reference(Practitioner)	HealthGorilla user. Default: current logged user.
requester.onBehalfOf	0..1	Reference(Organization)	HealthGorilla practice or practice location. Default: the current practice. Required if the requester's practice has several locations. In this case the certain practice location must be specified.
recipient	0..1	Reference(Practitioner or Organization)	Receiver of referral. This may be a physician that does not have HealthGorrilla account. Or this may be a practice or practice location. Otherwise you should use HealthGorilla extension to specify the recipient.
extension: referralrequest-recipient	0..1	Extension	Receiver of referral. Extension: https://www.healthgorilla.com/fhir/StructureDefinition/referralrequest-recipient This may be a physician who does not have HealthGorrilla account. Or this may be physician that has HealthGorilla account. In this case the link to practice location that should receive the request must be specified.
reasonCode	0..*	CodeableConcept	Reason for referral. ICD10 diagnoses.
supportingInfo	0..*	Reference(DiagnosticReport \| DocumentReference \| Binary)	Additional information to support referral.
extension: referralrequest-deliveryOptions	0..1	Extension	Delivery options. Extension: https://www.healthgorilla.com/fhir/StructureDefinition/referralrequest-deliveryOptions Allows to specify the delivery methods.

Recipient

Practitioner that has HealthGorilla account

Extension: https://www.healthgorilla.com/fhir/StructureDefinition/referralrequest-recipient

Name
agent	Reference (Practitioner)	Link to the practitioner who has HealthGorilla account.
location	Reference (Location)	Link to the practice location. Optional for practice with a single location.
onBehalfOf	Reference (Organization)	Link to the practice.

{
  ...
   "extension":[
      {
         "url":"https://www.healthgorilla.com/fhir/StructureDefinition/referralrequest-recipient",
         "extension":[
            {
               "url":"agent",
               "valueReference":{
                  "reference":"Practitioner/974e04546c424b6f687bf587",
                  "display":"Dr. Gregory Hosue, PhD"
               }
            },
            {
               "url":"location",
               "valueReference":{
                  "reference":"Location/tl-974e04549053f5b7257b292c-03db4352ee0190ad5e9e6748"
               }
            },
            {
               "url":"onBehalfOf",
               "valueReference":{
                  "reference":"Organization/t-974e04549053f5b7257b292c"
               }
            }
         ]
      }
   ],
  ...
}

Practitioner that does not have account in HealthGorilla

{
  "resourceType": "ReferralRequest",
  "meta": {
    "profile": [
     "https://healthgorilla.com/fhir/StructureDefinition/hg-referral"
    ]
  },
  ... 
  "recipient": [
     {
        "reference": "Practitioner/npi-bfb369547657c1ed968786a2"
     }
  ],
  ...
}

{
  "resourceType": "ReferralRequest",
  "meta": {
    "profile": [
     "https://healthgorilla.com/fhir/StructureDefinition/hg-referral"
    ]
  },
  ...
   "recipient":[
      {
         "identifier": [
               {
                  "system":"http://hl7.org/fhir/sid/us-npi",
                  "value":"1548265317"
               }
            ]
      }
   ],
  ...
}

Practice

{
  "resourceType": "ReferralRequest",
  "meta": {
    "profile": [
     "https://healthgorilla.com/fhir/StructureDefinition/hg-referral"
    ]
  },
  ... 
  "recipient": [
     {
        "reference": "Organization/tl-bfb369547657c1ed968786a2-03db4352ee0190ad5e9e6748"
     }
  ],
  ...
}

{
  ...
   "extension":[
      {
         "url":"https://www.healthgorilla.com/fhir/StructureDefinition/referralrequest-recipient",
         "extension":[
            {
               "url":"location",
               "valueReference":{
                  "reference":"Location/tl-974e04549053f5b7257b292c-03db4352ee0190ad5e9e6748"
               }
            },
            {
               "url":"onBehalfOf",
               "valueReference":{
                  "reference":"Organization/t-974e04549053f5b7257b292c"
               }
            }
         ]
      }
   ],
  ...
}

Supported Info

You can attach links to DiagnosticReport, DocumentReference or Binary resources.

Example:

DiagnosticReport and Binary (File) attachments.

...
"supportingInfo" : [
                	{
                		"reference" : "http://api.healthgorilla.com/fhir/Binary/ext-7f8ec35e4af006f3ede6db6d"
                	},
                	{
                		"reference" : "DiagnosticReport/d5da43523f4ad880ba1dfb64"
                	}
                ]
...

📘
Binary Attachment
If you want to attach a binary resource (File) to a referral, then you should upload it before creating a referral payload.

Delivery Options

You can specify delivery options for the referral.

Extension: https://www.healthgorilla.com/fhir/StructureDefinition/referralrequest-recipient

Existing HealthGorilla practitioner

Available options:

Notify by SMS

{
   ...
   "extension":[
      {
         "url":"https://www.healthgorilla.com/fhir/StructureDefinition/referralrequest-deliveryOptions",
         "extension":[
            {
               "url":"method",
               "valueContactPoint":{
                  "system":"sms",
                  "value":"000 000 0000"
               }
            }
         ]
      },
      ...
   ],
   ...
}

Practitioner that does not have HealthGorilla account

Available options:

Notify by SMS
Notify by fax
Notify by email

To send a referral to a practitioner who does not have a HealthGorilla account, you must provide a fax or email. SMS notification is optional.

{
   ...
   "extension":[
      {
         "url":"https://www.healthgorilla.com/fhir/StructureDefinition/referralrequest-deliveryOptions",
         "extension":[
            {
               "url":"method",
               "valueContactPoint":{
                  "system":"fax",
                  "value":"000 000 1111"
               }
            },
            {
               "url":"method",
               "valueContactPoint":{
                  "system":"sms",
                  "value":"000 000 0000"
               }
            }
         ]
      },
      ...
   ],
   ...
}

Submit the referral

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

You should send HTTP POST request to ReferralRequest endpoint. Once request is submitted, then HTTP 201 will be returned and newly created resource location included into the response header.

Example:

POST /fhir/ReferralRequest HTTP/1.1 
Host: api.healthgorilla.com 
Authorization: Bearer sldfksgkkG78dsdff787
HG-Idempotency-Key: 15e72676-48c3-11ea-b77f-2e728ce88125
X-Request-Id: 09189c18-48c8-11ea-b77f-2e728ce88125
Content-Type: application/json 
[...omitted for brevity...]

HTTP/1.1 201 Created
Server: Apache-Coyote/1.1
X-Hg-Request-Id: 15e2305e94845d4d2f3f7796
X-Request-Id: 15e2305e94845d4d2f3f7796
X-Correlation-Id: 09189c18-48c8-11ea-b77f-2e728ce88125
Content-Length: 0
Date: Tue, 6 Feb 2020 14:33:16 GMT
Location: https://api.healthgorilla.com/fhir/ReferralRequest/03db4352ee0190ad5e9e6748

Errors

Failed to send referral to practitioner due to missed fax/email.

{
    "resourceType": "OperationOutcome",
    "issue": [
        {
            "severity": "fatal",
            "code": "invalid",
            "details": {
                "text": "Missed contact info (fax/email) for not-activated recipient doctor's account."
            }
        }
    ]
}

Supplied practitioner is unknown.

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

Referral Response

When referral get a reply then DirectMessage is sent to the requester.

You can find link to the reply in the referral.

Extension: https://www.healthgorilla.com/fhir/StructureDefinition/referralrequest-reply

{
    "resourceType": "ReferralRequest",
    "id": "d276c65e491a5abaa81ac022",
    "meta": {
        "versionId": "1590148972184",
        "lastUpdated": "2020-05-22T15:02:52.184+03:00",
        "profile": [
            "https://healthgorilla.com/fhir/StructureDefinition/hg-referral"
        ]
    },
    "extension": [
        {
            "url": "https://www.healthgorilla.com/fhir/StructureDefinition/referralrequest-reply",
            "valueReference": {
                "identifier": {
                    "system": "https://www.healthgorilla.com",
                    "value": "6cbfc75ed44d23ae13183334"
                }
            }
        }
    ],
    "status": "completed",
    ...
}

Then you can read the reply if the logged user has access to this private message.

https://api.healthgorilla.com/fhir/DirectMessage
?identifier=https://www.healthgorilla.com|6cbfc75ed44d23ae13183334

{
    "resourceType": "Bundle",
    "id": "2190c049-3caa-4213-94ed-025eb4a3de1a",
    "meta": {
        "lastUpdated": "2020-05-22T16:19:18.669+03:00"
    },
    "type": "searchset",
    "total": 1,
    "link": [
        {
            "relation": "self",
            "url": "http://localhost:8080/fhir/DirectMessage?_format=json&identifier=https%3A%2F%2Fwww.healthgorilla.com%7C49d1c75e4a4676a3d9595800"
        }
    ],
    "entry": [
        {
            "fullUrl": "http://localhost:8080/fhir/DirectMessage/49d1c75e7bd856d8ea6edf42",
            "resource": {
                "resourceType": "DirectMessage",
                "id": "49d1c75e7bd856d8ea6edf42",
                "meta": {
                    "lastUpdated": "2020-05-22T16:19:05.995+03:00",
                    "profile": [
                        "http://healthgorilla.com/fhir/Profile/DirectMessage"
                    ]
                },
                "identifier": [
                    {
                        "system": "https://www.healthgorilla.com",
                        "value": "49d1c75e9a16cee3414ce894"
                    }
                ],
                "sentOn": "2020-05-22T16:19:05+03:00",
                "sender": {
                    "practitioner": {
                        "reference": "Practitioner/d5da4352bb6290302c4cc8d7",
                        "display": "Gregory Tomas House, M.D. (Dr. House Practice)"
                    },
                    "organization": {
                        "reference": "Organization/t-d5da43523ded70612e79f479",
                        "display": "Dr. House Practice"
                    }
                },
                "recipient": [
                    {
                        "practitioner": {
                            "reference": "Practitioner/ceda4352e8f6405dd2e42f09",
                            "display": "John Doe, M.D."
                        },
                        "organization": {
                            "reference": "Organization/t-d5da4352af2201ace56ca725",
                            "display": "Secret Health Hospital"
                        }
                    }
                ],
                "title": "Reply on Referral",
                "content": {
                    "text": "Dear Dr. John Doe,\n\nThank you for referring Bart Simpson to my care.\nHere are the results of my examination:\n\nSincerely,\nGregory Tomas House"
                },
                "attachment": [
                    {
                        "reference": {
                            "reference": "ReferralRequest/19d1c75e7d682381d8e1ff10"
                        }
                    }
                ],
                "direction": {
                    "coding": [
                        {
                            "system": "https://www.healthgorilla.com/fhir/message-direction",
                            "code": "IN",
                            "display": "Incoming"
                        }
                    ],
                    "text": "INCOMING"
                },
                "subject": {
                    "reference": "Patient/03db43522cc01432572e0a53",
                    "display": "Bart Simpson"
                }
            }
        }
    ]
}

Subscribe to receive notification of replies

You can add a subscription to receive incoming messages when a recipient reply to a referral request.

{
    "resourceType": "Subscription",
    "status": "requested",
    "end": "2022-01-01T00:00:00Z",
    "reason": "Receive referral responses",
    "criteria": "DirectMessage?direction=IN",
    "channel": {
        "type": "rest-hook",
        "endpoint": "https://mysite.com/referral/responsecallback",
        "payload": "application/fhir+json",
        "header": [
            "Authorization: Bearer accc5e72ac51fc53c6881b9a5d122765"
        ]
    }
}

Sample

{
   "resourceType":"ReferralRequest",
   "meta":{
      "profile":[
         "https://healthgorilla.com/fhir/StructureDefinition/hg-referral"
      ]
   },
   "extension":[
      {
         "url":"https://www.healthgorilla.com/fhir/StructureDefinition/referralrequest-deliveryOptions",
         "extension":[
            {
               "url":"method",
               "valueContactPoint":{
                  "system":"fax",
                  "value":"000 000 0000"
               }
            }
         ]
      }
   ],
   "status":"active",
   "intent":"order",
   "subject":{
      "reference":"Patient/03db4352ee0190ad5e9e6748",
      "display":"Homer Simpson"
   },
   "requester": {
                    "agent": {
                        "reference": "Practitioner/ceda4352e8f6405dd2e42f09",
                        "display": "Dr House"
                    },
                    "onBehalfOf": {
                        "reference": "Organization/tl-d5da4352af2201ace56ca725-931490546b89416ed64ff6a4"
                    }
   },
   "recipient":[
      {
         "identifier": [
               {
                  "system":"http://hl7.org/fhir/sid/us-npi",
                  "value":"1548265317"
               }
            ]
      }
   ],
   "note":[
      {
         "text":"Dear John Doe,\n\nI would like to refer my patient, Homer Simpson, to your office for a consultation. I have included this patient’s relevant information below for your attention.\n\nPlease let myself or my office staff know if you require any further information regarding Homer Simpson.\nPlease find the appropriate test results and records for this patient (if any) below.\n\nI would greatly appreciate if you could respond with your examination results.\nSincerely,\nJohn Doe"
      }
   ],
   "reasonCode": [
        {
            "coding": [
                {
                    "system": "http://hl7.org/fhir/sid/icd-10",
                    "code": "M71.022",
                    "display": "Abscess of bursa, left elbow"
                }
            ],
            "text": "Abscess of bursa, left elbow"
        },
        {
            "coding": [
                {
                    "system": "http://hl7.org/fhir/sid/icd-10",
                    "code": "M70.10",
                    "display": "Bursitis, unspecified hand"
                }
            ],
            "text": "Bursitis, unspecified hand"
        }
   ],
   "supportingInfo":[
      {
         "reference":"DiagnosticReport/d5da43523f4ad880ba1dfb64"
      }
   ]
}

Resources

ReferralRequest

Recipient

Practitioner that has HealthGorilla account

Practitioner that does not have account in HealthGorilla

Practice

Supported Info

📘Binary Attachment

Delivery Options

Existing HealthGorilla practitioner

Practitioner that does not have HealthGorilla account

Submit the referral

Errors

Failed to send referral to practitioner due to missed fax/email.

Supplied practitioner is unknown.

Referral Response

Subscribe to receive notification of replies

Sample

📘
Binary Attachment