Quickstart
A quick introduction to building with Vital
1. API keys
Let’s test out running Vital locally by cloning the Quickstart app.
You can get API keys by signing up in the Dashboard.
Once registered, you can create a team. A team is associated with a region (either EU
or US
),
the region dictates where data is stored. You can learn more at regions.
To create a team and get your API keys, you first need to sign up for a Vital account in the Dashboard.
Once registered, you can create a team by hovering over your username at the bottom of the Dashboard sidebar.
A team is associated with a region (either EU
or US
), the region dictates where data is stored.
You can learn more at regions.
To create your API keys, go to the configuration section of the Dashboard. For each region, you’ll have access to two environments Sandbox and Production. We’ll start in the Sandbox environment, so create a new Sandbox API key.
If you get stuck at any point in the Quickstart, help is just a click away! Join our Slack channel or send us a message to support@tryvital.io
Environment | ||
---|---|---|
sandbox | Testing, Connect up to 10 live users | api.sandbox.tryvital.io |
production | Live environment to use with real customers | api.tryvital.io |
2. Running Quickstart locally
Once you have your API keys, it’s time to run the Vital Quickstart locally!
The instructions below will guide you through the process of cloning the Quickstart repository,
customizing the .env
file with your own Vital API_KEY
and finally, building and running the app.
# Note: If on Windows, run
# git clone -c core.symlinks=true https://github.com/tryVital/quickstart
# instead to ensure correct symlink behavior
git clone https://github.com/tryVital/quickstart.git
# Create .env, then fill
# out VITAL_API_KEY, VITAL_REGION (eu, us) and VITAL_ENV in .env
touch .env
# Note: must use python 3
# For virtualenv users:
# virtualenv venv
# source venv/bin/activate
poetry install
# Start the backend app
cd backend/python
source ./start.sh
Open a new shell and start the frontend app. Your app will be running at http://localhost:3000
.
# Install dependencies
cd quickstart/frontend
npm install
# Open .env.local, then fill
# out NEXT_PUBLIC_VITAL_API_KEY, NEXT_PUBLIC_VITAL_ENV and NEXT_PUBLIC_VITAL_REGION
# Start the frontend app
npm run dev
# Go to http://localhost:3000
3. Creating your first User
When retrieving data or connecting devices, Vital will require a user_id
as input.
A user_id
is a unique representation that we hold for a user. It allows you to fetch data for that user.
To create a user, you need to pass an unique id (client_user_id
). This represents the user in your system. Our recommendation is
to store the Vital user_id
in your db against the user row.
Personally identifiable information (PII), such as an email address or phone number, should not be used as input for the user_id
parameter.
Enter a new client_user_id
and tap Create:
This can also be achieved via the API as follows.
4. Connecting a source
A source, at Vital, is a medical device, wearable, or lab. It is a source of information for health data. To connect a source tap the connect button, this will launch the Vital Link Widget for that user.
Once you have entered your credentials and moved to the next screen, you have connected your first source! You can now make API calls to retrieve data for that Source.
How it works
As you might have noticed, you use both a server and a client-side component to access the Vital APIs. A more detailed explanation on how linking works can be found in link flow
The first step is to create a new link_token
by making a /link/token
request and passing in the
required configuration. This link_token
is a short lived, one-time use token that authenticates your
app with Vital Link, our frontend module.
# TEST BACKEND IMPLEMENTATION
from vital.client import Vital
from vital.environment import VitalEnvironment
from vital.client import Vital
from fastapi import FastAPI
from starlette.middleware.cors import CORSMiddleware
client = Vital(
api_key=<YOUR_API_KEY>,
environment=VitalEnvironment.SANDBOX,
timeout=30
)
app = FastAPI()
app.add_middleware( # type: ignore
CORSMiddleware,
allow_origins=["*"],
allow_credentials=True,
allow_methods=["*"],
allow_headers=["*"],
)
@app.get("/token/{user_key}")
def get_token(user_key: str):
return client.link.token(user_id=user_key)
Once you have a link_token
, you can use it to initialize Link
. Link
is a drop-in client-side
module available for web, iOS, and Android that handles the authentication process.
The Quickstart uses Link
on the web, which is a pure JavaScript integration that you trigger via your own client-side code.
import { Button } from "@chakra-ui/react";
import { useState, useCallback } from "react";
import { useVitalLink } from "@tryvital/vital-link";
export const LinkButton: React.FC<{ userID: string | null }> = ({ userID }) => {
const [isLoading, setLoading] = useState(false);
const onSuccess = useCallback((metadata) => {
// Device is now connected.
console.log("onSuccess", metadata);
}, []);
const onExit = useCallback((metadata) => {
// User has quit the link flow.
console.log("onExit", metadata);
}, []);
const onError = useCallback((metadata) => {
// Error encountered in connecting device.
console.log("onError", metadata);
}, []);
const config = {
onSuccess,
onExit,
onError,
env: "sandbox",
region: "us",
};
const { open, ready, error } = useVitalLink(config);
const handleVitalOpen = async () => {
setLoading(true);
const token = await getTokenFromBackend(userID);
open(token.link_token);
setLoading(false);
};
return (
<Button
bg="blue.400"
color="white"
fontSize={"12px"}
px={2}
py={0}
onClick={handleVitalOpen}
isLoading={isLoading || !ready}
isDisabled={userID ? false : true}
>
Connect
</Button>
);
};
This is what your users see to connect their medical device or wearables:
5. Making your first API request
We can now explore what happens when
you press the analyze button in the Quickstart to make an API call.
As an example, we’ll look at the Quickstart’s call to /summary/sleep
, which retrieves sleep
summary data for a user. The request is simple and requires the Vital
user_id
, start_date
and end_date
.
Getting user sleep data
6. SDK’s and Libraries
We offer different SDKs so you can start building your app right away:
vital-python | Python library for calling Vital API on your backend |
vital-link | React Library for initializing link |
vital-node | Vital Node Client |
vital-ios | Vital iOS Client |
Java | Soon to be added |
Go | Soon to be added |
You can also download our API collection or by installing postman first and clicking on the below button.
Next Steps
Congratulations, you have completed the Vital Quickstart!
There are a few directions you can go in now:
Vital Link
A client-side component your users will interact with in order to link their accounts with Vital. It allows you to access their accounts via the Vital API.
Vital SDKs
Native toolkits to integrate Vital into iOS, Android, and Flutter
Vital Webhooks
Webhooks are a way to receive data from Vital. We frequently poll to receive data from the various providers.