Connecting Medplum with Metriport: healthcare API integration

Pamella Bezerra

June 10, 2025

Healthcare data integration remains one of the most challenging aspects of building modern healthcare applications. With patient records scattered across multiple systems, providers, and data networks, creating a unified view of patient information requires robust integration strategies.

This content explores the learnings from building a bi-directional integration between Medplum and Metriport, demonstrating how to aggregate comprehensive medical records and deliver them in a standardized format.

Understanding the integration landscape

What is Metriport?

Metriport is an open-source API platform that provides programmatic access to a patient's comprehensive medical records. It aggregates data from various health data networks, patient portals, and electronic health records (EHRs) across the U.S., delivering everything in a standardized FHIR format.

Metriport offers two primary capabilities:

Patient matching and data aggregation: Retrieve consolidated medical records from multiple data sources
Webhook-based data delivery: Asynchronous delivery of aggregation results to configured webhook URLs

The integration challenge

The task was to create a simple yet robust integration point between Medplum and Metriport. This involved developing a solution capable of both initiating patient data queries from Medplum to Metriport and receiving consolidated patient data back from Metriport for ingestion into Medplum.

The solution led to the development of a two-bot architecture within Medplum to manage both outbound requests and inbound data processing.

Key learnings from the integration

1. Understanding Metriport's webhook architecture

One of the primary discoveries was the critical role of Metriport's webhooks for receiving consolidated data. After initiating a data query for a patient through Metriport's API, the actual data is not returned directly in the API response. Instead, Metriport processes the request asynchronously and pushes the resulting FHIR Bundle to a pre-configured webhook URL.

Why webhooks?

This asynchronous pattern is common in healthcare data exchanges due to several factors:

Large data volumes: Patient records can contain extensive historical data
Data sensitivity: Healthcare data requires careful processing and validation
Aggregation complexity: Collecting data from various sources takes time
Fire-and-forget model: The initial request is processed independently, with webhooks serving as the callback mechanism

Implementation approach

This architecture led to implementing a dedicated Medplum Bot to serve as the webhook endpoint. This bot's sole purpose is to:

Listen for incoming data from Metriport
Process the received FHIR Bundle
Upsert contained resources (Patient, Observation, Condition, etc.) into the Medplum instance

2. Architectural pattern: Two-bot separation of concerns

A two-bot architecture within Medplum effectively managed the bi-directional data flow:

Outbound Bot (Patient Bot)

Trigger: Medplum Patient resource changes
Responsibility: Interact with Metriport's API to initiate actions
Functions: Patient finding, data request initiation
Benefit: Clean separation from inbound webhook processing logic

Inbound Bot (Consolidated Data Webhook)

Trigger: Incoming webhooks from Metriport
Responsibility: Receive and process consolidated patient data
Functions: Authentication, data parsing, resource upsertion
Benefit: Isolated logic for incoming data handling

This separation of concerns (initiation vs. reception) significantly simplifies debugging and enables future enhancements without affecting the entire integration.

3. Data-driven configuration for patient interactions

A crucial learning involved controlling the Patient Bot's behavior through Medplum's FHIR data model. The bot is designed to find existing patients in Metriport based on demographics, but it can also create new patient records when necessary.

Configuration requirements

Patient creation in Metriport isn't automatic—it depends on specific configuration within Medplum resources:

Link Patient to Organization: The Medplum Patient resource must have its managingOrganization field populated, referencing a Medplum Organization resource
Specify Metriport Facility ID: The referenced Organization resource must contain an identifier with the Metriport Facility ID

Conditional logic

If both configurations are present:

The bot creates the patient in Metriport
Then requests consolidated data

If either configuration is missing:

The bot logs a warning with missing information details
Skips patient creation and data querying for that update

This approach demonstrates how Medplum's FHIR data model can effectively drive integration logic.

4. Implementing secure communication

Security was implemented using Medplum's Access Policies and ClientApplications:

Authentication setup

A dedicated ClientApplication is established in Medplum for incoming webhooks
Associated with an Access Policy following the principle of least privilege
Grants only necessary permissions (specific create operations for relevant resource types)
Avoids broad permissions (like wildcard * access)

This approach ensures that webhook authentication is secure while maintaining minimal access scope.

5. Testing and debugging strategies

Effective testing required leveraging Metriport's development environment:

Metriport Sandbox

Safe environment for development and testing
Access to test data for simulating scenarios and API responses
Isolated from production systems

Dashboard testing features

"Save and Test" functionality for webhook configuration
Sends ping messages to webhook URLs
Enables verification of connectivity and message handling
Confirms webhook setup correctness

These tools proved essential for validating the integration before deployment.

Implementation walkthrough

The integration workflow follows these steps:

Patient update triggers: Changes to Medplum Patient resources trigger the Patient Bot
Configuration validation: Bot checks for required organization and facility ID configuration
Metriport interaction: Bot queries Metriport for existing patient or creates new record
Data request: Bot initiates consolidated data aggregation request
Webhook delivery: Metriport asynchronously delivers FHIR Bundle to webhook endpoint
Data processing: Webhook Bot processes and upserts resources into Medplum

Best practices and recommendations

Based on this integration experience, consider these best practices:

Architecture

Separate concerns with dedicated bots for different integration aspects
Use configuration-driven logic through FHIR data models
Implement proper error handling and logging

Security

Follow principle of least privilege for access policies
Use dedicated client applications for webhook authentication
Validate incoming webhook data thoroughly

Testing

Leverage sandbox environments for development
Test webhook connectivity before deployment
Validate data transformation and upsertion logic

Monitoring

Implement comprehensive logging for debugging
Monitor webhook delivery success rates
Track data aggregation completion times

Further resources

Medplum Documentation

Metriport Documentation

Project Implementation

GitHub Issue #6239 - Original integration issue
GitHub Pull Request #6313 - Complete code implementation

Conclusion

Building healthcare data integrations requires careful consideration of security, scalability, and data standards. The Medplum-Metriport integration demonstrates how modern healthcare platforms can work together to provide comprehensive patient data access while maintaining security and compliance requirements.

The two-bot architecture pattern, configuration-driven logic, and webhook-based data delivery create a robust foundation for healthcare data integration that other developers can adapt for their own use cases. By leveraging standardized FHIR formats and well-designed APIs, healthcare applications can break down data silos and provide better patient care through comprehensive medical record access.

‍