Skip to main content
This functionality is currently under construction. Please reach out to support if you’d like to use it.
Message Delivery lets a practitioner exchange patient clinical data, referrals, and other communications directly with another practitioner on the network in a secure manner.

​
How it works

Metriport supports two methods of Message Delivery - Direct Message and Cross-Community Document Reliable Interchange (aka XCDR). To learn how to activate either one for your account, please reach out to our support. When you send a message, you are required to set the destination for the recipient, and Metriport determines which method to use for the exchange. All messages are stored as FHIR Communication resources and merged into the patient’s Consolidated Data, like everything else.

​
Outbound

The message must be in reference to a specific patient. Create the patient that you intend to exchange information about in Metriport using the Create Patient endpoint, if they don’t exist already. The message must contain a subject line, and at least one of body or attachments. If you’re attaching documents, upload them first using Upload Document and pass the returned document IDs in attachments. Otherwise, you can use the List Documents endpoint with a source filter for Metriport to pull all document references for the document you have uploaded for the patient. To send a message to another practitioner, you will need:
  1. The patientId from the Patient Create step mentioned above.
  2. The destination for the recipient - refer to the Finding a destination section below.
  3. Optionally, the NPI of the intended recipient in intendedRecipientNpi. This is especially useful when the destination points to an organization but the message is intended for a specific practitioner.
For example, Send Message with an example body: 
{
  "destination": "intake@cardio.direct.partner.com",
  "subject": "Referral - cardiology",
  "body": "Please review the attached referral for cardiology consultation.",
  "attachments": ["00000000-0000-0000-0000-000000000000"],
  "intendedRecipientNpi": ["1234567890"]
}
The endpoint returns immediately with Communication resource with the in-progress status while Metriport delivers the message. When the recipient acknowledges receipt, or if delivery fails, Metriport sends a message.status webhook to your configured URL. You can also check status by polling Get Message Status, though we recommend using webhooks instead.

​
Inbound

When another practitioner sends a message to your organization, Metriport receives it and emits a message.received webhook. The payload includes a presigned URL to download the full message content and attachments. Inbound messages are also available via List Messages. Note that some inbound messages might not be tied to a specific patient. However, if Metriport is able to match the message to a patient, the data from the message will also be included in the patient’s Consolidated Data.

​
What you need to do

To use Message Delivery, your application needs to:
  1. Configure a webhook URL so Metriport can notify you when messages are received or when outbound delivery completes. See Implementing Webhooks.
  2. Handle message.received and message.status webhooks - see Message Events for payload details.
  3. Upload documents before sending, if your message includes attachments - see Upload Document.

​
The full flow

​
Sending a message

  1. Create Patient, if they don’t exist already.
  2. Optionally upload documents with Upload Document or FHIR data with Create Patient’s Consolidated Data and note the document IDs.
  3. Find the recipient’s destination with Search Destinations.
  4. Call Send Message.
  5. Await the message.status webhook, or poll Get Message Status.

​
Receiving a message

  1. Await the message.received webhook.
  2. Download the message from the presigned URL in the payload.
  3. Optionally list historical messages with List Messages.

​
Finding a destination

Use Search Destinations to find where to send a message. Search by provider name and location, organization name, or the NPI. The response is a list of potential matches containing names and locations to help you disambiguate between them. Pick the one that matches best and use its destination property to Send Message. Results are ordered by Metriport’s recommended preference for your account. If you already know the recipient’s destination, you can verify it with the same endpoint, or skip search and pass it directly on send.
The destination is an OID or a Direct email