Start Network Query

Triggers a network query for the specified patient across all available health data networks.

POST /medical/v1/network/query

Start Network Query

cURL

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": {}
}
'

Metriport SDK

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",
  },
});

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;
• network-query.hie.first-data-ready: the first batch of HIE data is available to reingest, ahead of the HIE query completing.

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.

Show Source configuration

hie · object

HIE (Health Information Exchange) source configuration.

Show HIE options

enabled · boolean · required

Whether to query the national networks for all-purpose clinical data.

pharmacy · object

Pharmacy source configuration.

Show Pharmacy options

enabled · boolean · required

Whether to query pharmacy sources.

realtime · boolean

Whether to return results in near real time.

This is a premium feature - if you'd like access to it, contact us and let us know!

lab · object

Laboratory source configuration.

Show Lab options

enabled · boolean · required

Whether to query laboratory sources.

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.

Show Metadata properties

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.

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.

Show Source properties

type · string · required

The type of source: hie, pharmacy, or lab.

status · string · required

The status of this source: processing, completed, or failed.

startedAt · string · required

ISO 8601 timestamp of when this specific source request was initiated.

errors · SourceError[]

Array of errors for data sources that could not be queried. Only present when one or more sources fail to start.

Show SourceError properties

source · string · required

The type of source that failed: hie, pharmacy, or lab.

httpStatus · number · required

The HTTP status code representing the error. Common values: - 400 - Bad Request (access to this data source is not enabled for this account) - 429 - Too Many Requests (rate limit exceeded for this data source)

message · string · required

A human-readable description of the error.

timestamp · string · required

ISO 8601 timestamp of when the error occurred.

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"
    }
  ]
}

Metriport SDK

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