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:

  <th>
    Comment
  </th>
</tr>

  <td>

  </td>
</tr>

<tr>
  <td>
    sentOn
  </td>

  <td>

  </td>
</tr>

<tr>
  <td>
    sender
  </td>

  <td>
    The sender of the message
  </td>
</tr>

<tr>
  <td>
    to
  </td>

  <td>
    Array of "To" recipient Direct addresses
  </td>
</tr>

<tr>
  <td>
    cc
  </td>

  <td>
    Array of "CC" recipient Direct addresses
  </td>
</tr>

<tr>
  <td>
    bcc
  </td>

  <td>
    Array of "BCC" recipient Direct addresses
  </td>
</tr>

<tr>
  <td>
    subject
  </td>

  <td>
    Subject string
  </td>
</tr>

<tr>
  <td>
    htmlBody
  </td>

  <td>
    HTML body string
  </td>
</tr>

<tr>
  <td>
    textBody
  </td>

  <td>
    Plain text body string
  </td>
</tr>

<tr>
  <td>
    attachment
  </td>

  <td>
    Array of attachments
  </td>
</tr>

<tr>
  <td>
    direction
  </td>

  <td>
    Message in/out direction
  </td>
</tr>

Name
identifier

FHIR Operations

The following operations are currently supported:

1. Read

  <th>
    Method
  </th>

  <th>
    Action
  </th>
</tr>

  <td>
    GET
  </td>

  <td>
    Get Direct message by its ID
  </td>
</tr>

HTTP Request
/DirectMessage/\{ID}?\_format=json

2. Search

  <th>
    Method
  </th>

  <th>
    Action
  </th>
</tr>

  <td>
    GET
  </td>

  <td>
    Returns DirectMessage resources matching the filter specified as parameters
  </td>
</tr>

HTTP Request
/DirectMessage?[parameter=\{value}][parameter={value}]

Parameters:

  <th>
    Type
  </th>

  <th>
    Description
  </th>
</tr>

  <td>
    Token
  </td>

  <td>
    OUT for outgoing messages and IN for incoming
  </td>
</tr>

<tr>
  <td>
    identifier
  </td>

  <td>
    Token
  </td>

  <td>
    DirectMessage's identifier
  </td>
</tr>

<tr>
  <td>
    * lastUpdated
  </td>

  <td>
    Date
  </td>

  <td>
    Return DirectMessage resources modified after the specified date. For ex.: gt2019-09-05
  </td>
</tr>

Key
direction

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

  <th>
    Method
  </th>

  <th>
    Action
  </th>
</tr>

  <td>
    POST
  </td>

  <td>
    Creates a new DirectMessage resource with OUT direction and sends corresponding Direct message to recipients
  </td>
</tr>

HTTP Request
/DirectMessage

Example

Send a Direct message example with description of the payload:

  <th>
    Notes
  </th>

  <th>
    Example
  </th>
</tr>

  <td>
    Originating organization identifier is subject to access rights authorization
  </td>

  <td>
    d5da4352af2201ace56ca725
  </td>
</tr>

<tr>
  <td>
    Organization location with identifier
  </td>

  <td>
    Your organization's location IDs are sent to you during the API access setup
  </td>

  <td>
    931490546b89416ed64ff6a4
  </td>
</tr>

<tr>
  <td>
    Sender Direct address
  </td>

  <td>
    Must match the Direct address configured for your organization
  </td>

  <td>
    [[email protected]](mailto:[email protected])
  </td>
</tr>

<tr>
  <td>
    Recipient Direct address
  </td>

  <td>
    Direct address of the recipient
  </td>

  <td>
    [[email protected]](mailto:[email protected])
  </td>
</tr>

<tr>
  <td>
    Subject
  </td>

  <td>
    Subject line of the Direct Message
  </td>

  <td>
    A test message with an attachment via HG FHIR API
  </td>
</tr>

<tr>
  <td>
    htmlBody
  </td>

  <td>
    Body of the Direct message
  </td>

  <td>
    <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>
  </td>
</tr>

<tr>
  <td>
    Attachment
  </td>

  <td>
    The file with DocumentReference identifier
  </td>

  <td>
    Message has attachment file "example.pdf" with the DocumentReference identifier "bfaf6a5b9e46e25e949e211b"
  </td>
</tr>

Field
Originating organization identifier

{
    "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.

  <th>
    Method
  </th>

  <th>
    Action
  </th>
</tr>

  <td>
    GET
  </td>

  <td>
    Search for providers in the Direct HPD in FHIR STU3
  </td>
</tr>

<tr>
  <td>
    /fhir/R4/DirectMessage/$searchProviders
  </td>

  <td>
    GET
  </td>

  <td>
    Search for providers in the Direct HPD in FHIR R4
  </td>
</tr>

HTTP Request
/fhir/DirectMessage2/$searchProviders

Parameters

  <th>
    Type
  </th>

  <th>
    Description
  </th>
</tr>

  <td>
    string
  </td>

  <td>
    First name
  </td>
</tr>

<tr>
  <td>
    lastName
  </td>

  <td>
    string
  </td>

  <td>
    Last Name
  </td>
</tr>

<tr>
  <td>
    npi
  </td>

  <td>
    number
  </td>

  <td>
    Provider NPI
  </td>
</tr>

<tr>
  <td>
    organizationName
  </td>

  <td>
    string
  </td>

  <td>
    Organization name
  </td>
</tr>

<tr>
  <td>
    organizationNpi
  </td>

  <td>
    number
  </td>

  <td>
    Organization NPI number
  </td>
</tr>

<tr>
  <td>
    organizationSpecialty
  </td>

  <td>
    string
  </td>

  <td>
    Organization speciality
  </td>
</tr>

<tr>
  <td>
    phone
  </td>

  <td>
    string
  </td>

  <td>

  </td>
</tr>

<tr>
  <td>
    fax
  </td>

  <td>
    string
  </td>

  <td>

  </td>
</tr>

<tr>
  <td>
    street
  </td>

  <td>
    string
  </td>

  <td>

  </td>
</tr>

<tr>
  <td>
    city
  </td>

  <td>
    string
  </td>

  <td>

  </td>
</tr>

<tr>
  <td>
    state
  </td>

  <td>
    string
  </td>

  <td>

  </td>
</tr>

<tr>
  <td>
    zip
  </td>

  <td>
    number
  </td>

  <td>

  </td>
</tr>

<tr>
  <td>
    * offset
  </td>

  <td>
    number
  </td>

  <td>

  </td>
</tr>

<tr>
  <td>
    * count
  </td>

  <td>
    number
  </td>

  <td>

  </td>
</tr>

Name
firstName

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