POST
/
medical
/
v1
/
document
/
query
Start Document Query
curl --request POST \
  --url https://api.sandbox.metriport.com/medical/v1/document/query \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '{
  "metadata": {}
}'
import { MetriportMedicalApi } from "@metriport/api-sdk";

const metriport = new MetriportMedicalApi("YOUR_API_KEY");

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

const status = await metriport.startDocumentQuery(
"018a80c4-292a-7486-a1234-76yuhe23yu14", // Patient
"018a80c4-292a-7486-a1234-9uiu76yhe234", // Facility
metadata
);

When executed, this endpoint triggers an asynchronous document query across HIEs. This is a two step process where the documents will first be downloaded from the respective HIE and, if they are C-CDA/XML, then converted to FHIR.

Each process (download, conversion) will contain its own total and status as well as the count for successful operations and errors.

When the asynchronous document query finishes, it stores new/updated document references for future requests and updates the status of download to completed. Meanwhile, in the background, files will be converted and the convert count will be incremented. Once all documents have been converted it too will be marked as completed.

If there’s no document to be converted, the total will be set to zero and the status to completed.

Once each process completes, a webhook request will be sent to your configured URL containing the available data. Note: the webhooks will only contain updates for new data fetched in the current document query.

Webhook message types - see the respective section on the webhooks page for more details:

  • medical.document-download: contains the newly downloaded documents for the patient;
  • medical.document-conversion: result of converting the newly downloaded C-CDA documents into FHIR.

If you were to trigger this endpoint again while the query is still processing, you will get a response that reflects the current query progress. So essentially, only a single document query will be running for a patient at any given time.

​
Query Params

​
patientId
string
required

The ID of the Patient for which to list available Documents.

​
facilityId
string
required

The ID of the Facility where the patient is receiving care.

​
pharmacies
boolean

When set to true, the document query will also request detailed medication history nationally across pharmacies and PBMs, including advanced insights like fill data - allowing you to know whether the patient picked up their medications, for example.

This will retrieve up to one year of medication history.

​
Body

​
metadata
object

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 business use case - for example, external IDs. This metadata will be returned in the webhook response.

{
  "metadata": {
     "youCan": "putAny",
     "stringKeyValue": "pairsHere",
  }
}

​
Response

​
download
Progress
​
requestId
string

The ID of your request. This can be referenced for support.

{
  "download": {
    "status": "processing"
  },
  "requestId": "018a80c4-292a-7486-a223-6dcbc636c44c"
}

import { MetriportMedicalApi } from "@metriport/api-sdk";

const metriport = new MetriportMedicalApi("YOUR_API_KEY");

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

const status = await metriport.startDocumentQuery(
"018a80c4-292a-7486-a1234-76yuhe23yu14", // Patient
"018a80c4-292a-7486-a1234-9uiu76yhe234", // Facility
metadata
);

​
Rate Limits

See limits and throttling