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:

Name	Comment
identifier
sentOn
sender	The sender of the message
to	Array of "To" recipient Direct addresses
cc	Array of "CC" recipient Direct addresses
bcc	Array of "BCC" recipient Direct addresses
subject	Subject string
htmlBody	HTML body string
textBody	Plain text body string
attachment	Array of attachments
direction	Message in/out direction

FHIR Operations

The following operations are currently supported:

1. Read

HTTP Request	Method	Action
/DirectMessage/{ID}?_format=json	GET	Get Direct message by its ID

2. Search

HTTP Request	Method	Action
/DirectMessage?[parameter={value}]	GET	Returns DirectMessage resources matching the filter specified as parameters

Parameters:

Key	Type	Description
direction	Token	OUT for outgoing messages and IN for incoming
identifier	Token	DirectMessage's identifier
_lastUpdated	Date	Return 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 Request	Method	Action
/DirectMessage	POST	Creates 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:

Field	Notes	Example
Originating organization identifier	Originating organization identifier is subject to access rights authorization	d5da4352af2201ace56ca725
Organization location with identifier	Your organization's location IDs are sent to you during the API access setup	931490546b89416ed64ff6a4
Sender Direct address	Must match the Direct address configured for your organization	[email protected]
Recipient Direct address	Direct address of the recipient	[email protected]
Subject	Subject line of the Direct Message	A test message with an attachment via HG FHIR API
htmlBody	Body 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.
Attachment	The file with DocumentReference identifier	Message 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 Request	Method	Action
/fhir/DirectMessage2/$searchProviders	GET	Search for providers in the Direct HPD in FHIR STU3
/fhir/R4/DirectMessage/$searchProviders	GET	Search for providers in the Direct HPD in FHIR R4

Parameters

Name	Type	Description
firstName	string	First name
lastName	string	Last Name
npi	number	Provider NPI
organizationName	string	Organization name
organizationNpi	number	Organization NPI number
organizationSpecialty	string	Organization speciality
phone	string
fax	string
street	string
city	string
state	string
zip	number
_offset	number
_count	number

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

Direct Message

📘DirectMessage vs InstantMessage

FHIR Operations

1. Read

2. Search

2.1 Retrieve all incoming Direct messages received starting from 09/05/2019

2.2 Retrieve a DirectMessage resource with identifier "35f3d35d12aa8d93dd9953c0"

3. Send

Direct Healthcare Provider Directory

📘
DirectMessage vs InstantMessage