Devices API
Overview
Getting started with our Devices 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.
- Link to the Metriport Connect widget in your app.
- Access your users’ health data 🎉🎉🎉
Feel free to follow along with this overview video as well, or just watch it before getting started to get an idea of the expected result:
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.
To demo the app without having to use your production enviroment simply head over to the Developers
page and toggle “sandbox”. This will allow you to try out the Devices API with up to 10 connected users.
2. Generate an API key
Once you’ve created an account and confirmed your email, you’ll be taken to the dashboard home page. From here, take the following steps to get your API key:
- In the left hand menu, click
Products & Billing
. - Click
Get Started
on the Device API product, and add your payment info. - In the left hand menu, click
Developers
. - On the Developers page, you’ll be able to click the
Generate Secret Key
button.
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
There are two ways to receive data from Metriport:
- API: Your app requests data from Metriport:
- your application polls Metriport for user data, for a specific date;
- Webhook: Metriport sends data to your app when it becomes available:
- your application exposes a webhook (endpoint), which Metriport calls when there’s more user data available;
- note that this is the only way to get information from Garmin and Apple Health (you can see what providers support Webhooks here);
- to learn more about how the Webhook flow works, see our Webhooks guide.
3.1 API: setup the Metriport client on your server
The Metriport client is a SDK (library) that’s installed on an application codebase and simplifies calling Metriport’s API.
In the root of your server project, run the following terminal command to install the SDK:
npm install --save @metriport/api
From here, all you need to do is to initialize a Metriport client instance using your API key, and you’re good to start making requests to the Metriport API from your server:
import { MetriportDevicesApi } from "@metriport/api";
const metriportClient = new MetriportDevicesApi("YOUR_API_KEY", options);
options
allows you to set the sandbox
property to access our sandbox environment (optional parameter).
3.2. Webhook: expose an endpoint to be called by Metriport
This allows your application to receive user data as soon as it becomes available, removing the need to poll Metriport’s API at regular intervals.
It’s the only and required way to get information from Garmin.
Head to the webhook page to learn how to setup this integration with Metriport.
4. Link to the Metriport Connect widget in your app
With Metriport, you get a pre-built Connect widget that you can easily plug into your app, so that your users can connect all of their data sources to your application! Here’s a preview:
To hook this up, on your server you’ll just need to create each user in Metriport, and generate a temporary token for each Connect session:
// create user in Metriport and get the Metriport user ID
const metriportUserId = await metriportClient.getMetriportUserId("your-internal-user-id");
// create a session token to be used in the Metriport Connect widget
const connectToken = await metriportClient.getConnectToken(metriportUserId);
As the Metriport user ID is reused for all subsequent data requests, we recommend saving it in your database for future requests.
Then, in your application’s front end, simply link to the Metriport Connect widget and pass in that session token you generated above:
window.open(`https://connect.metriport.com/?token=${connectToken}`);
The token will expire 10 minutes after it is created, and can be reused for the duration of the Connect session.
To open the widget in Sandbox mode, add the parameter &sandbox=true
to the
URL. For example:
`https://connect.metriport.com/?token=${connectToken}&sandbox=true`
Head to the Connect Widget page to learn more about the various Widget customization options, and view some code samples for integrating the Widget on different platforms such as iOS and Android.
5. Access your user’s health data 🎉🎉🎉
That’s it, now you’re ready to start accessing all of your user’s health data from all of the data sources they’ve connected to your app!
API reference
Check out our API reference for example data requests and responses.