POST
/
medical
/
v1
/
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 metriportClient = new MetriportMedicalApi("YOUR_API_KEY");

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

const status = await api.startDocumentQuery(
  "2.16.840.1.113883.3.666.5.2004.4.2005",
  "2.16.840.1.113883.3.666.123",
  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.

To get updates about the document query progress, including download and conversion status, check out our webhooks guide. Note that the webhooks will only contain updates for new data fetched in the current document query.

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.

​
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"
}
Delete PatientGet Document Query Status