Direct Messaging

Direct Message

If your organization's account is set up with Direct Secure Messaging (see https://directtrust.org/what-we-do/direct-secure-messaging) support enabled in Health Gorilla then you can send and receive Direct Messages using DirectMessage resource. A message is a composite object that can contain a sender and recipients, a subject, a message body and attachments. Users may send messages to (and receive from) any Direct address.

A DirectMessage can contain arbitrary files as well as DiagnosticReport, RequestGroup, DocumentReference and ReferralRequest resources as attachments.

πŸ“˜

DirectMessage vs InstantMessage

The FHIR resource for Health Gorilla's internal message system was previously named DirectMessage and was renamed to InstantMessage. See documentation for .

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

The following attributes are supported:

NameComment
identifier
sentOn
senderThe sender of the message
toArray of "To" recipient Direct addresses
ccArray of "CC" recipient Direct addresses
bccArray of "BCC" recipient Direct addresses
subjectSubject string
htmlBodyHTML body string
textBodyPlain text body string
attachmentArray of attachments
directionMessage in/out direction

FHIR Operations

The following operations are currently supported:

1. Read

HTTP RequestMethodAction
/DirectMessage/{ID}?_format=jsonGETGet Direct message by its ID

2. Search

HTTP RequestMethodAction
/DirectMessage?[parameter={value}]GETReturns DirectMessage resources matching the filter specified as parameters

Parameters:

KeyTypeDescription
directionTokenOUT for outgoing messages and IN for incoming
identifierTokenDirectMessage's identifier
_lastUpdatedDateReturn DirectMessage resources modified after the specified date. For ex.: gt2019-09-05

Examples:

2.1 Retrieve all incoming Direct messages received starting from 09/05/2019
https://api.healthgorilla.com/fhir/DirectMessage?
direction=IN
&_lastUpdated=gt2019-09-05
&_format=json
2.2 Retrieve a DirectMessage resource with identifier "35f3d35d12aa8d93dd9953c0"
https://api.healthgorilla.com/fhir/DirectMessage?
identifier=https://www.healthgorilla.com|35f3d35d12aa8d93dd9953c0
&_format=json

3. Send

HTTP RequestMethodAction
/DirectMessagePOSTCreates a new DirectMessage resource with OUT direction and sends corresponding Direct message to recipients

Example

Send a Direct message example with description of the payload:

FieldNotesExample
Originating organization identifierOriginating organization identifier is subject to access rights authorizationd5da4352af2201ace56ca725
Organization location with identifierYour organization's location IDs are sent to you during the API access setup931490546b89416ed64ff6a4
Sender Direct addressMust match the Direct address configured for your organization[email protected]
Recipient Direct addressDirect address of the recipient[email protected]
SubjectSubject line of the Direct MessageA test message with an attachment via HG FHIR API
htmlBodyBody of the Direct message

Hi,

It's a test message with an attachment and HTML mark-up. It's been sent via HG FHIR API.

AttachmentThe file with DocumentReference identifierMessage has attachment file "example.pdf" with the DocumentReference identifier "bfaf6a5b9e46e25e949e211b"
{
    "resourceType": "DirectMessage",
    "sender": {
        "organization": {
            "reference": "Organization/tl-d5da4352af2201ace56ca725-931490546b89416ed64ff6a4",
            "display": "Dr. Doe Practice"
        },
        "directAddress": "[email protected]"
    },
    "to": ["[email protected]"],
    "subject": "A test message with an attachment via HG FHIR API",
    "htmlBody": "<p>Hi,</p> <p>It's a test message with an attachment and HTML mark-up. It's been sent via <i>HG FHIR API</i>.</p>",
    "attachment": [
        {
            "file": {
                "contentType": "application/pdf",
                "data": "<BASE64 encoded content of example.pdf>",
                "title": "example.pdf"
            }
        },
        {
            "reference": {
                "reference": "DocumentReference/bfaf6a5b9e46e25e949e211b"
            }
        }
    ]
}

Direct Healthcare Provider Directory

The Direct Healthcare Provider Directory (HPD) is an address book of Direct addresses that providers and organizations have opted in to sharing their address.

HTTP RequestMethodAction
/fhir/DirectMessage2/$searchProvidersGETSearch for providers in the Direct HPD in FHIR STU3
/fhir/R4/DirectMessage/$searchProvidersGETSearch for providers in the Direct HPD in FHIR R4

Parameters

NameTypeDescription
firstNamestringFirst name
lastNamestringLast Name
npinumberProvider NPI
organizationNamestringOrganization name
organizationNpinumberOrganization NPI number
organizationSpecialtystringOrganization speciality
phonestring
faxstring
streetstring
citystring
statestring
zipnumber
_offsetnumber
_countnumber
https://api.healthgorilla.com/fhir/DirectMessage/$searchProviders?firstName=Julia&_count=1&_offset=0&lastName=ABRAHAM&organization=Blue Ridge Community Health Service&city=Hendersonville&fax=828-696-2350&npi=1417417403&phone=828-692-4289&state=NC&zip=28792&street=2579 Chimney Rock Road
https://api.healthgorilla.com/fhir/R4/DirectMessage/$searchProviders?firstName=Julia&_count=1&_offset=0&lastName=ABRAHAM&organization=Blue Ridge Community Health Service&city=Hendersonville&fax=828-696-2350&npi=1417417403&phone=828-692-4289&state=NC&zip=28792&street=2579 Chimney Rock Road

Sample response:

{
    "resourceType": "Bundle",
    "meta": {
        "profile": [
            "https://healthgorilla.com/fhir/StructureDefinition/hg-stateless-bundle"
        ]
    },
    "type": "searchset",
    "total": 1,
    "link": [
        {
            "relation": "self",
            "url": "https://api.healthgorilla.com/fhir/R4/DirectMessage/$searchProviders?firstName=Julia&_count=1&_offset=0&lastName=ABRAHAM&organization=Blue%20Ridge%20Community%20Health%20Service&city=Hendersonville&fax=828-696-2350&npi=1417417403&phone=828-692-4289&state=NC&zip=28792&street=2579%20Chimney%20Rock%20Road"
        }
    ],
    "entry": [
        {
            "resource": {
                "resourceType": "PractitionerRole",
                "contained": [
                    {
                        "resourceType": "Practitioner",
                        "id": "1",
                        "name": [
                            {
                                "text": "JULIA ABRAHAM",
                                "family": "ABRAHAM",
                                "given": [
                                    "JULIA"
                                ]
                            }
                        ],
                        "address": [
                            {
                                "text": "2579 Chimney Rock Road, 340B00130800BR, Hendersonville, NC 28792",
                                "line": [
                                    "2579 Chimney Rock Road",
                                    "340B00130800BR"
                                ],
                                "city": "Hendersonville",
                                "state": "NC",
                                "postalCode": "28792-9181"
                            }
                        ]
                    },
                    {
                        "resourceType": "Organization",
                        "id": "2",
                        "name": "Blue Ridge Community Health Service"
                    }
                ],
                "identifier": [
                    {
                        "type": {
                            "coding": [
                                {
                                    "system": "http://terminology.hl7.org/CodeSystem/v2-0203",
                                    "code": "PRN",
                                    "display": "Passport number"
                                }
                            ],
                            "text": "Passport number"
                        },
                        "system": "http://hl7.org/fhir/sid/us-npi",
                        "value": "1417417403"
                    }
                ],
                "practitioner": {
                    "reference": "#1"
                },
                "organization": {
                    "reference": "#2"
                },
                "telecom": [
                    {
                        "system": "fax",
                        "value": "828-696-2350",
                        "use": "work"
                    },
                    {
                        "system": "phone",
                        "value": "828-692-4289",
                        "use": "work"
                    },
                    {
                        "system": "email",
                        "value": "[email protected]",
                        "use": "work"
                    }
                ]
            }
        }
    ]
}