Skip to main content
POST
/
medical
/
v1
/
network
/
query
Start Network Query
curl --request POST \
  --url https://api.sandbox.metriport.com/medical/v1/network/query \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "sources": {
    "hie": {
      "enabled": true
    },
    "pharmacy": {
      "enabled": true,
      "realtime": true
    },
    "lab": {
      "enabled": true
    }
  },
  "proofedIdentityId": "<string>",
  "metadata": {}
}
'
import { MetriportMedicalApi } from "@metriport/api-sdk";

const metriport = new MetriportMedicalApi("YOUR_API_KEY");

const status = await metriport.startNetworkQuery({
  patientId: "00000000-0000-0000-0000-000000000000",
  sources: {
    hie: { enabled: true },
    pharmacy: { enabled: true, realtime: true },
    lab: { enabled: true },
  },
  metadata: {
    youCan: "putAny",
    stringKeyValue: "pairsHere",
  },
});

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.

This endpoint returns a 2XX status code even when one or more data sources fail to start or encounter errors. Source-level failures are reported in the errors array of the response body rather than as HTTP 4XX or 5XX status codes. Always check the errors key in the response to detect partial failures.
This endpoint triggers a network query, an asynchronous query against various kinds of health data sources including HIEs, pharmacies, and laboratories. As data from each source is processed and merged into a patient’s record, also known as their ‘Consolidated Data’, we emit network-query.* webhook events. Every time a source completes, a webhook request will be sent to your configured URL containing a link to download the patient’s consolidated data. Webhook message types - see the webhooks page for more details:
  • network-query.hie: HIE data has been merged into the consolidated bundle;
  • network-query.pharmacy: Pharmacy data has been merged into the consolidated bundle;
  • network-query.lab: Laboratory data has been merged into the consolidated bundle.
For IAS-purposed queries, webhook payloads include purposeOfUse: "ias" when applicable.

​
Headers

​
x-aal2-session
string
Required when the purposeOfUse query parameter is ias. An active AAL2 session ID for the patient’s verified identity. See Create AAL2 Challenge.

​
Query Params

​
patientId
string
required
The ID of the Patient for which to query health data.
​
purposeOfUse
string
default:"treatment"
The purpose of the request. One of treatment or ias. Defaults to treatment. Use ias when the patient is retrieving their own records through Individual Access Services — see Individual Access (IAS).

​
Body

​
sources
object
required
Data sources to query. At least one source must be enabled.
Legacy format: The API also accepts an array of source names (e.g., sources: ["hie", "pharmacy", "lab"]) for backward compatibility, but the object format above is recommended as it supports per-source options.
​
proofedIdentityId
string
Required when the purposeOfUse query parameter is ias. The verified identity returned on the ias.identity.verified webhook.
​
metadata
object
Custom metadata to include with the request. This will be returned in webhook payloads.
Example Request Body: 
{
  "sources": {
    "hie": { "enabled": true },
    "pharmacy": { "enabled": true, "realtime": true },
    "lab": { "enabled": true }
  },
  "metadata": {
    "youCan": "putAny",
    "stringKeyValue": "pairsHere"
  }
}

​
Response

​
requestId
string
required
The unique identifier for this network query request. Use this to track the query status and correlate webhooks.
​
startedAt
string
required
ISO 8601 timestamp of when the network query request was initially made.
​
status
string
required
The overall status of the network query. Can be one of:
  • processing - at least one source is still being queried
  • completed - all sources have completed successfully
  • partial - some sources completed, some failed
  • failed - all sources failed
​
sources
Source[]
required
Array of status objects for each data source being queried. A source type may appear multiple times if it was retried after a failure.
​
errors
SourceError[]
Array of errors for data sources that could not be queried. Only present when one or more sources fail to start.
Example Response Body (all sources started): 
{
  "requestId": "00000000-0000-0000-0000-000000000000",
  "startedAt": "2024-12-30T10:00:00.000Z",
  "status": "processing",
  "sources": [
    {
      "type": "hie",
      "status": "processing",
      "startedAt": "2024-12-30T10:00:00.500Z"
    },
    {
      "type": "pharmacy",
      "status": "processing",
      "startedAt": "2024-12-30T10:00:00.750Z"
    },
    {
      "type": "lab",
      "status": "processing",
      "startedAt": "2024-12-30T10:00:01.000Z"
    }
  ]
}
Example Response Body (with source errors): 
{
  "requestId": "00000000-0000-0000-0000-000000000000",
  "startedAt": "2024-12-30T10:00:00.000Z",
  "status": "processing",
  "sources": [
    {
      "type": "hie",
      "status": "processing",
      "startedAt": "2024-12-30T10:00:00.500Z"
    }
  ],
  "errors": [
    {
      "source": "pharmacy",
      "httpStatus": 400,
      "message": "Access to pharmacy data source is not enabled for this account",
      "timestamp": "2024-12-30T10:00:00.600Z"
    },
    {
      "source": "lab",
      "httpStatus": 429,
      "message": "Rate limit exceeded for laboratory data source",
      "timestamp": "2024-12-30T10:00:00.800Z"
    }
  ]
}

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

const metriport = new MetriportMedicalApi("YOUR_API_KEY");

const status = await metriport.startNetworkQuery({
  patientId: "00000000-0000-0000-0000-000000000000",
  sources: {
    hie: { enabled: true },
    pharmacy: { enabled: true, realtime: true },
    lab: { enabled: true },
  },
  metadata: {
    youCan: "putAny",
    stringKeyValue: "pairsHere",
  },
});

​
Rate Limits

See limits and throttling