Quickstart

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. More information on regions is available here.

For each region, you'll have access to two environments Sandbox and Production. We'll start in the Sandbox environment. View the configuration section of the Dashboard to find your Sandbox API Key.

info

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	https://api.sandbox.tryvital.io
production	Live environment to use with real customers	https://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.

1. Clone quickstart and run locally

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
# 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
cd backend/python

# Copy the .env.example file to .env, then fill
# out VITAL_API_KEY and VITAL_ENV in .env
cp .env.example .env

# Note: must use python 3
# For virtualenv users:
# virtualenv venv
# source venv/bin/activate
poetry install

# Start the backend app
source ./start.sh

Open a new shell and start the frontend app. Your app will be running at http://localhost:3000.

2. Run quickstart frontend

1
2
3
4
5
6
7
8
# Install dependencies
cd quickstart/frontend
npm install

# Start the frontend app
npm 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.

caution

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.

Creating a Vital user

1
2
3
4
5
6
curl --request POST \
     --url https://api.tryvital.io/v2/user/ \
     --header 'Accept: application/json' \
     --header 'Content-Type: application/json' \
     --header 'x-vital-api-key: <your_api_key>' \
     --data '{"client_user_id":"<your_user_id>"}'

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 here

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.

Generating a Link Token

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
# TEST BACKEND IMPLEMENTATION
from http.client import HTTPException
from tracemalloc import start
from typing import Optional
from vital import Client
from fastapi import FastAPI
from starlette.middleware.cors import CORSMiddleware
from pydantic import BaseModel
import os
from dotenv import load_dotenv
load_dotenv()

app = FastAPI()
VITAL_API_KEY = os.getenv("VITAL_API_KEY")
VITAL_ENVIRONMENT = os.getenv("VITAL_ENV")

client = Client(api_key=VITAL_API_KEY, environment=VITAL_ENVIRONMENT)

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.create(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.

Generating a Link Token

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
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

1
2
3
4
5
6
7
8
9
from vital import Client

client = Client(
  api_key=<API_KEY>,
  environment="sandbox",
  region="us"
)

sleep_data = client.Sleep.get(user_id, start_date, end_date)

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 here 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:

1. API keys​

info

2. Running Quickstart locally​

3. Creating your first User​

caution

4. Connecting a source​

How it works​

5. Making your first API request​

6. SDK's and Libraries​

Next Steps​

1. API keys

2. Running Quickstart locally

3. Creating your first User

4. Connecting a source

How it works

5. Making your first API request

6. SDK's and Libraries

Next Steps