​
Overview

When using the Medical API, Metriport will send Webhook messages to your app as soon as data becomes available.

This is the usual flow to obtain Patient data:

  1. You trigger a document query to retrieve a Patient’s medical documents from HIEs;
    • XML C-CDA documents will be converted and stored on Metriport’s FHIR storage;
    • as documents get downloaded and converted, you should get patient document data webhook messages;
  2. Once document conversion is completed, you can query for patient consolidated data;
    • depending on the amount of data this can take some time to crunch together, so results are sent through a webhook message: patient consolidated data

You should expect to get more than one Webhook message per patient per request (document query and/or consolidated data).

To enable this integration approach with Metriport, and for some prerequesite reading to understand how the Webhook flow works, see our Webhooks guide.

When you receive a webhook message, you should respond with a 200 status code within 4 seconds. We recommend processing the webhook request asynchronously.

​
Types of Messages

  • medical.document-download: result of Document Query, containing the newly downloaded documents for the patient - see details below;
  • medical.document-conversion: result of converting the newly downloaded C-CDA documents into FHIR - see details below;
  • medical.document-bulk-download-urls: list of download urls for a patient’s documents, see details below;
  • medical.consolidated-data: result of a Consolidated Data Query, containing the patient’s data in FHIR format - see details below.

​
Workflow

​
Download URLs

Below is a flowchart of the process to download all the raw documents we’ve received from the networks for a patient:

​
Consolidated Data

Below is a flowchart of the process to get a patient’s consolidated FHIR data:

​
Passing Metadata

You can pass metadata to endpoints that support webhooks, and you will receive the meta.data field of the webhook request.

Metadata holds a record of up to 50 custom string key-value pairs. Key names can be up to 40 characters long and values up to 500 characters long. You may use this to attach whatever metadata is relevant for your use-case - for example, external IDs. Below is an example payload you could send in the request body of one of those endpoints and how you would use the sdk:

{
  "metadata": {
     "youCan": "putAny",
     "stringKeyValue": "pairsHere",
  }
}
Metriport SDK
import { MetriportMedicalApi } from "@metriport/api-sdk";

const metadata = {
    youCan: "putAny",
    stringKeyValue: "pairsHere",
};

const metriport = new MetriportMedicalApi(apiToken);

const consolidatedData = await metriport.startConsolidatedQuery(
  patientId,
  ["AllergyIntolerance", "Appointment"] as const,
  "2023-03-01",
  "2023-04-01",
  undefined,
  metadata
);

​
Patient Document Data

These are messages you can expect to receive in the following scenarios:

  1. When queried documents have completed downloading, the message type will be medical.document-download, and at this point you’ll be able to download the raw files;
  2. Then, if the downloaded documents contained C-CDA/XML files, when the conversion to FHIR has completed, the message type will be medical.document-conversion, and at this point you’ll be able to query for patient consolidated data in FHIR-compliant format.

Note that the webhooks will only contain updates for new data fetched in the current document query.

{
  "meta": {
    "messageId": "<message-id>",
    "when": "<date-time-in-utc>",
    "type": "medical.document-download"
    "data": {
        youCan: "putAny",
        stringKeyValue: "pairsHere",
    }
  },
  "patients": [
    {
      "patientId": "<patient-id-1>",
      "externalId": "<external-id-1>",
      "type": "document-download",
      "status": "completed",
      "documents": [
        {
          "id": "1.2.543.1.34.1.34.134",
          "fileName": "CCDA_Diag.xml",
          "description": "Patient Diagnoses",
          "status": "current",
          "indexed": "2019-09-07T15:50:00.000Z",
          "mimeType": "application/xml",
          "size": "17344007",
          "type": {
            "coding": [
              {
                "system": "http://snomed.info/sct",
                "code": "62479008",
                "display": "Diagnoses"
              }
            ],
            "text": "Diagnoses"
          }
        },
        {
          "id": "1.2.543.1.224.54.22.540",
          "fileName": "Progress_Notes.xml",
          "description": "Patient Encounter Progress Notes 2023-03-22",
          "status": "current",
          "indexed": "2023-03-22T08:34:00.000Z",
          "mimeType": "application/xml",
          "size": "8675545",
          "type": {
            "coding": [
              {
                "system": "http://snomed.info/sct",
                "code": "371532007",
                "display": "Progress Report"
              }
            ],
            "text": "Progress Notes"
          }
        }
      ]
    },
    {
      "patientId": "<patient-id-2>",
      "type": "document-download",
      "status": "completed",
      ...
    }
  ]
}

The format follows:

​
meta
required

Metadata about the message. The full format is described here.

​
patients
PatientDocQueryUpdate[]
required

Array of Document query status updates - where each item corresponds to a specific patient.

​
Patient Consolidated Data

A Patient’s consolidated data is the result of converting C-CDA documents from HIEs into FHIR, as well as other FHIR data your application has inserted into Metriport’s FHIR repository.

Patients can have a large amount of data, so in order to have access to a Patient’s data:

  1. Trigger a consolidated data query - one query per patient at any given time;
  2. Your app can check the status by calling get consolidated query status;
  3. When the result is ready, we’ll send a webhook message with the results (below).

Example payload:

{
  "meta": {
    "messageId": "1e82424a-1220-473d-a0d1-6e5fde15159e",
    "when": "2023-08-23T22:09:11.373Z",
    "type": "medical.consolidated-data"
  },
  "patients": [
    {
      "patientId": "eddeefa1-b54a-41d6-854f-0e91b7871d6a",
      "externalId": "1234567890",
      "status": "completed",
      "filters": {
        "resources": "DocumentReference,Appointment"
      },
      "bundle": {
        "type": "searchset",
        "resourceType": "Bundle",
        "total": 1,
        "entry": [
          {
            "resource": {
              "resourceType": "Appointment",
              "id": "123",
              "start": "2021-06-10T13:00:00.000Z",
              "end": "2021-06-10T13:55:00.000Z",
              "status": "booked",
              "meta": {
                "source": "#cXWJjuhQX33LJ0VJrPiD0",
                "versionId": "2",
                "lastUpdated": "2023-08-23T12:41:54.661-05:00"
              },
              "contained": [
                {
                  "id": "eddeefa1-b54a-41d6-854f-0e91b7871d6a",
                  "meta": {
                    "source": "#4fh35tN5_DjOxfVrq3dfi"
                  },
                  "name": [
                    {
                      "given": ["John"],
                      "family": "Doe"
                    }
                  ],
                  "gender": "male",
                  "address": [
                    {
                      "country": "USA",
                      "postalCode": "12345"
                    }
                  ],
                  "birthDate": "1981-01-01",
                  "resourceType": "Patient"
                }
              ],
              "participant": [
                {
                  "actor": {
                    "display": "John Doe",
                    "reference": "Patient/eddeefa1-b54a-41d6-854f-0e91b7871d6a"
                  },
                  "period": {
                    "end": "2021-05-24T13:21:28.527Z",
                    "start": "2021-05-24T13:21:28.527Z"
                  },
                  "status": "accepted"
                }
              ]
            }
          }
        ]
      }
    }
  ]
}

The format follows:

​
meta
required

Metadata about the message. The full format is described here.

​
patients
PatientConsolidatedData[]
required

Array of consolidated data query results - where each item corresponds to a specific patient.

​
Medical Record

When querying for a Patient’s consolidated data, you can also request this information in PDF or HTML format.

The following is the result of the previous section, but with the Bundle containing a document reference to a rendered Medical Record Summary that represents the resulting FHIR bundle.

Inside the Bundle you’ll find a DocumentReference resource with the first item in the content array containing an attachment with a url which can be used to download the rendered medical record.

Example payload:

{
  "meta": {
    "messageId": "1e82424a-1220-473d-a0d1-6e5fde15159e",
    "when": "2023-08-23T22:09:11.373Z",
    "type": "medical.consolidated-data"
  },
  "patients": [
    {
      "patientId": "eddeefa1-b54a-41d6-854f-0e91b7871d6a",
      "externalId": "1234567890",
      "status": "completed",
      "filters": {
        "resources": "DocumentReference,Appointment"
      },
      "bundle": {
        "resourceType": "Bundle",
        "total": 1,
        "type": "collection",
        "entry": [
          {
            "resource": {
              "resourceType": "DocumentReference",
              "subject": {
                "reference": "Patient/eddeefa1-b54a-41d6-854f-0e91b7871d6a"
              },
              "content": [
                {
                  "attachment": {
                    "contentType": "application/pdf",
                    "url": "https://documents.s3.amazonaws.com/abc123-Amz-SignedHeaders=host"
                  }
                }
              ]
            }
          }
        ]
      }
    }
  ]
}

​
Bulk Document Download URLs

If you want to download all of a patient’s documents, especially when they have a large volume of documents, you can start a Bulk Get Document URL query. We’ll send a webhook message with all the downloadable URLs for all the patient’s documents. You can use the value of the url property in the returned documents objects to download the files.

Here is an example payload:

{
"meta": {
    "messageId": "bd4184dd-3b35-4c60-8130-447d1d528fea",
    "when": "2023-11-30T05:05:12.215Z",
    "type": "medical.document-bulk-download"
  },
  "patients": [
    {
      "status": "completed",
      "patientId": "<patient-id-1>",
      "externalId": "<external-id-1>",
      "documents": [
        {
          "id": "018c1b94-57dc-7950-b564-f74ab9b56cc4",
          "size": 40670,
          "fileName": "81f2ec4e-c71c-4090-bf1c-9d8529f25b5a/018c1b94-2ed9-70f2-8b0f-ad4f8e8c7a16/81f2ec4e-c71c-4090-bf1c-9d8529f65b5a_018c1b94-2ed9-70f2-8b0f-ad4f8e8c7a16_018c1b94-57dc-7950-b564-f74ab9b56cc4.xml",
          "description": "Patient Diagnoses",
          "status": "current",
          "indexed": "2019-09-07T15:50:00.000Z",
          "mimeType": "application/xml",
          "size": 40670,
          "type": {
            "coding": [
              {
                "system": "http://snomed.info/sct",
                "code": "62479008",
                "display": "Diagnoses"
              }
            ],
            "text": "Diagnoses"
          }
          "url": "<a-document-url>"
        },
        {
          "id": "018c1b94-57dc-7950-b564-f749bcf9be3e",
          "fileName": "81f2ec4e-c71c-4090-bf1c-9d8529f25b5a/018c1b94-2ed9-70f2-8b0f-ad4f8e8c7a16/81f2ec4e-c71c-4090-bf1c-9d8529f65b5a_018c1b94-2ed9-70f2-8b0f-ad4f8e8c7a16_018c1b94-57dc-7950-b564-f749bcf9be3e.pdf",
          "description": "Patient Diagnoses",
          "status": "current",
          "indexed": "2019-09-07T15:50:00.000Z",
          "mimeType": "application/pdf",
          "size": 77093,
          "type": {
            "coding": [
              {
                "system": "http://snomed.info/sct",
                "code": "62479008",
                "display": "Diagnoses"
              }
            ],
            "text": "Diagnoses"
          }
          "url": "<another-document-url>"
        }
      ],
    }
  ]
}

The format is as follows:

​
meta
required

Metadata about the message. The full format is described here.

​
patients
DocumentBulkDownloadUrls[]
required

An array of Document bulk download URLs, where each item corresponds to the queried patient.

Medical Record SummaryFiltering data