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.
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:
These are messages you can expect to receive in the following scenarios:
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;
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.
Metadata about the message. The full format is described here.
type
string
required
The type of the Medical API webhook data message. Can be one of: medical.document-download, medical.document-conversion,
medical.consolidated-data, medical.document-bulk-download-urls.
patients
PatientDocQueryUpdate[]
required
Array of Document query status updates - where each item corresponds to a specific patient.
patiendId
string
required
The Patient ID.
type
string
required
Specifies what step in the Document query flow this message is for - can be one of
document-download | document-conversion.
status
string
required
The outcome of the step corresponding to type - can be one of completed | failed.
documents
DocumentReference[]
An array of objects describing the Documents that can be retrieved for the Patient - will only be present for document-download messages.
id
string
required
The Document ID.
fileName
string
required
Name of the file.
description
string
Human-readable description of the Document.
status
string
Can be one of current, superceded, or entered in error.
indexed
string
When this Document reference was created - formatted to ISO 8601.
mimeType
string
Document MIME type - usually application/xml, or application/pdf.
size
string
Size of the Document in bytes.
type
CodableConcept
What kind of document this is (LOINC if possible).
coding
Coding[]
Array containing the coding defined by a terminology system.
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:
Metadata about the message. The full format is described here.
type
string
required
For Patient Consolidated Data this will always be medical.consolidated-data.
patients
PatientConsolidatedData[]
required
Array of consolidated data query results - where each item corresponds to a specific patient.
patiendId
string
required
The Patient ID.
status
string
required
The outcome of consolidated data query - can be one of completed | failed.
filters
Filter[]
required
The filters used to obtain the patient’s consolidated data.
resources
string
A comma separated, case sensitive list of resources to be returned. If none are provided all
resources will be included.
dateFrom
string
The start date (inclusive) for which to filter returned resources - formatted YYYY-MM-DD as per
ISO 8601. If not provided, no start date filter will be applied.
dateTo
string
The end date (inclusive) for which to filter returned resources - formatted YYYY-MM-DD as per
ISO 8601. If not provided, no end date filter will be applied.
bundle
Bundle
A FHIR Bundle of type “searchset” with the entry being the outcome of the query.
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.
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.