canonical: https://jentic.com/apis/metriport.com/metriport

# Metriport Medical API

The Metriport Medical API gives developers programmatic access to healthcare facilities, patients, and FHIR-formatted clinical documents. It supports patient demographics, document queries against connected health information networks, bulk document download, and consolidated FHIR data queries - making it useful for digital health products that need a unified view of a patient's medical history. Authentication uses a tenant API key passed in the x-api-key header.

## For AI agents

Look up patients, request clinical documents from health information networks, and run FHIR-based consolidated data queries against a tenant's medical record graph.

## Scope

Does not handle clinical scheduling, billing, claims submission, or e-prescribing - use for patient demographics, document retrieval, and FHIR consolidated queries only.

## Capabilities

- Register an organization and create the facilities a patient roster lives under
- Manage patient demographics with create, retrieve, update, and remove operations
- Trigger document queries that pull clinical records from connected HIE networks for a patient
- Download patient documents individually or as a bulk archive
- Run consolidated FHIR data queries that return a unified resource bundle for a patient

## Use cases

### Patient Onboarding with Auto-Document Pull

Digital health products onboarding a new patient can register the patient via POST /patient and immediately trigger POST /document/query/{patientId} to pull historical records from connected health information exchanges. This delivers a consolidated medical history within minutes of signup, without requiring the patient to upload PDFs manually.

Example prompt: Create a patient under facility 'fac_123' with demographics, then call POST /document/query/{patientId} and poll for completion.

### Consolidated FHIR for Care Coordination

Care coordination tools need a single FHIR view spanning encounters, conditions, medications, and lab results. POST /patient/{patientId}/consolidated/query starts the query and the agent retrieves the resulting bundle, which already conforms to FHIR R4 so it can drop into existing clinical decision systems without translation.

Example prompt: Start a consolidated query for patient 'pat_456' filtered to Encounter and Condition resources and return the resulting FHIR bundle.

### Bulk Document Migration

When a clinic switches EHRs or pulls historical archives, POST /document/bulk/download/{patientId} produces a packaged set of documents for a patient that can be ingested into the new system. Combined with /facility and /patient listings, this supports systematic migration without per-document manual handling.

Example prompt: List all patients in facility 'fac_789', then for each patient start a bulk document download and collect the resulting URLs.

### Agent-Assisted Clinical Lookups Through Jentic

An AI agent supporting a clinician can fetch a patient's consolidated record on demand by searching Jentic for the operation, loading the input schema for /patient/{patientId}/consolidated/query, and executing with the patient ID. The Metriport x-api-key never enters the agent context - Jentic injects it at execution time.

Example prompt: Search Jentic for 'get a patient's consolidated FHIR record', load the operation, and execute with patient ID and the requested resource types.

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| POST | /patient | Create a patient under a facility |
| GET | /patient/{id} | Retrieve a patient by ID |
| POST | /document/query/{patientId} | Start a document query for a patient |
| POST | /document/bulk/download/{patientId} | Start a bulk document download |
| POST | /patient/{patientId}/consolidated/query | Start a FHIR consolidated query |
| POST | /document/upload/{patientId} | Upload a document to a patient record |

## Key resources

- **Organization** — Create the parent organization for your tenant
- **Facility** — List, create, retrieve, and update facilities under the organization
- **Patient** — Full lifecycle for patient demographics - create, list, retrieve, update, delete
- **Document** — Trigger document queries, get download URLs, request bulk downloads, and upload documents
- **Consolidated** — Start FHIR consolidated queries and post consolidated data for a patient

## Why Jentic

- **Setup:** Wiring the Metriport Medical API by hand means reading its x-api-key header scheme, threading the patient id through document and consolidated queries against the /medical/v1 base, and handling errors yourself. Through Jentic you install once, import the Metriport Medical API from the API Directory, store the API key once, and your agent calls it.
- **Permission scoping:** Metriport puts the patient id in the URL path (/document/query/{patientId}, /patient/{patientId}/consolidated/query), so a rule can pin your agent to one patient's records and nothing else. You choose the operations it may call, so a bulk document download or upload is not included unless you add it.
- **Credential handling:** Your Metriport x-api-key is stored once, encrypted, by your own Jentic One instance and injected into the x-api-key header at execution time. It never enters the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'pull a patient's medical records' or 'query consolidated FHIR data', and Jentic returns the matching Metriport operation with its input schema so the agent calls the right endpoint without browsing the reference docs.

## Related APIs

- **DrChrono** — Cloud EHR with patient, appointment, and clinical APIs
- **athenahealth** — EHR and practice management API
- **Experian** — Identity verification useful before requesting medical records

## FAQ

### What authentication does the Metriport Medical API use?

Metriport uses an API key passed in the x-api-key header. Through Jentic the key is stored encrypted in the vault and added to the request at execution time so the agent never sees it.

### Can I retrieve a patient's full medical history with one call?

POST /patient/{patientId}/consolidated/query starts a job that produces a single FHIR bundle covering the resource types you request. You poll or webhook for completion and then GET the resulting bundle from the returned URL.

### What are the rate limits for the Metriport API?

The OpenAPI spec does not enumerate fixed rate limits - they are set by your Metriport plan and the upstream health information network. Watch for 429 responses and stagger bulk document jobs across patients to avoid throttling.

### How do I trigger a document pull for a new patient through Jentic?

Search Jentic for 'pull medical documents for a patient', load the POST /document/query/{patientId} operation, and execute with the patientId returned from POST /patient. Jentic handles the x-api-key from your stored credential.

### Does Metriport return raw HL7 v2 messages?

No - Metriport normalises everything to FHIR R4 resources. If you specifically need raw HL7 v2 you would integrate directly with the source EHR or a separate HL7 broker.

### Can I upload documents back into the patient record?

Yes. POST /document/upload/{patientId} attaches a document to the patient - useful for adding scans, intake forms, or external lab results into the consolidated view.

### Can I limit what my agent is allowed to do with the Metriport Medical API?

Yes. Because your Jentic One instance is self-hosted, your own rules decide which Metriport operations and credentials the agent may use. Metriport carries the patient id in the URL path, as in /document/query/{patientId} and /patient/{patientId}/consolidated/query, so a rule can pin the agent to a single patient's records and nothing else. You also choose which operations it may call, so a bulk document download or a document upload stays off limits unless you explicitly add it.