Quickstart
Follow this guide to start exchanging comprehensive patient medical data.
Overview
Getting started with our Medical API is pretty easy, you’ll just need take the following steps:
- Create a developer account.
- Generate an API key.
- Integrate your app with Metriport.
- Create Facilities and Patients.
- Get Patient Medical Documents.
- Get Patient FHIR Resources. 🔥
- Generate Patient Medical Record Summary. 📄
- Share Medical Data with the Networks. 🏥
- Request API access.
Feel free to check this demo video out before getting started to get a high level overview of the platform:
Let’s get into it! 🤘
1. Create a developer account
Click me to go to the developer dashboard!
This will take you to the Metriport developer dashboard where you can create your Metriport account, if you don't have one already.
2. Generate an API key
After we approve your access request, take the following steps to get your API key:
- Toggle the
Sandbox
switch in the Dashboard navbar to enterSandbox
mode (learn more about this here). - In the left hand menu, click
Developers
. - On the Developers page, you’ll be able to click the “Generate Secret Key” button.
The API key will only be displayed once. Please make sure to save it to a secure location before leaving the page.
This Secret Key will allow you to start making requests to the entire Metriport API on your behalf. Treat this like a password, and keep it somewhere safe! You can read the API Keys page to learn more about API key security best practices.
If you believe your key has been compromised, you can always revoke it and then generate a new one on the Developers page by clicking the trash button beside the key.
3. Integrate your app with Metriport
Note that there are two ways to receive data from Metriport:
- Webhook: Metriport sends patient data to your app when it becomes available:
- your application exposes a webhook (endpoint), which Metriport calls when there’s Patient data available after initiating a query;
- to learn more about how the Webhook flow works, see our Webhooks guide.
- API: Your app requests data from Metriport:
- your application polls Metriport for Patients’ medical data after initiating a query to fetch a Patient’s documents;
We recommend using Webhooks to ensure you’re able to get patient data as quickly and easily as possible.
4. Create Facilities and Patients
For the remainder of the steps, you are able to either use the Dashboard UI, or the API - whatever you prefer!
Pro-tip: you can use our handy SDK on your server if you’re using Node:
Now you can now create Facilities
and Patients
. First,
you’ll need to create your Facilities
.
In Metriport, a Facility
is a location that a Patient
receives some form of treatment. You can
create multiple Facilities
to represent each of your care locations. Note that for telehealth
practices, these can be virtual locations.
1234567893
when creating Facilities.You can create a Facility
by either:
Creating Facilities using the API
See the Create Facility endpoint in our API reference.
Creating Facilities using the Dashboard
- On the
Medical API
page, in the Facilities section, clickAdd
. - Fill in the details and submit the form to add your Facility.
Once you’ve created all of your Facilities
, you can create the Patients
that you treat
each facility. You can create Patients
by either:
Creating Patients using the API
See the Create Patient endpoint in our API reference.
Creating Patients using the Dashboard
- On the
Medical API
page, in the Facilities section, clickPatients
for the Facility under which to add Patients. - In the Patients section, click
Add
. - Fill in the details and submit the form to add your Patient.
When you create a Patient, Metriport automatically links the Patient to all HIE data sources related to the Patient based on the demographic and/or identification information provided when creating the Patient.
In Sandbox mode, you can create Patients with pre-defined patient demographics to simulate a match and pull example clinical data - see our Sandbox guide for more details.
5. Get Patient Medical Documents
Now, you’re able to access your Patients’ medical Documents
. This involves 2 main steps:
- Querying for available
Documents
to get a list of metadata describing the available records. - Downloading the
Document
data from the URL returned in the metadata.
To query for a Patient’s available Documents
, you can either:
Query for Documents using the API
- Start an asynchronous Document Query across HIEs;
- Then, either process the inbound Webhook message which will be sent if you have Webhooks configured, or poll the API to List Documents to get the available document references returned from HIEs.
Query for Documents using the Dashboard
- On the
Medical API
page, in the Facilities section, clickPatients
for the Facility where the Patient is located. - In the desired Patient’s row, click
Documents
. - You’ll see all available Documents in the side panel.
- To update the list of documents from HIEs, click on
Query Documents
.
Once you’ve identified the Document
you want to retrieve, you can download them by either:
Downloading a Document using the API
See the Get Document endpoint in our API reference.
Downloading a Document using the Dashboard
- In the side panel that comes up after clicking
Documents
, simply clickDownload
on the desired Document.
6. Get Patient FHIR Resources 🔥
As we query for Documents we will automatically convert XML C-CDA docs into FHIR resources.
Other Documents, like PDFs and images, will be left in their original format and not processed.
After the conversion from CDA to FHIR, we will store the resulting FHIR resources and make them available to be queried. This will allow you to get the necessary data you might need to better understand and treat your Patients.
To learn more on how to obtain a Patient’s resources, please see the Start Consolidated Data Query endpoint.
We also provide the ability to add any FHIR resources to a Patient with our Create Patient’s Consolidated Data endpoint.
7. Generate Patient Medical Record Summary 📄
The aforementioned FHIR resources are generated from all available C-CDAs for a patient, resulting in a set of unique medical records. To condense all of these records into a single document, refer to the Medical Record Summary guide.
8. Contribute Medical Data with the Networks 🏥
To uphold data quality in the networks, and improve patient health outcomes, it’s required that your organization reciprocates medical data exchange by making net-new patient clinical data available to the networks. Some examples of this include:
- Remote patient monitoring observations such as weight and blood pressure;
- Clinical progress notes from patient encounters;
- Lab results
Metriport makes it easy to contribute this data back with the networks - you can:
- Upload FHIR data using our Create Patient’s Consolidated Data endpoint.
- Upload binary documents using the Upload Document endpoint.
For more details on how to contribute data back, see the Data Contribution guide.
9. Request API access
Access to our Medical API will require you to make requests on behalf of a covered entity with an NPI number for a valid Treatment purpose of use.
To start using the Medical API for production workloads, with real patient data, you can take the following steps to request production API access:
- In the left hand menu, click
Products & Billing
. - Click
Get Started
on the Medical API product. - Press
Book an Intro Call
and select a time and a date to talk to us.
After the call, we will promptly setup your account.
Wrapping up
That’s it! 🤘
You’re now well equiped to use the Metriport API to access, manage, and exchange your Patients’ medical data.
As next steps, we’d recommend scoping out our Medical API Reference in further detail to see the other things you can do with the API.