> ## Documentation Index
> Fetch the complete documentation index at: https://docs.metriport.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Message Delivery

> Exchange clinical data directly with another practitioner.

<Warning>
  This functionality is currently under construction. Please
  reach out to support if you'd like to use it.
</Warning>

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](/medical-api/fhir/resources/communication) resources and
merged into the patient's [Consolidated Data](/medical-api/api-reference/fhir/consolidated-data-query-post),
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](/medical-api/api-reference/patient/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](/medical-api/api-reference/document/post-upload-url) and pass the
returned document IDs in `attachments`. Otherwise, you can use the [List Documents](/medical-api/api-reference/document/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](#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](/medical-api/api-reference/message/send-message) with an example body:

```json theme={null}
{
  "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`](/medical-api/handling-data/webhooks-with-nq#message-status)
webhook to [your configured URL](/medical-api/api-reference/settings/post-settings).

You can also check status by polling [Get Message Status](/medical-api/api-reference/message/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`](/medical-api/handling-data/webhooks-with-nq#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](/medical-api/api-reference/message/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](/medical-api/api-reference/fhir/consolidated-data-query-post).

## 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](/medical-api/getting-started/webhooks).
2. Handle `message.received` and `message.status` webhooks - see
   [Message Events](/medical-api/handling-data/webhooks-with-nq#message-events) for payload details.
3. Upload documents before sending, if your message includes attachments - see
   [Upload Document](/medical-api/api-reference/document/post-upload-url).

## The full flow

### Sending a message

1. [Create Patient](/medical-api/api-reference/patient/create-patient), if they
   don't exist already.
2. Optionally upload documents with [Upload Document](/medical-api/api-reference/document/post-upload-url)
   or FHIR data with [Create Patient's Consolidated Data](/medical-api/api-reference/fhir/create-patient-consolidated)
   and note the document IDs.
3. Find the recipient's `destination` with [Search Destinations](/medical-api/api-reference/message/search-destinations).
4. Call [Send Message](/medical-api/api-reference/message/send-message).
5. Await the [`message.status`](/medical-api/handling-data/webhooks-with-nq#message-status) webhook, or
   poll [Get Message Status](/medical-api/api-reference/message/get-message-status).

### Receiving a message

1. Await the [`message.received`](/medical-api/handling-data/webhooks-with-nq#message-received) webhook.
2. Download the message from the presigned URL in the payload.
3. Optionally list historical messages with [List Messages](/medical-api/api-reference/message/list-messages).

## Finding a destination

Use [Search Destinations](/medical-api/api-reference/message/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](/medical-api/api-reference/message/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.

<Tip>The `destination` is an OID or a Direct email</Tip>