--- title: Metriport API Integration on Truto slug: metriport category: Healthcare canonical: "https://truto.one/integrations/detail/metriport/" --- # Metriport API Integration on Truto **Category:** Healthcare **Status:** Beta ## MCP-ready AI tools Truto exposes 61 tools for Metriport that AI agents can call directly. - **create_a_metriport_patient** — Create a new patient in Metriport for a specified facility where the patient is receiving care. Returns the created patient object including id, firstName, lastName, dob, genderAtBirth, address, personalIdentifiers, and facilityIds. Required: facilityId, firstName, lastName, dob, genderAtBirth, address. - **get_single_metriport_patient_by_id** — Get a single Metriport patient by id. Returns: id, eTag, firstName, lastName, dob, genderAtBirth, address, personalIdentifiers, and facilityIds. Required: id. - **update_a_metriport_patient_by_id** — Update a Metriport patient's demographics, personal identifiers, address, contact info, and consent status. Returns the updated patient object including id, eTag, firstName, lastName, dob, genderAtBirth, address, personalIdentifiers, and facilityIds. Required: id, facilityId. - **list_all_metriport_patients** — List Patients in Metriport, optionally filtered by the Facility where they receive care. Returns: id, firstName, lastName, dob, genderAtBirth, address, personalIdentifiers, facilityIds, eTag. All Patients are returned when no facility is specified. - **delete_a_metriport_patient_by_id** — Delete a Metriport patient by id. Returns an empty 204 response on success. Required: id. - **metriport_patients_get_medical_record_summary** — Get the Medical Record Summary download URL for a Metriport patient in PDF or HTML format. Returns: url, facilities. Required: patient_id, conversionType. The download URL is valid for 600 seconds (10 minutes). - **metriport_patients_get_medical_record_summary_status** — Check if a Medical Record Summary already exists for a Metriport patient and when it was generated in PDF and HTML formats. Returns: htmlCreatedAt, pdfCreatedAt. Required: patient_id. - **metriport_patients_match** — Match an existing Metriport patient by demographics without creating a new record — use it to resolve your patient to a Metriport patient id before other calls. Returns the matched patient: id, eTag, firstName, lastName, dob, genderAtBirth, address, personalIdentifiers, contact, and facilityIds. Returns 404 if no patient matches. Required: firstName, lastName, dob, genderAtBirth. - **metriport_patients_bulk_create** — Create a batch of patients in Metriport and initiate Document Queries for all of them. This is an asynchronous endpoint — the response contains a presigned upload URL for a CSV file of patient demographics that is valid for 10 minutes. Returns: requestId, status, uploadUrl. Supports a maximum of 100,000 patients per batch. - **metriport_patients_get_by_external_id** — Get a Metriport patient by their external identifier (the ID from your internal system/EHR). Returns: id, eTag, firstName, lastName, dob, genderAtBirth, address, personalIdentifiers, facilityIds. Required: externalId. - **metriport_patients_get_facilities** — Get all facilities associated with a Metriport patient. Returns each facility's id, eTag, oid, name, npi, tin, active, and address. Required: patient_id. - **metriport_patients_set_facilities** — Set (replace) all facilities associated with a Metriport patient. This operation overrides any existing facility associations. Returns the facilities array including each facility's id, eTag, oid, name, npi, tin, active, and address. Required: patient_id, facilityIds. - **metriport_patients_update_treatment_relationship** — Update a patient's treatment relationship consent status in Metriport. Set to true to grant consent or false to revoke it; revoking automatically removes the patient from all treatment cohorts. Returns: id, treatmentRelationship, message, requestId, status, uploadUrl. Required: patient_id, treatmentRelationship. - **metriport_patients_add_to_cohorts** — Add a Metriport patient to multiple cohorts at once. Returns: cohorts — an array of cohort objects, each with id, name, description, color, settings, and size. Required: patient_id, cohortIds. Cohorts the patient already belongs to are silently skipped; patients without a treatment relationship cannot be added to treatment cohorts. - **metriport_patients_list_cohorts** — List all cohorts a Metriport patient is a member of. Returns: id, eTag, name, description, color, settings, size. Required: patient_id. - **metriport_patients_sync_external** — Sync a Metriport patient with an external EHR system, creating a link between the Metriport Patient and the external system when automatic synchronization isn't possible. Returns: patientId, externalId. Required: patient_id. - **metriport_patients_bulk_update** — Update a Metriport patient's Health Information Exchange (HIE) opt-out status. Returns: id, hieOptOut, message, requestId, status, uploadUrl. Required: patient_id, hieOptOut. - **create_a_metriport_facility** — Create a new Facility in Metriport where your patients receive care. Returns the created facility object including id, oid, name, npi, tin, active, and address. Required: name, npi, tin, active, address. - **get_single_metriport_facility_by_id** — Get a single Metriport Facility by id. Returns the facility object including id, oid, name, npi, tin, active, and address. Required: id. - **update_a_metriport_facility_by_id** — Update a Metriport Facility by id. Returns the updated facility object including id, oid, name, npi, tin, active, and address. Required: id, name, npi, tin, active, address. - **list_all_metriport_facilities** — List all Facilities created under your Metriport organization. Returns: id, eTag, oid, name, npi, tin, active, address. - **delete_a_metriport_facility_by_id** — Delete a Metriport Facility by id. Returns an empty 204 response on success. Cannot delete a Facility that has patients associated with it. Required: id. - **metriport_documents_start_query** — Trigger a document query for a specified patient across HIEs in Metriport to retrieve their clinical documents asynchronously. Returns: status, requestId. Required: patientId. - **metriport_documents_get_query_status** — Get the status of a document query previously started for a specified patient in Metriport. Returns: status, requestId. Required: patientId. - **list_all_metriport_documents** — List all FHIR DocumentReferences retrievable for a Patient in Metriport, with optional date range and content search filters. Returns DocumentReference objects including id, resourceType, status, type, subject, description, date, content (with attachment download URLs), author, and context. Required: patientId. - **metriport_documents_get_url** — Get a downloadable URL for a Metriport document by file name. Returns: url, documents. Required: fileName. The URL is valid for 60 seconds; optional conversionType converts XML/CDA files to html or pdf. - **metriport_documents_upload** — Create a DocumentReference in Metriport and receive an upload URL for a medical document. Returns: documentReferenceId, uploadUrl. Required: patientId, type, description, context. Uploads are limited to 50MB per file. - **metriport_documents_start_bulk_get_url** — Start a bulk download URL generation process for all of a patient's documents in Metriport. Returns: status, requestId. Required: patientId. The process is asynchronous — completed URLs are delivered via webhook. Only one bulk process runs per patient at a time; re-triggering while running returns the current progress. - **metriport_consolidated_data_start_query** — Start an asynchronous consolidated data query for a Metriport patient to retrieve cached data in FHIR JSON, PDF, or HTML format. Returns: requestId, status, startedAt, dateFrom, dateTo, resources, conversionType, queries, message. Required: patient_id, conversionType. Results are delivered via webhook when ready; if identical parameters match an in-progress query, the previous request's status is… - **metriport_consolidated_data_get_query_status** — Get the status of all in-progress consolidated data queries for a Metriport patient. Returns: queries, message. Required: patient_id. - **metriport_consolidated_data_get_single_query_status** — Get the status of a single consolidated data query for a Metriport patient by request ID. Returns: requestId, status, startedAt, dateFrom, dateTo, resources, conversionType. Required: patient_id, request_id. - **create_a_metriport_consolidated_datum** — Contribute FHIR resources to a Metriport patient's consolidated data by uploading a FHIR Bundle of type collection. Returns: resourceType, id, type, entry. Required: patient_id, resourceType, type, entry. Content-length must not exceed 1MB (50 resources in sandbox). - **metriport_consolidated_data_count** — Get a count of a Metriport patient's consolidated data per FHIR resource type, with optional date and resource-type filters. Returns: total, resources, filter. Required: patient_id. - **create_a_metriport_cohort** — Create a new Metriport cohort for organizing and managing groups of patients. Returns: id, eTag, name, description, color, settings, size, token. Cohort names must be unique within your organization. Required: name. - **get_single_metriport_cohort_by_id** — Get a single Metriport cohort by id, including the count of patients assigned to it. Returns: id, eTag, name, description, color, settings, size. Required: id. - **list_all_metriport_cohorts** — List all cohorts defined by your organization in Metriport. Returns an array of cohorts, each with id, eTag, name, description, color, settings, and size. - **update_a_metriport_cohort_by_id** — Update an existing Metriport cohort's details (name, description, color, settings). All fields are optional; omitted fields remain unchanged and empty strings clear values. Returns: id, eTag, name, description, color, settings, size. Required: id. - **delete_a_metriport_cohort_by_id** — Delete a Metriport cohort by id. The cohort must be empty — remove all patients first or the API Returns an empty 204 response on success. Returns an empty 204 response on success. Required: id. - **metriport_cohorts_add_patients** — Add patients to a Metriport cohort in bulk. Returns the updated cohort including id, name, description, color, settings, size, and a message. Required: cohort_id. Provide either patientIds or allPatients in the body, but not both. - **metriport_cohorts_remove_patients** — Remove patients from a Metriport cohort in bulk. Returns the updated cohort including id, name, description, color, settings, size, and a message. Required: cohort_id. Provide either patientIds or allPatients in the body, but not both. - **metriport_cohorts_list_patients** — List all patients that are members of a Metriport cohort. Returns: id, eTag, firstName, lastName, dob, genderAtBirth, address, personalIdentifiers, facilityIds. Required: cohort_id. Max 100 items per page. - **create_a_metriport_organization** — Register a new Organization in Metriport representing your legal corporate entity. Returns the created organization including its id, name, type, and location with full address details. Required: type, name, and location containing addressLine1, city, state, zip, and country. - **list_all_metriport_organizations** — Get the Metriport organization representing your legal corporate entity. Returns: id, type, name, location, facilities. - **update_a_metriport_organization_by_id** — Update your Metriport organization's details by id. Returns the updated organization object including id, type, name, and location. Required: id. - **metriport_messages_send** — Send a secure message to another practitioner in the Metriport network regarding a specific patient. Returns the Message object with an initial status of processing; use the returned id to poll via Get Message Status or receive a webhook when delivery completes or fails. Required: patientId, destination. Sending is asynchronous. - **get_single_metriport_message_by_id** — Get the status of a previously sent message in Metriport. Returns: id, patientId, direction, status, transportMethod, network, destination, subject, body, attachments, intendedRecipientNpi, sentAt, updatedAt. Required: id. - **list_all_metriport_messages** — List all inbound and outbound secure messages for your Metriport organization, optionally filtered by direction, patient, destination, or status. Returns: id, patientId, direction, status, transportMethod, network, destination, subject, body, attachments, intendedRecipientNpi, sentAt, updatedAt. Some inbound messages may not be tied to a specific patient. - **metriport_network_queries_start** — Trigger a network query for a Metriport patient to retrieve health data from HIEs, pharmacies, and laboratories. Returns: meta, networkEntries. Required: patient_id. The endpoint returns 2XX even on partial source failures—always check the errors array for source-level failures. - **metriport_network_queries_get_status** — Get the status of a Metriport network query to check its progress in retrieving patient health data from HIEs, pharmacies, and laboratories. Returns: meta (itemsOnPage, itemsInTotal) and networkEntries, each with name, oid, npi, addressLine, city, state, zipCode, rootOrganization, managingOrgOid, network, and supportsMessaging. Required: patient_id, request_id — obtain request_id from the start method. - **list_all_metriport_network_entries** — List HIE (network) directory entries available to your Metriport account, with optional full-text and exact-match filters. Returns: name, oid, npi, addressLine, city, state, zipCode, rootOrganization, managingOrgOid, network, supportsMessaging. - **list_all_metriport_settings** — Get the Metriport account settings. Returns: id, webhookUrl, webhookKey. - **update_a_metriport_setting_by_id** — Update the Metriport account settings, storing a new webhook URL. Returns: id, webhookUrl, webhookKey. Required: webhookUrl. - **metriport_settings_get_webhook_status** — Get the status of communication with your app's webhook in Metriport. Returns: webhookEnabled, webhookStatusDetail, webhookRequestsProcessing, webhookRequestsFailed. Might return an empty body if no settings are stored for your account yet. - **metriport_settings_retry_webhook** — Retry failed webhook requests in Metriport. Returns an empty 204 response on success. - **metriport_tokens_create_embed** — Create an embed access token for embedding Metriport in your application. Returns: token. The optional expirationInSeconds body field accepts a maximum of 36000 seconds (10 hours). - **get_single_metriport_care_gap_by_id** — Get detailed information about a specific Metriport care gap measure report. Returns a FHIR Bundle including a Patient resource, the full MeasureReport with population membership data, and a Parameters resource with supporting calculation details. Required: id. - **list_all_metriport_care_gaps** — List care gaps across all patients in your Metriport organization. Returns: resourceType, type, entry. - **metriport_care_gaps_list_for_patient** — List care gaps for a single Metriport patient. Returns: resourceType, type, entry. Required: patient_id. - **metriport_suspects_list_for_patient** — List suspected conditions for a Metriport patient as FHIR Bundles. Returns each result as a FHIR Bundle with resourceType, type, and entry (containing a Patient, the suspected Condition, and supporting Observation/Procedure/MedicationRequest evidence). Required: patient_id. - **create_a_metriport_identity_session** — Start a hosted IAL2 identity verification session for a Metriport patient, returning a single-use URL where the user completes verification with an approved Credential Service Provider. Returns: sessionId, sessionUrl, expiresAt, status. Required: patientId, redirectUrl. The sessionUrl is single-use and the redirectUrl must be on the account's allowlist. - **create_a_metriport_aal_2_challenge** — Create a multifactor AAL2 challenge for a verified Metriport user. Returns a single-use challenge URL along with its challengeId, expiry timestamp, and authentication method (totp or webauthn). Required: proofedIdentityId, redirectUrl. ## How it works 1. **Link your customer's Metriport account.** Use Truto's frontend SDK; we handle every OAuth and API key flow so you don't need to create the OAuth app. 2. **Authentication is automatic.** Truto refreshes tokens, stores credentials securely, and injects them into every API request. 3. **Call Truto's API to reach Metriport.** The Proxy API is a 1-to-1 mapping of the Metriport API. 4. **Get a unified response format.** Every response uses a single shape, with cursor-based pagination and data in the `result` field. ## Use cases - **Automate chart prep for new patient onboarding** — Care management and telehealth platforms can pull a patient's full out-of-network medical history the moment they register, so clinicians walk into intake visits with a complete chart instead of blank forms. - **Surface care gaps and suspected conditions for value-based care** — Population health and risk adjustment platforms can programmatically flag missing preventative screenings and undiagnosed conditions per patient, helping their clinic customers close gaps and optimize RAF scores. - **Prevent adverse drug interactions at the point of prescribing** — E-prescribing and telehealth apps can pull consolidated FHIR medication histories from nationwide HIEs to cross-reference new prescriptions against a patient's actual active medications across all providers. - **Bulk onboard patient rosters into cohort tracking** — Population health platforms can import CSVs of tens of thousands of patients, assign them to facilities, and group them into cohorts for ongoing clinical monitoring — all through a single sync flow. - **Embed a nationwide clinical record viewer inside your app** — SaaS platforms can offer clinicians a pre-built, standardized medical record viewer without designing UI for hundreds of lab types, notes, and document formats. ## What you can build - **One-click patient network query** — Let users create a patient, run demographic matching, and trigger an HIE-wide network query with a single action, then receive a webhook when the consolidated bundle is ready. - **AI-generated medical record summaries** — Ship a feature that produces human-readable HTML or PDF medical record summaries on demand, complete with a status endpoint to track generation progress. - **Consolidated FHIR data viewer** — Render active medications, lab results, vitals, allergies, and conditions in your own UI by querying Metriport's consolidated FHIR bundle per patient. - **Care gaps and suspected conditions dashboard** — Build a population health view that lists care gaps and suspected conditions per patient, sourced from FHIR MeasureReports and supporting Observation evidence. - **Bulk patient import with cohort assignment** — Offer CSV-based imports that create patients in bulk, assign them to facilities, and add them to named cohorts for tracking — all in a single guided workflow. - **Embedded clinical viewer via secure tokens** — Generate time-limited embed tokens to drop Metriport's pre-built clinical viewer directly into your dashboard without building document rendering yourself. ## FAQs ### How does authentication work between Truto and Metriport? Your end users connect their Metriport account through Truto's linked account flow. Truto stores and refreshes credentials, so you make normalized API calls without handling Metriport API keys directly. ### How do I receive data updates from Metriport — is it polling or webhooks? Metriport is webhook-driven. You trigger asynchronous operations like network queries, document queries, and consolidated data queries, then Metriport fires a webhook when results are ready. Truto forwards these events to your backend so you don't need to build per-tenant webhook routing. ### What patient data can I actually retrieve? You can retrieve consolidated FHIR R4 bundles (medications, labs, vitals, allergies, conditions), raw and processed clinical documents, AI-generated medical record summaries in HTML or PDF, care gaps, and suspected conditions — all per patient. ### Can I import large patient rosters at once? Yes. Metriport supports bulk patient creation (up to 100,000 patients per request) and bulk updates, which you can call through Truto to seed cohorts or migrate existing patient bases. ### Does Metriport support secure messaging between practitioners? Yes. You can send HIPAA-compliant messages to out-of-network practitioners over the HIE network via the messages endpoint, and retrieve message history per patient context. ### Can I embed Metriport's clinical viewer instead of building my own? Yes. Use the embed token endpoint through Truto to generate secure, time-limited tokens that authenticate users into Metriport's pre-built clinical viewer, embeddable directly in your product UI. ## Related reading - [Connect Metriport to ChatGPT: Manage Patient HIE and Medical Records](https://truto.one/blog/connect-metriport-to-chatgpt-manage-patient-hie-and-medical-records/) — Learn how to connect Metriport to ChatGPT using a managed MCP server. Automate Health Information Exchange (HIE) queries, FHIR data parsing, and patient matching. - [Connect Metriport to Claude: Access Consolidated Clinical Data and Gaps](https://truto.one/blog/connect-metriport-to-claude-access-consolidated-clinical-data-and-gaps/) — Learn how to connect Metriport to Claude using a managed MCP server. Give your AI agents secure access to clinical data, HIE networks, and care gaps. - [Connect Metriport to AI Agents: Automate Patient Sync and Messaging](https://truto.one/blog/connect-metriport-to-ai-agents-automate-patient-sync-and-messaging/) — Learn how to connect Metriport to AI agents using Truto's /tools endpoint. Build autonomous healthcare workflows to match patients, sync HIE data, and manage care gaps.