Metriport

https://docs.metriport.com
Admin
Metriport is a Medical API platform that enables healthcare applications to exchange comprehensive...
Tokens:206,669
Snippets:2,771
Trust Score:7.8
Update:3 months ago
Show doc for...
Tokens:
Raw
### Start Bulk Get Document URL

Source: https://docs.metriport.com/medical-api/api-reference/document/download-url-bulk

Triggers a process to generate a list of download URLs for all of the patient's documents. The status of this asynchronous process is returned in the response.

```APIDOC
## POST /medical-api/api-reference/document/download-url-bulk

### Description
Triggers a process to generate a list of download URLs for all of the patient's documents. This is an asynchronous process, and the status is returned in the response to the original request.

### Method
POST

### Endpoint
/medical-api/api-reference/document/download-url-bulk

### Parameters
#### Query Parameters
- **patientId** (string) - Required - The ID of the patient for which to initiate the bulk URL generation.

#### Request Body
- **metadata** (object) - Optional - Arbitrary key-value pairs that will be included in the webhook request.

### Response
#### Success Response (200)
- **status** (string) - Required - The status of the URL generation process - can be `processing`, `completed`, or `failed`.
- **requestId** (string) - Required - A unique identifier for the request.

### Response Example
```json
{
  "status": "processing",
  "requestId": "018c1e9d-dfce-70cb-8c0e-edfbbd2a7f5f"
}
```
```

--------------------------------

### Response Example for Set Patient Facilities

Source: https://docs.metriport.com/medical-api/api-reference/patient/set-patient-facilities

Example JSON response illustrating the structure of facilities associated with a patient after an update.

```json
{
  "facilities": [
    {
      "id": "018a80c4-292a-7486-a1234-9uiu76yhe234",
      "eTag": "1",
      "oid": "2.16.840.1.113883.3.666.123.4.101",
      "name": "Care Facility, LLC",
      "npi": "1234567891",
      "tin": "12-3456789",
      "active": true,
      "address": {
        "addressLine1": "2261 Market Street",
        "addressLine2": "#4818",
        "city": "San Francisco",
        "state": "CA",
        "zip": "94114",
        "country": "USA"
      }
    },
    {
      "id": "018a80c4-292a-7486-a1234-6hyt345tyu23",
      "eTag": "1",
      "oid": "2.16.840.1.113883.3.666.123.4.102",
      "name": "Care Facility 2, LLC",
      "npi": "1789123456",
      "tin": "12-6789345",
      "active": true,
      "address": {
        "addressLine1": "451 Care Street",
        "addressLine2": "#320",
        "city": "Austin",
        "state": "TX",
        "zip": "78617",
        "country": "USA"
      }
    }
  ]
}

```

--------------------------------

### Example Response for Creating Patient Data

Source: https://docs.metriport.com/medical-api/api-reference/fhir/create-patient-consolidated

This is an example of the transaction-response Bundle returned after successfully creating a patient's consolidated data.

```json
{
  "resourceType": "Bundle",
  "id": "bc0fcad0-6457-4b9e-93b3-44212e386138",
  "type": "transaction-response",
  "entry": [
    {
      "response": {
        "status": "201 Created",
        "location": "Appointment/3/_history/1",
        "etag": "1",
        "lastModified": "2023-07-27T21:29:31.491+00:00",
        "outcome": {
          "resourceType": "OperationOutcome",
          "issue": [
            {
              "severity": "information",
              "code": "informational",
              "details": {
                "coding": [
                  {
                    "system": "https://public.metriport.com/fhir/StructureDefinition/operation-outcome",
                    "code": "SUCCESSFUL_CREATE",
                    "display": "Create succeeded."
                  }
                ]
              },
              "diagnostics": "Successfully created resource \"Appointment/3/_history/1\". Took 7ms."
            }
          ]
        }
      }
    }
  ]
}
```

--------------------------------

### Example Response for Update Settings

Source: https://docs.metriport.com/medical-api/api-reference/settings/post-settings

This is an example of the JSON response received after successfully updating settings. It includes the settings ID, the configured webhook URL, and the associated webhook key.

```json
{
  "id": "<settings-id>",
  "webhookUrl": "https://server.domain.com/webhook/endpoint",
  "webhookKey": "<webhook-key>"
}
```

--------------------------------

### Metriport SDK Usage Examples

Source: https://docs.metriport.com/medical-api/api-tools/sdk

Examples demonstrating common operations using the initialized Metriport client. These include creating facilities, fetching patient data, and listing patient documents.

```typescript
// Create a Facility
const patient = await metriportClient.createFacility({
  // facility data
});

// Get a Patient
const patient = await metriportClient.getPatient(patientId);

// List the given Patient's available documents/records
const documents = await metriportClient.listDocuments(patientId, facilityId);
```

--------------------------------

### Start Bulk Get Document URL using Metriport SDK

Source: https://docs.metriport.com/medical-api/api-reference/document/download-url-bulk

Use this JavaScript code snippet with the Metriport SDK to initiate the generation of download URLs for a patient's documents. Ensure you replace 'YOUR_API_KEY' with your actual API key.

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

const metriport = new MetriportMedicalApi("YOUR_API_KEY");

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

const status = await metriport.startBulkGetDocumentUrl(
  "018a80c4-292a-7486-a1234-76yuhe23yu14",
  metadata
);

```

--------------------------------

### Facility API Response Example

Source: https://docs.metriport.com/medical-api/api-reference/facility/list-facilities

This is an example of the JSON response structure when listing facilities. It includes details such as ID, name, NPI, TIN, and address for each facility.

```json
{
  "facilities":[
    {
      "id": "018a80c4-292a-7486-a1234-9uiu76yhe234",
      "oid": "2.16.840.1.113883.3.666.123.4.101",
      "name": "Care Facility, LLC",
      "npi": "1234567891",
      "tin": "12-3456789",
      "active": true,
      "address": {
        "addressLine1": "2261 Market Street",
        "addressLine2": "#4818",
        "city": "San Francisco",
        "state": "CA",
        "zip": "94114",
        "country": "USA"
      }
    },
    {
      "id": "018a80c4-292a-7486-a1234-6hyt345tyu23",
      "oid": "2.16.840.1.113883.3.666.123.4.102",
      "name": "Care Facility 2, LLC",
      "npi": "1789123456",
      "tin": "12-6789345",
      "active": true,
      "address": {
        "addressLine1": "451 Care Street",
        "addressLine2": "#320",
        "city": "Austin",
        "state": "TX",
        "zip": "78617",
        "country": "USA"
      }
    }
  ]
}
```

--------------------------------

### HIE First Data Ready Event Payload Example

Source: https://docs.metriport.com/medical-api/handling-data/webhooks-with-nq

Example payload for an HIE query where the first batch of data is ready. Note the 'processing' status and 'firstDataReadyAt' timestamp.

```json
{
  "meta": {
    "messageId": "11111111-1111-1111-1111-111111111111",
    "requestId": "22222222-2222-2222-2222-222222222222",
    "when": "2024-12-26T10:03:22.000Z",
    "type": "network-query.hie.first-data-ready",
    "data": {
      "youCan": "putAny",
      "stringKeyValue": "pairsHere"
    }
  },
  "payload": {
    "patientId": "00000000-0000-0000-0000-000000000000",
    "externalId": "1234567890",
    "consolidatedDataUrl": "https://documents.s3.amazonaws.com/consolidated-abc123-Amz-SignedHeaders=host",
    "source": {
      "type": "hie",
      "status": "processing",
      "firstDataReadyAt": "2024-12-26T10:03:18.000Z"
    }
  }
}
```

--------------------------------

### Example DocumentReference Payload

Source: https://docs.metriport.com/medical-api/api-reference/document/post-upload-url

This is an example JSON payload for creating a DocumentReference resource. It includes details like description, type, and context of the document.

```json
{
  "description": "Third degree wrist burn treatment",
  "type": {
    "text": "Burn management Hospital Progress note",
    "coding": [
      {
        "code": "100556-0",
        "system": "http://loinc.org",
        "display": "Burn management Hospital Progress note"
      },
    ]
  },
  "context": {
    "period": {
      "start": "2023-10-10T14:14:17Z",
      "end": "2023-10-10T15:30:30Z"
    },
    "facilityType": {
      "text": "John Snow Clinic - Acute Care Centre"
    }
  }
}
```

--------------------------------

### Initialize SDK with Sandbox Options

Source: https://docs.metriport.com/medical-api/getting-started/sandbox

To connect to the sandbox environment using the SDK, provide the `options` parameter with `sandbox = true` during initialization.

```javascript
import Metriport from "metriport";

const metriport = new Metriport({
  sandbox: true,
  // ... other options
});
```

--------------------------------

### Get Network Query Status with Metriport SDK

Source: https://docs.metriport.com/medical-api/api-reference/network/get-network-query

Use this snippet to check the progress of a network query. Ensure you have your API key and the request ID from when the query was started.

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

const metriport = new MetriportMedicalApi("YOUR_API_KEY");

const status = await metriport.getNetworkQueryStatus({
  requestId: "22222222-2222-2222-2222-222222222222",
});

```

--------------------------------

### Get Message Status Response Example

Source: https://docs.metriport.com/medical-api/api-reference/message/get-message-status

This JSON object represents the response when retrieving the status of a message. It includes details about the communication resource, its status, sender, recipient, and payload.

```json
{
  "communication": {
    "resourceType": "Communication",
    "id": "00000000-0000-0000-0000-000000000000",
    "status": "in-progress",
    "subject": {
      "reference": "Patient/00000000-0000-0000-0000-000000000000"
    },
    "topic": {
      "text": "Referral - cardiology"
    },
    "sender": {
      "display": "Your Organization name"
    },
    "recipient": [
      {
        "type": "Organization",
        "display": "intake@cardio.direct.partner.com"
      },
      {
        "type": "Practitioner",
        "display": "1234567893"
      }
    ],
    "sent": "2026-06-16T18:40:00.000Z",
    "payload": [
      {
        "contentReference": {
          "reference": "DocumentReference/00000000-0000-0000-0000-000000000000"
        }
      }
    ],
    "extension": [
      {
        "url": "https://public.metriport.com/fhir/StructureDefinition/data-source.json",
        "valueCoding": {
          "system": "https://public.metriport.com/fhir/StructureDefinition/data-source.json",
          "code": "METRIPORT"
        }
      }
    ]
  }
}
```

--------------------------------

### Start Bulk Get Document URL

Source: https://docs.metriport.com/llms.txt

Triggers a process to generate a list of download URLs for all of the patient's documents. This is part of the document management features in the Medical API.

```APIDOC
## POST /document/download-url-bulk

### Description
Triggers a process to generate a list of download URLs for all of the patient's documents.

### Method
POST

### Endpoint
/document/download-url-bulk

### Request Body
- **patient_id** (string) - Required - The ID of the patient.

### Response
#### Success Response (200)
- **message** (string) - Indicates the process has started.
```

--------------------------------

### Care Gap API Response Example

Source: https://docs.metriport.com/medical-api/api-reference/analytics/care-gaps/get-care-gap

This JSON object represents a FHIR Bundle returned by the Get Care Gap API. It includes patient details, a MeasureReport detailing care gap status, and parameters used in the calculation.

```json
{
  "resourceType": "Bundle",
  "type": "collection",
  "entry": [
    {
      "fullUrl": "urn:uuid:11111111-1111-1111-1111-111111111111",
      "resource": {
        "resourceType": "Patient",
        "id": "00000000-0000-0000-0000-000000000000",
        "identifier": [
          {
            "value": "1234567890",
            "system": "https://public.metriport.com/fhir/StructureDefinition/external-id.json",
            "use": "secondary"
          }
        ],
        "name": [
          { "given": ["Alex"], "family": "Example" }
        ],
        "gender": "female",
        "birthDate": "1980-01-15"
      }
    },
    {
      "fullUrl": "urn:uuid:22222222-2222-2222-2222-222222222222",
      "resource": {
        "resourceType": "MeasureReport",
        "id": "BreastCancerScreening.00000000-0000-0000-0000-000000000000.2025-01-01",
        "status": "complete",
        "type": "individual",
        "measure": "http://ncqa.org/fhir/Measure/BreastCancerScreening",
        "subject": {
          "reference": "Patient/00000000-0000-0000-0000-000000000000"
        },
        "period": {
          "start": "2025-01-01",
          "end": "2025-12-31"
        },
        "extension": [
          {
            "url": "https://public.metriport.com/fhir/StructureDefinition/job-id",
            "valueString": "99999999-9999-9999-9999-999999999999"
          }
        ],
        "group": [
          {
            "id": "BreastCancerScreening",
            "code": {
              "coding": [
                {
                  "system": "https://ncqa.org/fhir/CodeSystem/measure-group",
                  "code": "BreastCancerScreening"
                }
              ]
            },
            "population": [
              {
                "code": {
                  "coding": [
                    {
                      "system": "https://ncqa.org/fhir/CodeSystem/measure-group",
                      "code": "initial-population"
                    }
                  ]
                },
                "count": 1
              },
              {
                "code": {
                  "coding": [
                    {
                      "system": "https://ncqa.org/fhir/CodeSystem/measure-group",
                      "code": "denominator"
                    }
                  ]
                },
                "count": 1
              },
              {
                "code": {
                  "coding": [
                    {
                      "system": "https://ncqa.org/fhir/CodeSystem/measure-group",
                      "code": "denominator-exclusion"
                    }
                  ]
                },
                "count": 0
              },
              {
                "code": {
                  "coding": [
                    {
                      "system": "https://ncqa.org/fhir/CodeSystem/measure-group",
                      "code": "numerator"
                    }
                  ]
                },
                "count": 0
              }
            ]
          }
        ]
      }
    },
    {
      "fullUrl": "urn:uuid:33333333-3333-3333-3333-333333333333",
      "resource": {
        "resourceType": "Parameters",
        "parameter": [
          {
            "name": "Age at end of measurement period",
            "valueInteger": 42
          },
          {
            "name": "Is continuously enrolled",
            "valueBoolean": true
          },
          {
            "name": "Initial population",
            "valueBoolean": true
          },
          {
            "name": "Denominator",
            "valueBoolean": true
          },
          {
            "name": "Numerator",
            "valueBoolean": false
          },
          {
            "name": "Mammography screening period",
            "valuePeriod": {
              "start": "2023-10-01",
              "end": "2025-12-31"
            }
          }
        ]
      }
    }
  ]
}
```

--------------------------------

### Initialize Metriport SDK for Node.js

Source: https://docs.metriport.com/medical-api/getting-started/quickstart

Initialize the Metriport SDK for use in your Node.js server. This is a common setup step for server-side integrations.

```javascript
import Metriport from "metriport";

const metriport = new Metriport({
  apiKey: "YOUR_API_KEY",
  // For sandbox mode, use:
  // baseUrl: "https://sandbox.metriport.com/api",
});
```

--------------------------------

### Get Document URL

Source: https://docs.metriport.com/medical-api/api-reference/document/get-document

Gets a downloadable URL for downloading the specified document.

```APIDOC
## Get Document URL

### Description
Gets a downloadable URL for downloading the specified document.

### Method
GET

### Endpoint
/document

### Query Parameters
- **fileName** (string) - Required - The file name of the document. You can get this from the meta.source attribute of any FHIR resource.
- **conversionType** (string) - Optional - The document type to convert to. Either `html` or `pdf`. This parameter should only be used for converting XML/CDA files.

### Response
#### Success Response (200)
- **url** (string) - The downloadable URL.

### Response Example
{
  "url": "https://example.com/download/document.pdf"
}
```

--------------------------------

### SDK Initialization

Source: https://docs.metriport.com/medical-api/api-tools/sdk

Initialize the Metriport API client in your Node.js application.

```typescript
import MetriportClient from "@metriport/api-sdk";

const metriportClient = new MetriportClient({
  apiKey: "YOUR_API_KEY",
  // other options
});
```

--------------------------------

### Get Facility

Source: https://docs.metriport.com/llms.txt

Gets a Facility's details. This is part of the facility management features in the Medical API.

```APIDOC
## GET /facility/{facility_id}

### Description
Gets a Facility.

### Method
GET

### Endpoint
/facility/{facility_id}

### Parameters
#### Path Parameters
- **facility_id** (string) - Required - The ID of the facility.

### Response
#### Success Response (200)
- **facility_details** (object) - Details of the facility.
```

--------------------------------

### Create Facility using Metriport SDK

Source: https://docs.metriport.com/medical-api/api-reference/facility/create-facility

Use the Metriport SDK to create a new facility. Ensure you have your API key and provide all required facility details.

```javascript
import { MetriportMedicalApi, USState } from "@metriport/api-sdk";

const metriport = new MetriportMedicalApi("YOUR_API_KEY");

const facility = await metriport.createFacility({
  name: "Care Facility, LLC",
  npi: "1234567891",
  tin: "12-3456789",
  active: true,
  address: {
    addressLine1: "2261 Market Street",
    addressLine2: "#4818",
    city: "San Francisco",
    state: USState.CA,
    zip: "94114",
    country: "USA",
  },
});
```

--------------------------------

### List Facilities with Metriport SDK

Source: https://docs.metriport.com/medical-api/api-reference/facility/list-facilities

Use the Metriport SDK to retrieve a list of all facilities. Ensure you replace 'YOUR_API_KEY' with your actual API key.

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

const metriport = new MetriportMedicalApi("YOUR_API_KEY");

const facilities = await metriport.listFacilities();
```

--------------------------------

### Example C-CDA XML Document

Source: https://docs.metriport.com/converter-api/getting-started/quickstart

This is an example of a C-CDA XML document structure. You will send this as the request body to the conversion endpoint.

```xml
<?xml version="1.0" encoding="UTF-8"?>
<ClinicalDocument xmlns="urn:hl7-org:v3">
    <!-- contents -->
</ClinicalDocument>
```

--------------------------------

### Send Message using Metriport SDK

Source: https://docs.metriport.com/medical-api/api-reference/message/send-message

This JavaScript example demonstrates how to use the Metriport SDK to send a message. Ensure you have your API key and the necessary attachment IDs.

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

const metriport = new MetriportMedicalApi("YOUR_API_KEY");

const status = await metriport.sendMessage({
  patientId: "11111111-1111-1111-1111-111111111111",
  destination: "intake@cardio.direct.partner.com",
  subject: "Referral - cardiology",
  body: "Please review the attached referral for cardiology consultation.",
  attachments: ["00000000-0000-0000-0000-000000000000"],
  intendedRecipientNpi: ["1234567890"],
});
```
Tokens:
Raw