Connect a Device

# Junction API
Source: https://docs.junction.com/api-details/junction-api


You use Junction API to:

* manage users, demographics information and device connections in your Team with the [Core API](/api-reference/user/create-user);
* pull ingested device data and inspect backfill progress through the [Data Access API](/api-reference/data/sleep/get-summary);
* order lab tests, manage appointments and pull the results through the [Lab Testing API](/api-reference/lab-testing/create-order); and
* aggregate ingested device data with the [Horizon AI Query API](/api-reference/horizon-ai/aggregation/query-one);

<Info>
  For managing Team configuration and Org resources programmatically, see [Junction Management API](/api-details/junction-management-api).
</Info>

## Environments

Junction provides two Sandbox environments and two Production environments today:

| Environment        | Base URL                              | Team API Key Prefix |
| ------------------ | ------------------------------------- | ------------------- |
| 🇺🇸 Production US | `https://api.tryvital.io/`            | `pk_us_*`           |
| 🇪🇺 Production EU | `https://api.eu.tryvital.io/`         | `pk_eu_*`           |
| 🇺🇸 Sandbox US    | `https://api.sandbox.tryvital.io/`    | `sk_us_*`           |
| 🇪🇺 Sandbox EU    | `https://api.sandbox.eu.tryvital.io/` | `sk_eu_*`           |

Sandbox environments are functionally identical to Production environments, except that:

1. Each Team can have only up to 50 Users in Sandbox;
2. You can create [Synthetic Device connections](/wearables/providers/test_data) connections; and
3. You can [simulate and transition an order through its lifecycle](/lab/overview/sandbox).

## Authentication

Junction API accepts **Team API Key**. You can provision a Team API Key through:

1. the Team Config page in the [Junction Dashboard](https://app.tryvital.io); or
2. the [Create Team API Key](api-reference/org-management/team-api-keys/create-team-api-key) endpoint of the
   [Junction Management API](/api-details/junction-management-api).

Your API requests should present the Team API Key under the `X-Vital-API-Key` header. For example:

```bash cURL
curl --request GET
  --url 'https://api.tryvital.io/v2/providers'
  --header 'X-Vital-API-Key: <YOUR-TEAM-API-KEY>'
```

<Note>
  A [Management Key](/api-details/junction-management-api) used by Junction Management API does not function as Team API Key.
  However, you can manage Team API Keys through a Management Key.
</Note>

## Junction Mobile SDKs

[Junction Mobile SDKs](/wearables/sdks/) supports two authentication methods:

| Scheme                                                              | Authorization         | Recommended use case   |
| ------------------------------------------------------------------- | --------------------- | ---------------------- |
| [Sign-In Token](/wearables/sdks/authentication#vital-sign-in-token) | User-scoped access    | Production mobile apps |
| [Team API Keys](/wearables/sdks/authentication#vital-api-keys)      | Full Team data access | Proof-of-concept       |

Refer to the [Mobile SDK Authentication](/wearables/sdks/authentication) documentation for more information.


# Junction Management API
Source: https://docs.junction.com/api-details/junction-management-api


<Info>
  [Junction Management API](/api-details/junction-management-api) is available for [the Scale plan](https://tryvital.io/pricing).
</Info>

<Tip>
  The base URL of this endpoint is `https://api.tryvital.io/management/`.

  The endpoint accepts only [Management Key](/api-details/junction-management-api#authentication) (`X-Management-Key`).
  Team API Key is not accepted.
</Tip>

You use Junction Management API to:

* manage Junction Org resources, such as [Teams](/api-reference/org-management/team/create-team) and [Members](/api-reference/org-management/member/list-members);
* manage Team configurations across both Sandbox and Production environments, such as:
  * [Team features and brand information](/api-reference/org-management/team/update-team);
  * [Team ETL Pipelines](/api-reference/org-management/team-etl-pipeline/upsert-team-etl-pipelines);
  * [Team Custom Credentials](/api-reference/org-management/team-custom-credentials/upsert-team-custom-credentials); and
  * [Team Continuous Query](/api-reference/horizon-ai/continuous-query/create).

Note that you can access a lot of Junction Management API functionalities through the [Junction Dashboard](https://app.tryvital.io/) as well.

<Info>
  For device and lab testing access, see [Junction API](/api-details/junction-api).
</Info>

## Environments

There is one production environment for Junction Management API:

| Environment   | Base URL                              | Management Key Prefix |
| ------------- | ------------------------------------- | --------------------- |
| 🤖 Production | `https://api.tryvital.io/management/` | `mg_*`                |

## Authentication

Junction Management API accepts **Management Key**. Enterprise customers can request a Management Key
through your Junction Customer Success manager.

Your API requests should present the Management Key under the `X-Management-Key` header. For example:

```bash cURL
curl --request GET
  --url "https://api.tryvital.io/management/v1/org/${ORG_ID}"
  --header 'X-Management-Key: ${YOUR_MANAGEMENT_KEY}'
```

<Note>
  A [Team API Key](/api-details/junction-api#authentication) does not work with Junction Management API.

  Junction enforces the use of separate API credentials based on the principle of least privilege, especially
  considering the administrative power of Junction Management API.
</Note>


# Rate Limiting
Source: https://docs.junction.com/api-details/rate_limiting


Junction does not impose a per-customer rate limit on server-to-server API calls at this time. We adjust the
elastic capacity and overprovisioning rate of our API servers regularly, in response to your usage pattern changes
and product launch plans.

However, when Junction API servers are under stress, there is a possibility in which our infrastructure may abort a number
of your API requests with a **429 Too Many Requests** or **503 Service Unavailable** response.

For idempotent API requests, consider retrying the API request at least once, upon receiving a 429 or 503 response. Optionally,
if you are making the API request in an asynchronous job context, consider having more retry attempts with an
expontential backoff strategy.

## Targeted rate limits

You may encounter **429 Too Many Requests** in the these specific scenarios:

| Endpoint                       | Authentication Scheme | Rate Limit          |
| ------------------------------ | --------------------- | ------------------- |
| `POST /user/refresh/{user_id}` | Vital API Key         | 8 per hour per user |

<Note>
  Junction may adjust rate limiting based on real-world usage patterns. We will give you sufficient notices
  if a new enforcement would impact your existing usage patterns.
</Note>


# Regions
Source: https://docs.junction.com/api-details/regions


Junction Team is a **regional** resource. All data of the Team are stored in the region you selected. This
cannot be changed afterwards. Make sure you choose a region that is suitable to your data residency requirements.

| Regions | Data Residency                                  |
| ------- | ----------------------------------------------- |
| 🇺🇸 US | Data stored in United States (Subject to HIPAA) |
| 🇪🇺 EU | Data stored in Belgium (Subject to GPDR)        |

Your Junction Org is a **global** resource — you can start with a Team in one region and create more in a different
region as you expand.


# Raw
Source: https://docs.junction.com/api-reference/data/activity/get-raw

GET /v2/summary/activity/{user_id}/raw
Get raw activity summary for user_id

<RequestExample>
  ```bash cURL
  curl --request GET \
       --url {{BASE_URL}}/v2/summary/activity/{user_id}/raw \
       --header 'Accept: application/json' \
       --header 'x-vital-api-key: <API_KEY>'
  ```

  ```python Python
  from vital.client import Vital
  from vital.environment import VitalEnvironment

  client = Vital(
    api_key="YOUR_API_KEY",
    environment=VitalEnvironment.SANDBOX
  )

  data = client.activity.get_raw(
      user_id="*",
      start_date="2022-05-01",
      end_date="2022-06-01"
  )
  ```

  ```javascript Node
  import { VitalClient, VitalEnvironment } from '@tryvital/vital-node';
  import { ActivityGetRawRequest } from '@tryvital/vital-node/api/resources/activity';

  const client = new VitalClient({
      apiKey: '<my_api_key>',
      environment: VitalEnvironment.Sandbox,
  });

  const request: ActivityGetRawRequest = {
      startDate: "2022-05-01",
      endDate: "2022-06-01"
  }

  const data = await client.activity.getRaw(
      '<my_user_id>',
      request
  );
  ```

  ```java Java
  import com.vital.api.Vital;
  import com.vital.api.core.Environment;
  import com.vital.api.resources.activity.requests.ActivityGetRawRequest;

  Vital vital = Vital.builder()
          .apiKey("YOUR_API_KEY")
          .environment(Environment.SANDBOX)
          .build();

  ActivityGetRawRequest request = ActivityGetRawRequest.builder()
          .startDate("2022-05-01")
          .endDate("2022-06-01")
          .build();

  var data = vital.activity().getRaw("<my_user_id>", request);
  ```

  ```go Go
  import (
    "context"

    vital "github.com/tryVital/vital-go"
    vitalclient "github.com/tryVital/vital-go/client"
    "github.com/tryVital/vital-go/option"
  )

  client := vitalclient.NewClient(
    option.WithApiKey("<YOUR_API_KEY>"),
    option.WithBaseURL(vital.Environments.Sandbox),
  )

  EndDate := "2022-06-01"
  request := &vital.ActivityGetRawRequest{
    StartDate: "2022-05-01",
    EndDate:   &EndDate,
  }

  response, err := client.Activity.GetRaw(context.TODO(), "*", request)
  if err != nil {
    return err
  }
  fmt.Printf("Received data %s\n", response)
  ```
</RequestExample>


# Summary
Source: https://docs.junction.com/api-reference/data/activity/get-summary

GET /v2/summary/activity/{user_id}
Get activity summary for user_id

<RequestExample>
  ```bash Shell
  curl --request GET \
       --url {{BASE_URL}}/v2/summary/activity/{user_id}/raw \
       --header 'Accept: application/json' \
       --header 'x-vital-api-key: <API_KEY>'
  ```

  ```python Python
  from vital.client import Vital
  from vital.environment import VitalEnvironment

  client = Vital(
    api_key="YOUR_API_KEY",
    environment=VitalEnvironment.SANDBOX
  )

  data = client.activity.get(
      user_id="*",
      start_date="2022-05-01",
      end_date="2022-06-01"
  )
  ```

  ```javascript Node
  import { VitalClient, VitalEnvironment } from '@tryvital/vital-node';
  import { ActivityGetRequest } from '@tryvital/vital-node/api/resources/activity';

  const client = new VitalClient({
      apiKey: '<my_api_key>',
      environment: VitalEnvironment.Sandbox,
  });

  const request: ActivityGetRequest = {
      startDate: "2022-05-01",
      endDate: "2022-06-01"
  }

  const data = await client.activity.get(
      '<my_user_id>',
      request
  );
  ```

  ```java Java
  import com.vital.api.Vital;
  import com.vital.api.core.Environment;
  import com.vital.api.resources.activity.requests.ActivityGetRequest;

  Vital vital = Vital.builder()
                  .apiKey("YOUR_API_KEY")
                  .environment(Environment.SANDBOX)
                  .build();

  ActivityGetRequest request = ActivityGetRequest.builder()
                  .startDate("2022-05-01")
                  .endDate("2022-06-01")
                  .build();

  var data = vital.activity().get("<my_user_id>", request);
  ```

  ```go Go
  import (
    "context"

    vital "github.com/tryVital/vital-go"
    vitalclient "github.com/tryVital/vital-go/client"
    "github.com/tryVital/vital-go/option"
  )

  client := vitalclient.NewClient(
    option.WithApiKey("<YOUR_API_KEY>"),
    option.WithBaseURL(vital.Environments.Sandbox),
  )

  EndDate := "2022-06-01"
  request := &vital.ActivityGetRequest{
    StartDate: "2022-05-01",
    EndDate:   &EndDate,
  }

  response, err := client.Activity.Get(context.TODO(), "*", request)
  if err != nil {
    return err
  }
  fmt.Printf("Received data %s\n", response)
  ```
</RequestExample>


# Raw
Source: https://docs.junction.com/api-reference/data/body/get-raw

GET /v2/summary/body/{user_id}/raw
Get raw Body summary for user_id

<RequestExample>
  ```bash cURL
  curl --request GET \
       --url {{BASE_URL}}/v2/summary/body/{user_id}/raw \
       --header 'Accept: application/json' \
       --header 'x-vital-api-key: <API_KEY>'
  ```

  ```python Python
  from vital.client import Vital
  from vital.environment import VitalEnvironment

  client = Vital(
    api_key="YOUR_API_KEY",
    environment=VitalEnvironment.SANDBOX
  )

  data = client.body.get_raw(
      user_id="*",
      start_date="2022-05-01",
      end_date="2022-06-01"
  )
  ```

  ```javascript Node
  import { VitalClient, VitalEnvironment } from '@tryvital/vital-node';
  import { BodyGetRawRequest } from '@tryvital/vital-node/api/resources/body';

  const client = new VitalClient({
      apiKey: '<my_api_key>',
      environment: VitalEnvironment.Sandbox,
  });

  const request: BodyGetRawRequest = {
      startDate: "2022-05-01",
      endDate: "2022-06-01"
  }

  const data = await client.body.getRaw(
      '<my_user_id>',
      request
  );
  ```

  ```java Java
  import com.vital.api.Vital;
  import com.vital.api.core.Environment;
  import com.vital.api.resources.body.requests.BodyGetRawRequest;

  Vital vital = Vital.builder()
          .apiKey("YOUR_API_KEY")
          .environment(Environment.SANDBOX)
          .build();

  BodyGetRawRequest request = BodyGetRawRequest.builder()
          .startDate("2022-05-01")
          .endDate("2022-06-01")
          .build();

  var data = vital.body().getRaw("<my_user_id>", request);
  ```

  ```go Go
  import (
    "context"

    vital "github.com/tryVital/vital-go"
    vitalclient "github.com/tryVital/vital-go/client"
    "github.com/tryVital/vital-go/option"
  )

  client := vitalclient.NewClient(
    option.WithApiKey("<YOUR_API_KEY>"),
    option.WithBaseURL(vital.Environments.Sandbox),
  )

  EndDate := "2022-06-01"
  request := &vital.BodyGetRawRequest{
    StartDate: "2022-05-01",
    EndDate:   &EndDate,
  }

  response, err := client.Body.GetRaw(context.TODO(), "*", request)
  if err != nil {
    return err
  }
  fmt.Printf("Received data %s\n", response)
  ```
</RequestExample>


# Summary
Source: https://docs.junction.com/api-reference/data/body/get-summary

GET /v2/summary/body/{user_id}
Get Body summary for user_id

<RequestExample>
  ```bash cURL
  curl --request GET \
       --url {{BASE_URL}}/v2/summary/body/{user_id} \
       --header 'Accept: application/json' \
       --header 'x-vital-api-key: <API_KEY>'
  ```

  ```python Python
  from vital.client import Vital
  from vital.environment import VitalEnvironment

  client = Vital(
    api_key="YOUR_API_KEY",
    environment=VitalEnvironment.SANDBOX
  )

  data = client.body.get(
      user_id="*",
      start_date="2022-05-01",
      end_date="2022-06-01"
  )
  ```

  ```javascript Node
  import { VitalClient, VitalEnvironment } from '@tryvital/vital-node';
  import { BodyGetRequest } from '@tryvital/vital-node/api/resources/body';

  const client = new VitalClient({
      apiKey: '<my_api_key>',
      environment: VitalEnvironment.Sandbox,
  });

  const request: BodyGetRequest = {
      startDate: "2022-05-01",
      endDate: "2022-06-01"
  }

  const data = await client.body.get(
      '<my_user_id>',
      request
  );
  ```

  ```java Java
  import com.vital.api.Vital;
  import com.vital.api.core.Environment;
  import com.vital.api.resources.body.requests.BodyGetRequest;

  Vital vital = Vital.builder()
          .apiKey("YOUR_API_KEY")
          .environment(Environment.SANDBOX)
          .build();

  BodyGetRequest request = BodyGetRequest.builder()
          .startDate("2022-05-01")
          .endDate("2022-06-01")
          .build();

  var data = vital.body().get("<my_user_id>", request);
  ```

  ```go Go
  import (
    "context"

    vital "github.com/tryVital/vital-go"
    vitalclient "github.com/tryVital/vital-go/client"
    "github.com/tryVital/vital-go/option"
  )

  client := vitalclient.NewClient(
    option.WithApiKey("<YOUR_API_KEY>"),
    option.WithBaseURL(vital.Environments.Sandbox),
  )

  EndDate := "2022-06-01"
  request := &vital.BodyGetRequest{
    StartDate: "2022-05-01",
    EndDate:   &EndDate,
  }

  response, err := client.Body.Get(context.TODO(), "*", request)
  if err != nil {
    return err
  }
  fmt.Printf("Received data %s\n", response)
  ```
</RequestExample>


# Get User Device
Source: https://docs.junction.com/api-reference/data/device/get-device

GET /v2/user/{user_id}/device/{device_id}

<RequestExample>
  ```bash Shell
  curl --request GET \
       --url {{BASE_URL}}/v2/user/{user_id}/device/{device_id} \
       --header 'Accept: application/json' \
       --header 'x-vital-api-key: <API_KEY>'
  ```

  ```python Python
  from vital.client import Vital
  from vital.environment import VitalEnvironment

  client = Vital(
    api_key="YOUR_API_KEY",
    environment=VitalEnvironment.SANDBOX
  )

  data = client.user.get_devices(
      user_id="<user_id>", device_id="<device_id>"
  )
  ```

  ```javascript Node
  import { VitalClient, VitalEnvironment } from '@tryvital/vital-node';

  const client = new VitalClient({
      apiKey: '<my_api_key>',
      environment: VitalEnvironment.Sandbox,
  });

  const data = await client.user.getDevices(
      '<user_id>', '<device_id>'
  );
  ```

  ```java Java
  import com.vital.api.Vital;
  import com.vital.api.core.Environment;

  Vital vital = Vital.builder()
                  .apiKey("YOUR_API_KEY")
                  .environment(Environment.SANDBOX)
                  .build();

  var data = vital.user().getDevices("<user_id>", "<device_id>");
  ```

  ```go Go
  import (
    "context"

    vital "github.com/tryVital/vital-go"
    vitalclient "github.com/tryVital/vital-go/client"
    "github.com/tryVital/vital-go/option"
  )

  client := vitalclient.NewClient(
    option.WithApiKey("<YOUR_API_KEY>"),
    option.WithBaseURL(vital.Environments.Sandbox),
  )

  response, err := client.User.GetDevices(context.TODO(), "<user_id>", "<device_id>")
  if err != nil {
    return err
  }
  fmt.Printf("Received data %s\n", response)
  ```
</RequestExample>


# Get User Devices
Source: https://docs.junction.com/api-reference/data/device/get-devices

GET /v2/user/{user_id}/device

<RequestExample>
  ```bash Shell
  curl --request GET \
       --url {{BASE_URL}}/v2/user/{user_id}/device \
       --header 'Accept: application/json' \
       --header 'x-vital-api-key: <API_KEY>'
  ```

  ```python Python
  from vital.client import Vital
  from vital.environment import VitalEnvironment

  client = Vital(
    api_key="YOUR_API_KEY",
    environment=VitalEnvironment.SANDBOX
  )

  data = client.user.get_devices(
      user_id="<user_id>"
  )
  ```

  ```javascript Node
  import { VitalClient, VitalEnvironment } from '@tryvital/vital-node';

  const client = new VitalClient({
      apiKey: '<my_api_key>',
      environment: VitalEnvironment.Sandbox,
  });

  const data = await client.user.getDevices(
      '<user_id>'
  );
  ```

  ```java Java
  import com.vital.api.Vital;
  import com.vital.api.core.Environment;

  Vital vital = Vital.builder()
                  .apiKey("YOUR_API_KEY")
                  .environment(Environment.SANDBOX)
                  .build();

  var data = vital.user().getDevices("<user_id>");
  ```

  ```go Go
  import (
    "context"

    vital "github.com/tryVital/vital-go"
    vitalclient "github.com/tryVital/vital-go/client"
    "github.com/tryVital/vital-go/option"
  )

  client := vitalclient.NewClient(
    option.WithApiKey("<YOUR_API_KEY>"),
    option.WithBaseURL(vital.Environments.Sandbox),
  )

  response, err := client.User.GetDevices(context.TODO(), "user_id")
  if err != nil {
    return err
  }
  fmt.Printf("Received data %s\n", response)
  ```
</RequestExample>


# Summary
Source: https://docs.junction.com/api-reference/data/electrocardiogram/get-summary

GET /v2/summary/electrocardiogram/{user_id}
Get electrocardiogram summary for user_id

<Note>
  The Electrocardiogram summary type does not embed the voltage measurements.

  Use the [Get Electrocardiogram Voltage](/api-reference/data/timeseries/electrocardiogram-voltage) endpoint
  with the `session_start` and `session-end` timestamps to query the voltage measurements.
</Note>

<RequestExample>
  ```bash Shell
  curl --request GET \
       --url {{BASE_URL}}/v2/summary/electrocardiogram/{user_id} \
       --header 'Accept: application/json' \
       --header 'x-vital-api-key: <API_KEY>'
  ```

  ```python Python
  from vital.client import Vital
  from vital.environment import VitalEnvironment

  client = Vital(
    api_key="YOUR_API_KEY",
    environment=VitalEnvironment.SANDBOX
  )

  data = client.electrocardiogram.get(
      user_id="*",
      start_date="2022-05-01",
      end_date="2022-06-01"
  )
  ```

  ```javascript Node
  import { VitalClient, VitalEnvironment } from '@tryvital/vital-node';
  import { ElectrocardiogramGetRequest } from '@tryvital/vital-node/api/resources/electrocardiogram';

  const client = new VitalClient({
      apiKey: '<my_api_key>',
      environment: VitalEnvironment.Sandbox,
  });

  const request: ElectrocardiogramGetRequest = {
      startDate: "2022-05-01",
      endDate: "2022-06-01"
  }

  const data = await client.electrocardiogram.get(
      '<my_user_id>',
      request
  );
  ```

  ```java Java
  import com.vital.api.Vital;
  import com.vital.api.core.Environment;
  import com.vital.api.resources.electrocardiogram.requests.ElectrocardiogramGetRequest;

  Vital vital = Vital.builder()
                  .apiKey("YOUR_API_KEY")
                  .environment(Environment.SANDBOX)
                  .build();

  ElectrocardiogramGetRequest request = ElectrocardiogramGetRequest.builder()
                  .startDate("2022-05-01")
                  .endDate("2022-06-01")
                  .build();

  var data = vital.electrocardiogram().get("<my_user_id>", request);
  ```

  ```go Go
  import (
    "context"

    vital "github.com/tryVital/vital-go"
    vitalclient "github.com/tryVital/vital-go/client"
    "github.com/tryVital/vital-go/option"
  )

  client := vitalclient.NewClient(
    option.WithApiKey("<YOUR_API_KEY>"),
    option.WithBaseURL(vital.Environments.Sandbox),
  )

  EndDate := "2022-06-01"
  request := &vital.ElectrocardiogramGetRequest{
    StartDate: "2022-05-01",
    EndDate:   &EndDate,
  }

  response, err := client.Electrocardiogram.Get(context.TODO(), "*", request)
  if err != nil {
    return err
  }
  fmt.Printf("Received data %s\n", response)
  ```
</RequestExample>


# Introspect Historical Pulls
Source: https://docs.junction.com/api-reference/data/introspection/historical-pulls

GET /v2/introspect/historical_pull

## Overview

Diagnose user historical data unavailability through the User Resources Introspection API.

This API offers detailed insights into all provider connections and collected historical resources of all users in your team,
empowering you to perform an initial diagnosis of any user connection issue with ease.

<Warning>
  Please note that `user_limit` is an upper bound and the endpoint can return data for fewer users.
  This would be the case if any of the top selected users had no available resource information.
</Warning>


# Introspect Resources
Source: https://docs.junction.com/api-reference/data/introspection/user-resources

GET /v2/introspect/resources

## Overview

Diagnose user data unavailability through the User Resources Introspection API.

This API offers detailed insights into all provider connections and collected resources of all users in your team, empowering you to perform an initial diagnosis of any user connection issue with ease.

<Warning>
  Please note that `user_limit` is an upper bound and the endpoint can return data for fewer users.
  This would be the case if any of the top selected users had no available resource information.
</Warning>


# Summary
Source: https://docs.junction.com/api-reference/data/meal/get-summary

GET /v2/summary/meal/{user_id}
Get user's meals

<RequestExample>
  ```bash cURL
  curl --request GET \
       --url {{BASE_URL}}/v2/summary/meal/{user_id}?start_date={{START_DATE}}&end_date={{END_DATE}} \
       --header 'Accept: application/json' \
       --header 'x-vital-api-key: <API_KEY>'
  ```

  ```python Python
  from vital.client import Vital
  from vital.environment import VitalEnvironment

  client = Vital(
    api_key="YOUR_API_KEY",
    environment=VitalEnvironment.SANDBOX
  )

  data = client.meal.get(
    user_id="<user_id>", 
    start_date="2021-01-01", 
    end_date="2021-01-02"
  )
  ```

  ```javascript Node
  import { VitalClient, VitalEnvironment } from '@tryvital/vital-node';
  import { MealGetRequest } from '@tryvital/vital-node/api';

  const client = new VitalClient({
      apiKey: '<my_api_key>',
      environment: VitalEnvironment.Sandbox,
  });

  const request: MealGetRequest = {
      startDate: '2021-01-01',
      endDate: '2021-01-02',
  };

  const data = await client.meal.get('user_id', request);
  ```

  ```java Java
  import com.vital.api.Vital;
  import com.vital.api.core.Environment;
  import com.vital.api.resources.meal.requests.MealGetRequest;

  Vital vital = Vital.builder()
          .apiKey("YOUR_API_KEY")
          .environment(Environment.SANDBOX)
          .build();

  MealGetRequest request = MealGetRequest
          .builder()
          .startDate("2021-01-01")
          .endDate("2021-01-02")
          .build();

  var data = vital.meal().get("<user_id>", request);
  ```

  ```go Go
  import (
    "context"

    vital "github.com/tryVital/vital-go"
    vitalclient "github.com/tryVital/vital-go/client"
    "github.com/tryVital/vital-go/option"
  )

  EndDate := "2021-01-02"
  request := &vital.MealGetRequest{
    StartDate: "2021-01-01",
    EndDate:   &EndDate,
  }

  response, err := client.Meal.Get(
    context.TODO(), 
    "<user_id>", 
    request
  )
  if err != nil {
    return err
  }
  fmt.Printf("Received data %s\n", response)
  ```
</RequestExample>


# Summary
Source: https://docs.junction.com/api-reference/data/menstrual-cycle/get-summary

GET /v2/summary/menstrual_cycle/{user_id}

<RequestExample>
  ```bash Shell
  curl --request GET \
       --url {{BASE_URL}}/v2/summary/menstrual_cycle/{user_id} \
       --header 'Accept: application/json' \
       --header 'x-vital-api-key: <API_KEY>'
  ```

  ```python Python
  from vital.client import Vital
  from vital.environment import VitalEnvironment

  client = Vital(
    api_key="YOUR_API_KEY",
    environment=VitalEnvironment.SANDBOX
  )

  data = client.menstrual_cycle.get(
      user_id="*",
      start_date="2022-05-01",
      end_date="2022-06-01"
  )
  ```

  ```javascript Node
  import { VitalClient, VitalEnvironment } from '@tryvital/vital-node';
  import { MenstrualCycleGetRequest } from '@tryvital/vital-node/api/resources/menstrualCycle';

  const client = new VitalClient({
      apiKey: '<my_api_key>',
      environment: VitalEnvironment.Sandbox,
  });

  const request: MenstrualCycleGetRequest = {
      startDate: "2022-05-01",
      endDate: "2022-06-01"
  }

  const data = await client.menstrualCycle.get(
      '<my_user_id>',
      request
  );
  ```

  ```java Java
  import com.vital.api.Vital;
  import com.vital.api.core.Environment;
  import com.vital.api.resources.menstrualCycle.requests.MenstrualCycleGetRequest;

  Vital vital = Vital.builder()
                  .apiKey("YOUR_API_KEY")
                  .environment(Environment.SANDBOX)
                  .build();

  MenstrualCycleGetRequest request = MenstrualCycleGetRequest.builder()
                  .startDate("2022-05-01")
                  .endDate("2022-06-01")
                  .build();

  var data = vital.menstrualCycle().get("<my_user_id>", request);
  ```

  ```go Go
  import (
    "context"

    vital "github.com/tryVital/vital-go"
    vitalclient "github.com/tryVital/vital-go/client"
    "github.com/tryVital/vital-go/option"
  )

  client := vitalclient.NewClient(
    option.WithApiKey("<YOUR_API_KEY>"),
    option.WithBaseURL(vital.Environments.Sandbox),
  )

  EndDate := "2022-06-01"
  request := &vital.MenstrualCycleGetRequest{
    StartDate: "2022-05-01",
    EndDate:   &EndDate,
  }

  response, err := client.MenstrualCycle.Get(context.TODO(), "*", request)
  if err != nil {
    return err
  }
  fmt.Printf("Received data %s\n", response)
  ```
</RequestExample>


# Raw
Source: https://docs.junction.com/api-reference/data/profile/get-raw

GET /v2/summary/profile/{user_id}/raw
Get raw profile for user_id

## Parameters

<RequestExample>
  ```bash cURL
  curl --request GET \
       --url {{BASE_URL}}/v2/summary/profile/{user_id}/raw \
       --header 'Accept: application/json' \
       --header 'x-vital-api-key: <API_KEY>'
  ```

  ```python Python
  from vital.client import Vital
  from vital.environment import VitalEnvironment

  client = Vital(
    api_key="YOUR_API_KEY",
    environment=VitalEnvironment.SANDBOX
  )

  data = client.profile.get_raw("<user_id>")
  ```

  ```javascript Node
  import { VitalClient, VitalEnvironment } from '@tryvital/vital-node';

  const client = new VitalClient({
      apiKey: '<my_api_key>',
      environment: VitalEnvironment.Sandbox,
  });

  const data = await client.profile.getRaw('<user_id>')
  ```

  ```java Java
  import com.vital.api.Vital;
  import com.vital.api.core.Environment;

  Vital vital = Vital.builder()
          .apiKey("YOUR_API_KEY")
          .environment(Environment.SANDBOX)
          .build();

  var data = vital.profile().getRaw("<user_id>");
  ```

  ```go Go
  import (
    "context"

    vital "github.com/tryVital/vital-go"
    vitalclient "github.com/tryVital/vital-go/client"
    "github.com/tryVital/vital-go/option"
  )

  client := vitalclient.NewClient(
    option.WithApiKey("<YOUR_API_KEY>"),
    option.WithBaseURL(vital.Environments.Sandbox),
  )

  response, err := client.Profile.GetRaw(context.TODO(), "<user_id>")
  if err != nil {
    return err
  }
  fmt.Printf("Received data %s\n", response)
  ```
</RequestExample>


# Summary
Source: https://docs.junction.com/api-reference/data/profile/get-summary

GET /v2/summary/profile/{user_id}
Get profile for user_id

<RequestExample>
  ```bash cURL
  curl --request GET \
       --url {{BASE_URL}}/v2/summary/profile/{user_id} \
       --header 'Accept: application/json' \
       --header 'x-vital-api-key: <API_KEY>'
  ```

  ```python Python
  from vital.client import Vital
  from vital.environment import VitalEnvironment

  client = Vital(
    api_key="YOUR_API_KEY",
    environment=VitalEnvironment.SANDBOX
  )

  data = client.profile.get("<user_id>")
  ```

  ```javascript Node
  import { VitalClient, VitalEnvironment } from '@tryvital/vital-node';

  const client = new VitalClient({
      apiKey: '<my_api_key>',
      environment: VitalEnvironment.Sandbox,
  });

  const data = await client.profile.get('<user_id>')
  ```

  ```java Java
  import com.vital.api.Vital;
  import com.vital.api.core.Environment;

  Vital vital = Vital.builder()
          .apiKey("YOUR_API_KEY")
          .environment(Environment.SANDBOX)
          .build();

  var data = vital.profile().get("<user_id>");
  ```

  ```go Go
  import (
    "context"

    vital "github.com/tryVital/vital-go"
    vitalclient "github.com/tryVital/vital-go/client"
    "github.com/tryVital/vital-go/option"
  )

  client := vitalclient.NewClient(
    option.WithApiKey("<YOUR_API_KEY>"),
    option.WithBaseURL(vital.Environments.Sandbox),
  )

  response, err := client.Profile.Get(context.TODO(), "<user_id>")
  if err != nil {
    return err
  }
  fmt.Printf("Received data %s\n", response)
  ```
</RequestExample>


# Summary
Source: https://docs.junction.com/api-reference/data/sleep-cycle/get-summary

GET /v2/summary/sleep_cycle/{user_id}
Get sleep cycle for user_id

<RequestExample>
  ```bash cURL
  curl --request GET \
       --url {{BASE_URL}}/v2/summary/sleep_cycle/{user_id}?start_date={{START_DATE}}&end_date={{END_DATE}} \
       --header 'Accept: application/json' \
       --header 'x-vital-api-key: <API_KEY>'
  ```

  ```python Python
  from vital.client import Vital
  from vital.environment import VitalEnvironment

  client = Vital(
    api_key="YOUR_API_KEY",
    environment=VitalEnvironment.SANDBOX
  )

  data = client.sleep_cycle.get(
    user_id="<user_id>", 
    start_date="2021-01-01", 
    end_date="2021-01-02"
  )
  ```

  ```javascript Node
  import { VitalClient, VitalEnvironment } from '@tryvital/vital-node';
  import { SleepCycleGetRequest } from '@tryvital/vital-node/api';

  const client = new VitalClient({
      apiKey: '<my_api_key>',
      environment: VitalEnvironment.Sandbox,
  });

  const request: SleepCycleGetRequest = {
      startDate: '2021-01-01',
      endDate: '2021-01-02',
  }

  const data = await client.sleepCycle.get('user_id', request)
  ```

  ```java Java
  import com.vital.api.Vital;
  import com.vital.api.core.Environment;
  import com.vital.api.resources.sleep_cycle.requests.SleepCycleGetRequest;

  Vital vital = Vital.builder()
          .apiKey("YOUR_API_KEY")
          .environment(Environment.SANDBOX)
          .build();

  SleepCycleGetRequest request = SleepCycleGetRequest
          .builder()
          .startDate("2021-01-01")
          .endDate("2021-01-02")
          .build();

  var data = vital.sleepCycle().get("<user_id>", request);
  ```

  ```go Go
  import (
    "context"

    vital "github.com/tryVital/vital-go"
    vitalclient "github.com/tryVital/vital-go/client"
    "github.com/tryVital/vital-go/option"
  )

  EndDate := "2021-01-02"
  request := &vital.SleepCycleGetRequest{
    StartDate: "2021-01-01",
    EndDate:   &EndDate,
  }

  response, err := client.SleepCycle.Get(
    context.TODO(), 
    "<user_id>", 
    request
  )
  if err != nil {
    return err
  }
  fmt.Printf("Received data %s\n", response)
  ```
</RequestExample>


# Raw
Source: https://docs.junction.com/api-reference/data/sleep/get-raw

GET /v2/summary/sleep/{user_id}/raw
Get raw sleep summary for user_id

<RequestExample>
  ```bash cURL
  curl --request GET \
       --url {{BASE_URL}}/v2/summary/sleep/{user_id}/raw \
       --header 'Accept: application/json' \
       --header 'x-vital-api-key: <API_KEY>'
  ```

  ```python Python
  from vital.client import Vital
  from vital.environment import VitalEnvironment

  client = Vital(
    api_key="YOUR_API_KEY",
    environment=VitalEnvironment.SANDBOX
  )

  data = client.sleep.get_raw(
      user_id="*",
      start_date="2021-01-01",
      end_date="2021-01-02"
  )
  ```

  ```javascript Node
  import { VitalClient, VitalEnvironment } from '@tryvital/vital-node';
  import { SleepGetRawRequest } from '@tryvital/vital-node/api/resources/sleep';

  const client = new VitalClient({
      apiKey: '<my_api_key>',
      environment: VitalEnvironment.Sandbox,
  });

  const request: SleepGetRawRequest = {
      startDate: '2021-01-01',
      endDate: '2021-01-02',
  }

  const data = await client.sleep.getRaw("<user_id>", request)
  ```

  ```java Java
  import com.vital.api.Vital;
  import com.vital.api.core.Environment;
  import com.vital.api.resources.sleep.requests.SleepGetRawRequest;

  Vital vital = Vital.builder()
          .apiKey("YOUR_API_KEY")
          .environment(Environment.SANDBOX)
          .build();

  SleepGetRawRequest request = SleepGetRawRequest
          .builder()
          .startDate("2021-01-01")
          .endDate("2021-01-02")
          .build();

  var data = vital.sleep().getRaw("<user_id>", request);
  ```

  ```go Go
  import (
    "context"

    vital "github.com/tryVital/vital-go"
    vitalclient "github.com/tryVital/vital-go/client"
    "github.com/tryVital/vital-go/option"
  )

  client := vitalclient.NewClient(
    option.WithApiKey("<YOUR_API_KEY>"),
    option.WithBaseURL(vital.Environments.Sandbox),
  )

  EndDate := "2022-06-01"
  request := &vital.SleepGetRawRequest{
    StartDate: "2022-05-01",
    EndDate:   &EndDate,
  }

  response, err := client.Sleep.GetRaw(context.TODO(), "<user_id>", request)
  if err != nil {
    return err
  }
  fmt.Printf("Received data %s\n", response)
  ```
</RequestExample>


# Summary
Source: https://docs.junction.com/api-reference/data/sleep/get-summary

GET /v2/summary/sleep/{user_id}
Get sleep summary for user_id

<RequestExample>
  ```bash cURL
  curl --request GET \
       --url {{BASE_URL}}/v2/summary/sleep/{user_id}?start_date={{START_DATE}}&end_date={{END_DATE}} \
       --header 'Accept: application/json' \
       --header 'x-vital-api-key: <API_KEY>'
  ```

  ```python Python
  from vital.client import Vital
  from vital.environment import VitalEnvironment

  client = Vital(
    api_key="YOUR_API_KEY",
    environment=VitalEnvironment.SANDBOX
  )

  data = client.sleep.get(
    user_id="<user_id>", 
    start_date="2021-01-01", 
    end_date="2021-01-02"
  )
  ```

  ```javascript Node
  import { VitalClient, VitalEnvironment } from '@tryvital/vital-node';
  import { SleepGetRequest } from '@tryvital/vital-node/api';

  const client = new VitalClient({
      apiKey: '<my_api_key>',
      environment: VitalEnvironment.Sandbox,
  });

  const request: SleepGetRequest = {
      startDate: '2021-01-01',
      endDate: '2021-01-02',
  }

  const data = await client.sleep.get('user_id', request)
  ```

  ```java Java
  import com.vital.api.Vital;
  import com.vital.api.core.Environment;
  import com.vital.api.resources.sleep.requests.SleepGetRequest;

  Vital vital = Vital.builder()
          .apiKey("YOUR_API_KEY")
          .environment(Environment.SANDBOX)
          .build();

  SleepGetRequest request = SleepGetRequest
          .builder()
          .startDate("2021-01-01")
          .endDate("2021-01-02")
          .build();

  var data = vital.sleep().get("<user_id>", request);
  ```

  ```go Go
  import (
    "context"

    vital "github.com/tryVital/vital-go"
    vitalclient "github.com/tryVital/vital-go/client"
    "github.com/tryVital/vital-go/option"
  )

  EndDate := "2021-01-02"
  request := &vital.SleepGetRequest{
    StartDate: "2021-01-01",
    EndDate:   &EndDate,
  }

  response, err := client.Sleep.Get(
    context.TODO(), 
    "<user_id>", 
    request
  )
  if err != nil {
    return err
  }
  fmt.Printf("Received data %s\n", response)
  ```
</RequestExample>


# Afib Burden
Source: https://docs.junction.com/api-reference/data/timeseries/afib-burden

GET /v2/timeseries/{user_id}/afib_burden/grouped

<Card title="View Full Response Schema »" icon="diamond-turn-right" iconType="sharp-solid" color="#F3A712" href="https://api.tryvital.io/redoc#tag/timeseries/operation/get_afib_burden_grouped">
  The Response section on the page still needs work. Click here to check out the complete schema.
</Card>

<RequestExample>
  ```bash cURL
  curl --request GET \
       --url {{BASE_URL}}/v2/timeseries/{user_id}/afib_burden/grouped?start_date={{START_DATE}}&end_date={{END_DATE}} \
       --header 'Accept: application/json' \
       --header 'x-vital-api-key: <API_KEY>'
  ```

  ```python Python
  from vital.client import Vital
  from vital.environment import VitalEnvironment

  client = Vital(
    api_key="YOUR_API_KEY",
    environment=VitalEnvironment.SANDBOX
  )

  data = client.vitals.afib_burden_grouped(
    user_id="<user_id>", 
    start_date="2021-10-01", 
    end_date="2021-10-02"
  )
  ```

  ```javascript Node
  import { VitalClient, VitalEnvironment } from '@tryvital/vital-node';
  import { VitalsAfibBurdenGroupedRequest } from '@tryvital/vital-node/api/resources/vitals';

  const client = new VitalClient({
      apiKey: '<my_api_key>',
      environment: VitalEnvironment.Sandbox,
  });

  const request: VitalsAfibBurdenGroupedRequest = {
      startDate: "2022-05-01",
      endDate: "2022-06-01"
  }

  const data = await client.vitals.afibBurdenGrouped(
      '<my_user_id>',
      request
  );
  ```

  ```java Java
  import com.vital.api.Vital;
  import com.vital.api.core.Environment;
  import com.vital.api.resources.vitals.requests.VitalsAfibBurdenGroupedRequest;

  Vital vital = Vital.builder()
          .apiKey("YOUR_API_KEY")
          .environment(Environment.SANDBOX)
          .build();

  VitalsAfibBurdenGroupedRequest request = VitalsAfibBurdenGroupedRequest.builder()
          .startDate("2022-05-01")
          .endDate("2022-06-01")
          .build();

  var data = vital.vitals().afibBurdenGrouped("<user_id>", request);
  ```

  ```go Go
  import (
    "context"

    vital "github.com/tryVital/vital-go"
    vitalclient "github.com/tryVital/vital-go/client"
  )

  client := vitalclient.NewClient(
    vitalclient.WithApiKey("<YOUR_API_KEY>"),
    vitalclient.WithBaseURL(vital.Environments.Sandbox),
  )

  EndDate := "2022-06-01"
  request := &vital.VitalsAfibBurdenGroupedRequest{
    StartDate: "2022-05-01",
    EndDate:   &EndDate,
  }

  response, err := client.Vitals.AfibBurdenGrouped(context.TODO(), "*", request)
  if err != nil {
    return err
  }
  fmt.Printf("Received data %s\n", response)
  ```
</RequestExample>

<ResponseExample>
  ```json Example
  {
    "groups": {
      "oura": [
        {
          "data": [
            {
              "end": "2023-02-13T14:30:52+00:00",
              "start": "2023-02-13T14:30:52+00:00",
              "unit": "%",
              "value": 3
            }
          ],
          "source": {
            "provider": "oura",
            "type": "ring"
          }
        }
      ]
    }
  }
  ```
</ResponseExample>


# Basal Body Temperature
Source: https://docs.junction.com/api-reference/data/timeseries/basal-body-temperature

GET /v2/timeseries/{user_id}/basal_body_temperature/grouped

<Card title="View Full Response Schema »" icon="diamond-turn-right" iconType="sharp-solid" color="#F3A712" href="https://api.tryvital.io/redoc#tag/timeseries/operation/get_basal_body_temperature_grouped">
  The Response section on the page still needs work. Click here to check out the complete schema.
</Card>

<RequestExample>
  ```bash cURL
  curl --request GET \
       --url {{BASE_URL}}/v2/timeseries/{user_id}/basal_body_temperature/grouped?start_date={{START_DATE}}&end_date={{END_DATE}} \
       --header 'Accept: application/json' \
       --header 'x-vital-api-key: <API_KEY>'
  ```

  ```python Python
  from vital.client import Vital
  from vital.environment import VitalEnvironment

  client = Vital(
    api_key="YOUR_API_KEY",
    environment=VitalEnvironment.SANDBOX
  )

  data = client.vitals.basal_body_temperature_grouped(
    user_id="<user_id>", 
    start_date="2021-10-01", 
    end_date="2021-10-02"
  )
  ```

  ```javascript Node
  import { VitalClient, VitalEnvironment } from '@tryvital/vital-node';
  import { VitalsBasalBodyTemperatureGroupedRequest } from '@tryvital/vital-node/api/resources/vitals';

  const client = new VitalClient({
      apiKey: '<my_api_key>',
      environment: VitalEnvironment.Sandbox,
  });

  const request: VitalsBasalBodyTemperatureGroupedRequest = {
      startDate: "2022-05-01",
      endDate: "2022-06-01"
  }

  const data = await client.vitals.basalBodyTemperatureGrouped(
      '<my_user_id>',
      request
  );
  ```

  ```java Java
  import com.vital.api.Vital;
  import com.vital.api.core.Environment;
  import com.vital.api.resources.vitals.requests.VitalsBasalBodyTemperatureGroupedRequest;

  Vital vital = Vital.builder()
          .apiKey("YOUR_API_KEY")
          .environment(Environment.SANDBOX)
          .build();

  VitalsBasalBodyTemperatureGroupedRequest request = VitalsBasalBodyTemperatureGroupedRequest.builder()
          .startDate("2022-05-01")
          .endDate("2022-06-01")
          .build();

  var data = vital.vitals().basalBodyTemperatureGrouped("<user_id>", request);
  ```

  ```go Go
  import (
    "context"

    vital "github.com/tryVital/vital-go"
    vitalclient "github.com/tryVital/vital-go/client"
  )

  client := vitalclient.NewClient(
    vitalclient.WithApiKey("<YOUR_API_KEY>"),
    vitalclient.WithBaseURL(vital.Environments.Sandbox),
  )

  EndDate := "2022-06-01"
  request := &vital.VitalsBasalBodyTemperatureGroupedRequest{
    StartDate: "2022-05-01",
    EndDate:   &EndDate,
  }

  response, err := client.Vitals.BasalBodyTemperatureGrouped(context.TODO(), "*", request)
  if err != nil {
    return err
  }
  fmt.Printf("Received data %s\n", response)
  ```
</RequestExample>

<ResponseExample>
  ```json Example
  {
    "groups": {
      "oura": [
        {
          "data": [
            {
              "end": "2023-02-13T14:57:24+00:00",
              "start": "2023-02-13T14:30:52+00:00",
              "timestamp": "2023-02-13T14:30:52+00:00",
              "unit": "\u00b0C",
              "value": 36.7
            }
          ],
          "source": {
            "provider": "oura",
            "type": "ring"
          }
        }
      ]
    }
  }
  ```
</ResponseExample>


# Blood Oxygen
Source: https://docs.junction.com/api-reference/data/timeseries/blood-oxygen

GET /v2/timeseries/{user_id}/blood_oxygen/grouped

<Card title="View Full Response Schema »" icon="diamond-turn-right" iconType="sharp-solid" color="#F3A712" href="https://api.tryvital.io/redoc#tag/timeseries/operation/get_blood_oxygen_grouped">
  The Response section on the page still needs work. Click here to check out the complete schema.
</Card>

<RequestExample>
  ```bash cURL
  curl --request GET \
       --url {{BASE_URL}}/v2/timeseries/{user_id}/blood_oxygen/grouped?start_date={{START_DATE}}&end_date={{END_DATE}} \
       --header 'Accept: application/json' \
       --header 'x-vital-api-key: <API_KEY>'
  ```

  ```python Python
  from vital.client import Vital
  from vital.environment import VitalEnvironment

  client = Vital(
    api_key="YOUR_API_KEY",
    environment=VitalEnvironment.SANDBOX
  )

  data = client.vitals.blood_oxygen_grouped(
    user_id="<user_id>", 
    start_date="2021-10-01", 
    end_date="2021-10-02"
  )
  ```

  ```javascript Node
  import { VitalClient, VitalEnvironment } from '@tryvital/vital-node';
  import { VitalsBloodOxygenGroupedRequest } from '@tryvital/vital-node/api/resources/vitals';

  const client = new VitalClient({
      apiKey: '<my_api_key>',
      environment: VitalEnvironment.Sandbox,
  });

  const request: VitalsBloodOxygenGroupedRequest = {
      startDate: "2022-05-01",
      endDate: "2022-06-01"
  }

  const data = await client.vitals.bloodOxygenGrouped(
      '<my_user_id>',
      request
  );
  ```

  ```java Java
  import com.vital.api.Vital;
  import com.vital.api.core.Environment;
  import com.vital.api.resources.vitals.requests.VitalsBloodOxygenGroupedRequest;

  Vital vital = Vital.builder()
          .apiKey("YOUR_API_KEY")
          .environment(Environment.SANDBOX)
          .build();

  VitalsBloodOxygenGroupedRequest request = VitalsBloodOxygenGroupedRequest.builder()
          .startDate("2022-05-01")
          .endDate("2022-06-01")
          .build();

  var data = vital.vitals().bloodOxygenGrouped("<user_id>", request);
  ```

  ```go Go
  import (
    "context"

    vital "github.com/tryVital/vital-go"
    vitalclient "github.com/tryVital/vital-go/client"
  )

  client := vitalclient.NewClient(
    vitalclient.WithApiKey("<YOUR_API_KEY>"),
    vitalclient.WithBaseURL(vital.Environments.Sandbox),
  )

  EndDate := "2022-06-01"
  request := &vital.VitalsBloodOxygenGroupedRequest{
    StartDate: "2022-05-01",
    EndDate:   &EndDate,
  }

  response, err := client.Vitals.BloodOxygenGrouped(context.TODO(), "*", request)
  if err != nil {
    return err
  }
  fmt.Printf("Received data %s\n", response)
  ```
</RequestExample>

<ResponseExample>
  ```json Example
  {
    "groups": {
      "oura": [
        {
          "data": [
            {
              "timestamp": "2023-02-13T14:30:52+00:00",
              "unit": "%",
              "value": 98
            }
          ],
          "source": {
            "provider": "oura",
            "type": "ring"
          }
        }
      ]
    }
  }
  ```
</ResponseExample>


# Blood Pressure
Source: https://docs.junction.com/api-reference/data/timeseries/blood-pressure

GET /v2/timeseries/{user_id}/blood_pressure/grouped

<Card title="View Full Response Schema »" icon="diamond-turn-right" iconType="sharp-solid" color="#F3A712" href="https://api.tryvital.io/redoc#tag/timeseries/operation/get_blood_pressure_grouped">
  The Response section on the page still needs work. Click here to check out the complete schema.
</Card>

<RequestExample>
  ```bash cURL
  curl --request GET \
       --url {{BASE_URL}}/v2/timeseries/{user_id}/blood_pressure/grouped?start_date={{START_DATE}}&end_date={{END_DATE}} \
       --header 'Accept: application/json' \
       --header 'x-vital-api-key: <API_KEY>'
  ```

  ```python Python
  from vital.client import Vital
  from vital.environment import VitalEnvironment

  client = Vital(
    api_key="YOUR_API_KEY",
    environment=VitalEnvironment.SANDBOX
  )

  data = client.vitals.blood_pressure_grouped(
    user_id="<user_id>", 
    start_date="2021-10-01", 
    end_date="2021-10-02"
  )
  ```

  ```javascript Node
  import { VitalClient, VitalEnvironment } from '@tryvital/vital-node';
  import { VitalsBloodPressureGroupedRequest } from '@tryvital/vital-node/api/resources/vitals';

  const client = new VitalClient({
      apiKey: '<my_api_key>',
      environment: VitalEnvironment.Sandbox,
  });

  const request: VitalsBloodPressureGroupedRequest = {
      startDate: "2022-05-01",
      endDate: "2022-06-01"
  }

  const data = await client.vitals.bloodPressureGrouped(
      '<my_user_id>',
      request
  );
  ```

  ```java Java
  import com.vital.api.Vital;
  import com.vital.api.core.Environment;
  import com.vital.api.resources.vitals.requests.VitalsBloodPressureGroupedRequest;

  Vital vital = Vital.builder()
          .apiKey("YOUR_API_KEY")
          .environment(Environment.SANDBOX)
          .build();

  VitalsBloodPressureGroupedRequest request = VitalsBloodPressureGroupedRequest.builder()
          .startDate("2022-05-01")
          .endDate("2022-06-01")
          .build();

  var data = vital.vitals().bloodPressureGrouped("<user_id>", request);
  ```

  ```go Go
  import (
    "context"

    vital "github.com/tryVital/vital-go"
    vitalclient "github.com/tryVital/vital-go/client"
  )

  client := vitalclient.NewClient(
    vitalclient.WithApiKey("<YOUR_API_KEY>"),
    vitalclient.WithBaseURL(vital.Environments.Sandbox),
  )

  EndDate := "2022-06-01"
  request := &vital.VitalsBloodPressureGroupedRequest{
    StartDate: "2022-05-01",
    EndDate:   &EndDate,
  }

  response, err := client.Vitals.BloodPressureGrouped(context.TODO(), "*", request)
  if err != nil {
    return err
  }
  fmt.Printf("Received data %s\n", response)
  ```
</RequestExample>

<ResponseExample>
  ```json Example
  {
    "groups": {
      "oura": [
        {
          "data": [
            {
              "diastolic": 75,
              "systolic": 125,
              "timestamp": "2025-08-22T21:42:21+00:00",
              "unit": "mmHg"
            }
          ],
          "source": {
            "provider": "oura",
            "type": "ring"
          }
        }
      ]
    }
  }
  ```
</ResponseExample>


# Body Fat
Source: https://docs.junction.com/api-reference/data/timeseries/body-fat

GET /v2/timeseries/{user_id}/body_fat/grouped

<Card title="View Full Response Schema »" icon="diamond-turn-right" iconType="sharp-solid" color="#F3A712" href="https://api.tryvital.io/redoc#tag/timeseries/operation/get_body_fat_grouped">
  The Response section on the page still needs work. Click here to check out the complete schema.
</Card>

<RequestExample>
  ```bash cURL
  curl --request GET \
       --url {{BASE_URL}}/v2/timeseries/{user_id}/body_fat/grouped?start_date={{START_DATE}}&end_date={{END_DATE}} \
       --header 'Accept: application/json' \
       --header 'x-vital-api-key: <API_KEY>'
  ```

  ```python Python
  from vital.client import Vital
  from vital.environment import VitalEnvironment

  client = Vital(
    api_key="YOUR_API_KEY",
    environment=VitalEnvironment.SANDBOX
  )

  data = client.vitals.body_fat_grouped(
    user_id="<user_id>", 
    start_date="2021-10-01", 
    end_date="2021-10-02"
  )
  ```

  ```javascript Node
  import { VitalClient, VitalEnvironment } from '@tryvital/vital-node';
  import { VitalsBodyFatGroupedRequest } from '@tryvital/vital-node/api/resources/vitals';

  const client = new VitalClient({
      apiKey: '<my_api_key>',
      environment: VitalEnvironment.Sandbox,
  });

  const request: VitalsBodyFatGroupedRequest = {
      startDate: "2022-05-01",
      endDate: "2022-06-01"
  }

  const data = await client.vitals.bodyFatGrouped(
      '<my_user_id>',
      request
  );
  ```

  ```java Java
  import com.vital.api.Vital;
  import com.vital.api.core.Environment;
  import com.vital.api.resources.vitals.requests.VitalsBodyFatGroupedRequest;

  Vital vital = Vital.builder()
          .apiKey("YOUR_API_KEY")
          .environment(Environment.SANDBOX)
          .build();

  VitalsBodyFatGroupedRequest request = VitalsBodyFatGroupedRequest.builder()
          .startDate("2022-05-01")
          .endDate("2022-06-01")
          .build();

  var data = vital.vitals().bodyFatGrouped("<user_id>", request);
  ```

  ```go Go
  import (
    "context"

    vital "github.com/tryVital/vital-go"
    vitalclient "github.com/tryVital/vital-go/client"
  )

  client := vitalclient.NewClient(
    vitalclient.WithApiKey("<YOUR_API_KEY>"),
    vitalclient.WithBaseURL(vital.Environments.Sandbox),
  )

  EndDate := "2022-06-01"
  request := &vital.VitalsBodyFatGroupedRequest{
    StartDate: "2022-05-01",
    EndDate:   &EndDate,
  }

  response, err := client.Vitals.BodyFatGrouped(context.TODO(), "*", request)
  if err != nil {
    return err
  }
  fmt.Printf("Received data %s\n", response)
  ```
</RequestExample>

<ResponseExample>
  ```json Example
  {
    "groups": {
      "oura": [
        {
          "data": [
            {
              "timestamp": "2023-02-13T14:30:52+00:00",
              "unit": "%",
              "value": 50
            }
          ],
          "source": {
            "provider": "oura",
            "type": "ring"
          }
        }
      ]
    }
  }
  ```
</ResponseExample>


# Body Mass Index
Source: https://docs.junction.com/api-reference/data/timeseries/body-mass-index

GET /v2/timeseries/{user_id}/body_mass_index/grouped

<Card title="View Full Response Schema »" icon="diamond-turn-right" iconType="sharp-solid" color="#F3A712" href="https://api.tryvital.io/redoc#tag/timeseries/operation/get_body_mass_index_grouped">
  The Response section on the page still needs work. Click here to check out the complete schema.
</Card>

<RequestExample>
  ```bash cURL
  curl --request GET \
       --url {{BASE_URL}}/v2/timeseries/{user_id}/body_mass_index/grouped?start_date={{START_DATE}}&end_date={{END_DATE}} \
       --header 'Accept: application/json' \
       --header 'x-vital-api-key: <API_KEY>'
  ```

  ```python Python
  from vital.client import Vital
  from vital.environment import VitalEnvironment

  client = Vital(
    api_key="YOUR_API_KEY",
    environment=VitalEnvironment.SANDBOX
  )

  data = client.vitals.body_mass_index_grouped(
    user_id="<user_id>", 
    start_date="2021-10-01", 
    end_date="2021-10-02"
  )
  ```

  ```javascript Node
  import { VitalClient, VitalEnvironment } from '@tryvital/vital-node';
  import { VitalsBodyMassIndexGroupedRequest } from '@tryvital/vital-node/api/resources/vitals';

  const client = new VitalClient({
      apiKey: '<my_api_key>',
      environment: VitalEnvironment.Sandbox,
  });

  const request: VitalsBodyMassIndexGroupedRequest = {
      startDate: "2022-05-01",
      endDate: "2022-06-01"
  }

  const data = await client.vitals.bodyMassIndexGrouped(
      '<my_user_id>',
      request
  );
  ```

  ```java Java
  import com.vital.api.Vital;
  import com.vital.api.core.Environment;
  import com.vital.api.resources.vitals.requests.VitalsBodyMassIndexGroupedRequest;

  Vital vital = Vital.builder()
          .apiKey("YOUR_API_KEY")
          .environment(Environment.SANDBOX)
          .build();

  VitalsBodyMassIndexGroupedRequest request = VitalsBodyMassIndexGroupedRequest.builder()
          .startDate("2022-05-01")
          .endDate("2022-06-01")
          .build();

  var data = vital.vitals().bodyMassIndexGrouped("<user_id>", request);
  ```

  ```go Go
  import (
    "context"

    vital "github.com/tryVital/vital-go"
    vitalclient "github.com/tryVital/vital-go/client"
  )

  client := vitalclient.NewClient(
    vitalclient.WithApiKey("<YOUR_API_KEY>"),
    vitalclient.WithBaseURL(vital.Environments.Sandbox),
  )

  EndDate := "2022-06-01"
  request := &vital.VitalsBodyMassIndexGroupedRequest{
    StartDate: "2022-05-01",
    EndDate:   &EndDate,
  }

  response, err := client.Vitals.BodyMassIndexGrouped(context.TODO(), "*", request)
  if err != nil {
    return err
  }
  fmt.Printf("Received data %s\n", response)
  ```
</RequestExample>

<ResponseExample>
  ```json Example
  {
    "groups": {
      "oura": [
        {
          "data": [
            {
              "end": "2023-02-13T14:57:24+00:00",
              "start": "2023-02-13T14:30:52+00:00",
              "timestamp": "2023-02-13T14:30:52+00:00",
              "unit": "index",
              "value": 21
            }
          ],
          "source": {
            "provider": "oura",
            "type": "ring"
          }
        }
      ]
    }
  }
  ```
</ResponseExample>


# Body Temperature
Source: https://docs.junction.com/api-reference/data/timeseries/body-temperature

GET /v2/timeseries/{user_id}/body_temperature/grouped

<Card title="View Full Response Schema »" icon="diamond-turn-right" iconType="sharp-solid" color="#F3A712" href="https://api.tryvital.io/redoc#tag/timeseries/operation/get_body_temperature_grouped">
  The Response section on the page still needs work. Click here to check out the complete schema.
</Card>

<RequestExample>
  ```bash cURL
  curl --request GET \
       --url {{BASE_URL}}/v2/timeseries/{user_id}/body_temperature/grouped?start_date={{START_DATE}}&end_date={{END_DATE}} \
       --header 'Accept: application/json' \
       --header 'x-vital-api-key: <API_KEY>'
  ```

  ```python Python
  from vital.client import Vital
  from vital.environment import VitalEnvironment

  client = Vital(
    api_key="YOUR_API_KEY",
    environment=VitalEnvironment.SANDBOX
  )

  data = client.vitals.body_temperature_grouped(
    user_id="<user_id>", 
    start_date="2021-10-01", 
    end_date="2021-10-02"
  )
  ```

  ```javascript Node
  import { VitalClient, VitalEnvironment } from '@tryvital/vital-node';
  import { VitalsBodyTemperatureGroupedRequest } from '@tryvital/vital-node/api/resources/vitals';

  const client = new VitalClient({
      apiKey: '<my_api_key>',
      environment: VitalEnvironment.Sandbox,
  });

  const request: VitalsBodyTemperatureGroupedRequest = {
      startDate: "2022-05-01",
      endDate: "2022-06-01"
  }

  const data = await client.vitals.bodyTemperatureGrouped(
      '<my_user_id>',
      request
  );
  ```

  ```java Java
  import com.vital.api.Vital;
  import com.vital.api.core.Environment;
  import com.vital.api.resources.vitals.requests.VitalsBodyTemperatureGroupedRequest;

  Vital vital = Vital.builder()
          .apiKey("YOUR_API_KEY")
          .environment(Environment.SANDBOX)
          .build();

  VitalsBodyTemperatureGroupedRequest request = VitalsBodyTemperatureGroupedRequest.builder()
          .startDate("2022-05-01")
          .endDate("2022-06-01")
          .build();

  var data = vital.vitals().bodyTemperatureGrouped("<user_id>", request);
  ```

  ```go Go
  import (
    "context"

    vital "github.com/tryVital/vital-go"
    vitalclient "github.com/tryVital/vital-go/client"
  )

  client := vitalclient.NewClient(
    vitalclient.WithApiKey("<YOUR_API_KEY>"),
    vitalclient.WithBaseURL(vital.Environments.Sandbox),
  )

  EndDate := "2022-06-01"
  request := &vital.VitalsBodyTemperatureGroupedRequest{
    StartDate: "2022-05-01",
    EndDate:   &EndDate,
  }

  response, err := client.Vitals.BodyTemperatureGrouped(context.TODO(), "*", request)
  if err != nil {
    return err
  }
  fmt.Printf("Received data %s\n", response)
  ```
</RequestExample>

<ResponseExample>
  ```json Example
  {
    "groups": {
      "oura": [
        {
          "data": [
            {
              "end": "2023-02-13T14:30:52+00:00",
              "sensor_location": "eardrum",
              "start": "2023-02-13T14:30:52+00:00",
              "unit": "\u00b0C",
              "value": 65
            }
          ],
          "source": {
            "provider": "oura",
            "type": "ring"
          }
        }
      ]
    }
  }
  ```
</ResponseExample>


# Body Temperature Delta
Source: https://docs.junction.com/api-reference/data/timeseries/body-temperature-delta

GET /v2/timeseries/{user_id}/body_temperature_delta/grouped

<Card title="View Full Response Schema »" icon="diamond-turn-right" iconType="sharp-solid" color="#F3A712" href="https://api.tryvital.io/redoc#tag/timeseries/operation/get_body_temperature_delta_grouped">
  The Response section on the page still needs work. Click here to check out the complete schema.
</Card>

<RequestExample>
  ```bash cURL
  curl --request GET \
       --url {{BASE_URL}}/v2/timeseries/{user_id}/body_temperature_delta/grouped?start_date={{START_DATE}}&end_date={{END_DATE}} \
       --header 'Accept: application/json' \
       --header 'x-vital-api-key: <API_KEY>'
  ```

  ```python Python
  from vital.client import Vital
  from vital.environment import VitalEnvironment

  client = Vital(
    api_key="YOUR_API_KEY",
    environment=VitalEnvironment.SANDBOX
  )

  data = client.vitals.body_temperature_delta_grouped(
    user_id="<user_id>", 
    start_date="2021-10-01", 
    end_date="2021-10-02"
  )
  ```

  ```javascript Node
  import { VitalClient, VitalEnvironment } from '@tryvital/vital-node';
  import { VitalsBodyTemperatureDeltaGroupedRequest } from '@tryvital/vital-node/api/resources/vitals';

  const client = new VitalClient({
      apiKey: '<my_api_key>',
      environment: VitalEnvironment.Sandbox,
  });

  const request: VitalsBodyTemperatureDeltaGroupedRequest = {
      startDate: "2022-05-01",
      endDate: "2022-06-01"
  }

  const data = await client.vitals.bodyTemperatureDeltaGrouped(
      '<my_user_id>',
      request
  );
  ```

  ```java Java
  import com.vital.api.Vital;
  import com.vital.api.core.Environment;
  import com.vital.api.resources.vitals.requests.VitalsBodyTemperatureDeltaGroupedRequest;

  Vital vital = Vital.builder()
          .apiKey("YOUR_API_KEY")
          .environment(Environment.SANDBOX)
          .build();

  VitalsBodyTemperatureDeltaGroupedRequest request = VitalsBodyTemperatureDeltaGroupedRequest.builder()
          .startDate("2022-05-01")
          .endDate("2022-06-01")
          .build();

  var data = vital.vitals().bodyTemperatureDeltaGrouped("<user_id>", request);
  ```

  ```go Go
  import (
    "context"

    vital "github.com/tryVital/vital-go"
    vitalclient "github.com/tryVital/vital-go/client"
  )

  client := vitalclient.NewClient(
    vitalclient.WithApiKey("<YOUR_API_KEY>"),
    vitalclient.WithBaseURL(vital.Environments.Sandbox),
  )

  EndDate := "2022-06-01"
  request := &vital.VitalsBodyTemperatureDeltaGroupedRequest{
    StartDate: "2022-05-01",
    EndDate:   &EndDate,
  }

  response, err := client.Vitals.BodyTemperatureDeltaGrouped(context.TODO(), "*", request)
  if err != nil {
    return err
  }
  fmt.Printf("Received data %s\n", response)
  ```
</RequestExample>

<ResponseExample>
  ```json Example
  {
    "groups": {
      "oura": [
        {
          "data": [
            {
              "end": "2023-02-13T14:57:24+00:00",
              "sensor_location": "wrist",
              "start": "2023-02-13T14:30:52+00:00",
              "unit": "\u00b0C",
              "value": -1.0
            }
          ],
          "source": {
            "provider": "oura",
            "type": "ring"
          }
        }
      ]
    }
  }
  ```
</ResponseExample>


# Body Weight
Source: https://docs.junction.com/api-reference/data/timeseries/body-weight

GET /v2/timeseries/{user_id}/body_weight/grouped

<Card title="View Full Response Schema »" icon="diamond-turn-right" iconType="sharp-solid" color="#F3A712" href="https://api.tryvital.io/redoc#tag/timeseries/operation/get_body_weight_grouped">
  The Response section on the page still needs work. Click here to check out the complete schema.
</Card>

<RequestExample>
  ```bash cURL
  curl --request GET \
       --url {{BASE_URL}}/v2/timeseries/{user_id}/body_weight/grouped?start_date={{START_DATE}}&end_date={{END_DATE}} \
       --header 'Accept: application/json' \
       --header 'x-vital-api-key: <API_KEY>'
  ```

  ```python Python
  from vital.client import Vital
  from vital.environment import VitalEnvironment

  client = Vital(
    api_key="YOUR_API_KEY",
    environment=VitalEnvironment.SANDBOX
  )

  data = client.vitals.body_weight_grouped(
    user_id="<user_id>", 
    start_date="2021-10-01", 
    end_date="2021-10-02"
  )
  ```

  ```javascript Node
  import { VitalClient, VitalEnvironment } from '@tryvital/vital-node';
  import { VitalsBodyWeightGroupedRequest } from '@tryvital/vital-node/api/resources/vitals';

  const client = new VitalClient({
      apiKey: '<my_api_key>',
      environment: VitalEnvironment.Sandbox,
  });

  const request: VitalsBodyWeightGroupedRequest = {
      startDate: "2022-05-01",
      endDate: "2022-06-01"
  }

  const data = await client.vitals.bodyWeightGrouped(
      '<my_user_id>',
      request
  );
  ```

  ```java Java
  import com.vital.api.Vital;
  import com.vital.api.core.Environment;
  import com.vital.api.resources.vitals.requests.VitalsBodyWeightGroupedRequest;

  Vital vital = Vital.builder()
          .apiKey("YOUR_API_KEY")
          .environment(Environment.SANDBOX)
          .build();

  VitalsBodyWeightGroupedRequest request = VitalsBodyWeightGroupedRequest.builder()
          .startDate("2022-05-01")
          .endDate("2022-06-01")
          .build();

  var data = vital.vitals().bodyWeightGrouped("<user_id>", request);
  ```

  ```go Go
  import (
    "context"

    vital "github.com/tryVital/vital-go"
    vitalclient "github.com/tryVital/vital-go/client"
  )

  client := vitalclient.NewClient(
    vitalclient.WithApiKey("<YOUR_API_KEY>"),
    vitalclient.WithBaseURL(vital.Environments.Sandbox),
  )

  EndDate := "2022-06-01"
  request := &vital.VitalsBodyWeightGroupedRequest{
    StartDate: "2022-05-01",
    EndDate:   &EndDate,
  }

  response, err := client.Vitals.BodyWeightGrouped(context.TODO(), "*", request)
  if err != nil {
    return err
  }
  fmt.Printf("Received data %s\n", response)
  ```
</RequestExample>

<ResponseExample>
  ```json Example
  {
    "groups": {
      "oura": [
        {
          "data": [
            {
              "timestamp": "2023-02-13T14:30:52+00:00",
              "unit": "kg",
              "value": 65
            }
          ],
          "source": {
            "provider": "oura",
            "type": "ring"
          }
        }
      ]
    }
  }
  ```
</ResponseExample>


# Caffeine
Source: https://docs.junction.com/api-reference/data/timeseries/caffeine

GET /v2/timeseries/{user_id}/caffeine/grouped

<Card title="View Full Response Schema »" icon="diamond-turn-right" iconType="sharp-solid" color="#F3A712" href="https://api.tryvital.io/redoc#tag/timeseries/operation/get_caffeine_grouped">
  The Response section on the page still needs work. Click here to check out the complete schema.
</Card>

<RequestExample>
  ```bash cURL
  curl --request GET \
       --url {{BASE_URL}}/v2/timeseries/{user_id}/caffeine/grouped?start_date={{START_DATE}}&end_date={{END_DATE}} \
       --header 'Accept: application/json' \
       --header 'x-vital-api-key: <API_KEY>'
  ```

  ```python Python
  from vital.client import Vital
  from vital.environment import VitalEnvironment

  client = Vital(
    api_key="YOUR_API_KEY",
    environment=VitalEnvironment.SANDBOX
  )

  data = client.vitals.caffeine_grouped(
    user_id="<user_id>", 
    start_date="2021-10-01", 
    end_date="2021-10-02"
  )
  ```

  ```javascript Node
  import { VitalClient, VitalEnvironment } from '@tryvital/vital-node';
  import { VitalsCaffeineGroupedRequest } from '@tryvital/vital-node/api/resources/vitals';

  const client = new VitalClient({
      apiKey: '<my_api_key>',
      environment: VitalEnvironment.Sandbox,
  });

  const request: VitalsCaffeineGroupedRequest = {
      startDate: "2022-05-01",
      endDate: "2022-06-01"
  }

  const data = await client.vitals.caffeineGrouped(
      '<my_user_id>',
      request
  );
  ```

  ```java Java
  import com.vital.api.Vital;
  import com.vital.api.core.Environment;
  import com.vital.api.resources.vitals.requests.VitalsCaffeineGroupedRequest;

  Vital vital = Vital.builder()
          .apiKey("YOUR_API_KEY")
          .environment(Environment.SANDBOX)
          .build();

  VitalsCaffeineGroupedRequest request = VitalsCaffeineGroupedRequest.builder()
          .startDate("2022-05-01")
          .endDate("2022-06-01")
          .build();

  var data = vital.vitals().caffeineGrouped("<user_id>", request);
  ```

  ```go Go
  import (
    "context"

    vital "github.com/tryVital/vital-go"
    vitalclient "github.com/tryVital/vital-go/client"
  )

  client := vitalclient.NewClient(
    vitalclient.WithApiKey("<YOUR_API_KEY>"),
    vitalclient.WithBaseURL(vital.Environments.Sandbox),
  )

  EndDate := "2022-06-01"
  request := &vital.VitalsCaffeineGroupedRequest{
    StartDate: "2022-05-01",
    EndDate:   &EndDate,
  }

  response, err := client.Vitals.CaffeineGrouped(context.TODO(), "*", request)
  if err != nil {
    return err
  }
  fmt.Printf("Received data %s\n", response)
  ```
</RequestExample>

<ResponseExample>
  ```json Example
  {
    "groups": {
      "oura": [
        {
          "data": [
            {
              "end": "2023-02-13T14:57:24+00:00",
              "start": "2023-02-13T14:30:52+00:00",
              "unit": "g",
              "value": 42
            }
          ],
          "source": {
            "provider": "oura",
            "type": "ring"
          }
        }
      ]
    }
  }
  ```
</ResponseExample>


# Calories Active
Source: https://docs.junction.com/api-reference/data/timeseries/calories-active

GET /v2/timeseries/{user_id}/calories_active/grouped

<Card title="View Full Response Schema »" icon="diamond-turn-right" iconType="sharp-solid" color="#F3A712" href="https://api.tryvital.io/redoc#tag/timeseries/operation/get_calories_active_grouped">
  The Response section on the page still needs work. Click here to check out the complete schema.
</Card>

<RequestExample>
  ```bash cURL
  curl --request GET \
       --url {{BASE_URL}}/v2/timeseries/{user_id}/calories_active/grouped?start_date={{START_DATE}}&end_date={{END_DATE}} \
       --header 'Accept: application/json' \
       --header 'x-vital-api-key: <API_KEY>'
  ```

  ```python Python
  from vital.client import Vital
  from vital.environment import VitalEnvironment

  client = Vital(
    api_key="YOUR_API_KEY",
    environment=VitalEnvironment.SANDBOX
  )

  data = client.vitals.calories_active_grouped(
    user_id="<user_id>", 
    start_date="2021-10-01", 
    end_date="2021-10-02"
  )
  ```

  ```javascript Node
  import { VitalClient, VitalEnvironment } from '@tryvital/vital-node';
  import { VitalsCaloriesActiveGroupedRequest } from '@tryvital/vital-node/api/resources/vitals';

  const client = new VitalClient({
      apiKey: '<my_api_key>',
      environment: VitalEnvironment.Sandbox,
  });

  const request: VitalsCaloriesActiveGroupedRequest = {
      startDate: "2022-05-01",
      endDate: "2022-06-01"
  }

  const data = await client.vitals.caloriesActiveGrouped(
      '<my_user_id>',
      request
  );
  ```

  ```java Java
  import com.vital.api.Vital;
  import com.vital.api.core.Environment;
  import com.vital.api.resources.vitals.requests.VitalsCaloriesActiveGroupedRequest;

  Vital vital = Vital.builder()
          .apiKey("YOUR_API_KEY")
          .environment(Environment.SANDBOX)
          .build();

  VitalsCaloriesActiveGroupedRequest request = VitalsCaloriesActiveGroupedRequest.builder()
          .startDate("2022-05-01")
          .endDate("2022-06-01")
          .build();

  var data = vital.vitals().caloriesActiveGrouped("<user_id>", request);
  ```

  ```go Go
  import (
    "context"

    vital "github.com/tryVital/vital-go"
    vitalclient "github.com/tryVital/vital-go/client"
  )

  client := vitalclient.NewClient(
    vitalclient.WithApiKey("<YOUR_API_KEY>"),
    vitalclient.WithBaseURL(vital.Environments.Sandbox),
  )

  EndDate := "2022-06-01"
  request := &vital.VitalsCaloriesActiveGroupedRequest{
    StartDate: "2022-05-01",
    EndDate:   &EndDate,
  }

  response, err := client.Vitals.CaloriesActiveGrouped(context.TODO(), "*", request)
  if err != nil {
    return err
  }
  fmt.Printf("Received data %s\n", response)
  ```
</RequestExample>

<ResponseExample>
  ```json Example
  {
    "groups": {
      "oura": [
        {
          "data": [
            {
              "end": "2023-02-13T14:57:24+00:00",
              "start": "2023-02-13T14:30:52+00:00",
              "unit": "kcal",
              "value": 184
            }
          ],
          "source": {
            "provider": "oura",
            "type": "ring"
          }
        }
      ]
    }
  }
  ```
</ResponseExample>


# Calories Basal
Source: https://docs.junction.com/api-reference/data/timeseries/calories-basal

GET /v2/timeseries/{user_id}/calories_basal/grouped

<Card title="View Full Response Schema »" icon="diamond-turn-right" iconType="sharp-solid" color="#F3A712" href="https://api.tryvital.io/redoc#tag/timeseries/operation/get_calories_basal_grouped">
  The Response section on the page still needs work. Click here to check out the complete schema.
</Card>

<RequestExample>
  ```bash cURL
  curl --request GET \
       --url {{BASE_URL}}/v2/timeseries/{user_id}/calories_basal/grouped?start_date={{START_DATE}}&end_date={{END_DATE}} \
       --header 'Accept: application/json' \
       --header 'x-vital-api-key: <API_KEY>'
  ```

  ```python Python
  from vital.client import Vital
  from vital.environment import VitalEnvironment

  client = Vital(
    api_key="YOUR_API_KEY",
    environment=VitalEnvironment.SANDBOX
  )

  data = client.vitals.calories_basal_grouped(
    user_id="<user_id>", 
    start_date="2021-10-01", 
    end_date="2021-10-02"
  )
  ```

  ```javascript Node
  import { VitalClient, VitalEnvironment } from '@tryvital/vital-node';
  import { VitalsCaloriesBasalGroupedRequest } from '@tryvital/vital-node/api/resources/vitals';

  const client = new VitalClient({
      apiKey: '<my_api_key>',
      environment: VitalEnvironment.Sandbox,
  });

  const request: VitalsCaloriesBasalGroupedRequest = {
      startDate: "2022-05-01",
      endDate: "2022-06-01"
  }

  const data = await client.vitals.caloriesBasalGrouped(
      '<my_user_id>',
      request
  );
  ```

  ```java Java
  import com.vital.api.Vital;
  import com.vital.api.core.Environment;
  import com.vital.api.resources.vitals.requests.VitalsCaloriesBasalGroupedRequest;

  Vital vital = Vital.builder()
          .apiKey("YOUR_API_KEY")
          .environment(Environment.SANDBOX)
          .build();

  VitalsCaloriesBasalGroupedRequest request = VitalsCaloriesBasalGroupedRequest.builder()
          .startDate("2022-05-01")
          .endDate("2022-06-01")
          .build();

  var data = vital.vitals().caloriesBasalGrouped("<user_id>", request);
  ```

  ```go Go
  import (
    "context"

    vital "github.com/tryVital/vital-go"
    vitalclient "github.com/tryVital/vital-go/client"
  )

  client := vitalclient.NewClient(
    vitalclient.WithApiKey("<YOUR_API_KEY>"),
    vitalclient.WithBaseURL(vital.Environments.Sandbox),
  )

  EndDate := "2022-06-01"
  request := &vital.VitalsCaloriesBasalGroupedRequest{
    StartDate: "2022-05-01",
    EndDate:   &EndDate,
  }

  response, err := client.Vitals.CaloriesBasalGrouped(context.TODO(), "*", request)
  if err != nil {
    return err
  }
  fmt.Printf("Received data %s\n", response)
  ```
</RequestExample>

<ResponseExample>
  ```json Example
  {
    "groups": {
      "oura": [
        {
          "data": [
            {
              "end": "2023-02-13T14:57:24+00:00",
              "start": "2023-02-13T14:30:52+00:00",
              "unit": "kcal",
              "value": 22.8
            }
          ],
          "source": {
            "provider": "oura",
            "type": "ring"
          }
        }
      ]
    }
  }
  ```
</ResponseExample>


# Carbohydrates
Source: https://docs.junction.com/api-reference/data/timeseries/carbohydrates

GET /v2/timeseries/{user_id}/carbohydrates/grouped

<Card title="View Full Response Schema »" icon="diamond-turn-right" iconType="sharp-solid" color="#F3A712" href="https://api.tryvital.io/redoc#tag/timeseries/operation/get_carbohydrates_grouped">
  The Response section on the page still needs work. Click here to check out the complete schema.
</Card>

<RequestExample>
  ```bash cURL
  curl --request GET \
       --url {{BASE_URL}}/v2/timeseries/{user_id}/carbohydrates/grouped?start_date={{START_DATE}}&end_date={{END_DATE}} \
       --header 'Accept: application/json' \
       --header 'x-vital-api-key: <API_KEY>'
  ```

  ```python Python
  from vital.client import Vital
  from vital.environment import VitalEnvironment

  client = Vital(
    api_key="YOUR_API_KEY",
    environment=VitalEnvironment.SANDBOX
  )

  data = client.vitals.carbohydrates_grouped(
    user_id="<user_id>", 
    start_date="2021-10-01", 
    end_date="2021-10-02"
  )
  ```

  ```javascript Node
  import { VitalClient, VitalEnvironment } from '@tryvital/vital-node';
  import { VitalsCarbohydratesGroupedRequest } from '@tryvital/vital-node/api/resources/vitals';

  const client = new VitalClient({
      apiKey: '<my_api_key>',
      environment: VitalEnvironment.Sandbox,
  });

  const request: VitalsCarbohydratesGroupedRequest = {
      startDate: "2022-05-01",
      endDate: "2022-06-01"
  }

  const data = await client.vitals.carbohydratesGrouped(
      '<my_user_id>',
      request
  );
  ```

  ```java Java
  import com.vital.api.Vital;
  import com.vital.api.core.Environment;
  import com.vital.api.resources.vitals.requests.VitalsCarbohydratesGroupedRequest;

  Vital vital = Vital.builder()
          .apiKey("YOUR_API_KEY")
          .environment(Environment.SANDBOX)
          .build();

  VitalsCarbohydratesGroupedRequest request = VitalsCarbohydratesGroupedRequest.builder()
          .startDate("2022-05-01")
          .endDate("2022-06-01")
          .build();

  var data = vital.vitals().carbohydratesGrouped("<user_id>", request);
  ```

  ```go Go
  import (
    "context"

    vital "github.com/tryVital/vital-go"
    vitalclient "github.com/tryVital/vital-go/client"
  )

  client := vitalclient.NewClient(
    vitalclient.WithApiKey("<YOUR_API_KEY>"),
    vitalclient.WithBaseURL(vital.Environments.Sandbox),
  )

  EndDate := "2022-06-01"
  request := &vital.VitalsCarbohydratesGroupedRequest{
    StartDate: "2022-05-01",
    EndDate:   &EndDate,
  }

  response, err := client.Vitals.CarbohydratesGrouped(context.TODO(), "*", request)
  if err != nil {
    return err
  }
  fmt.Printf("Received data %s\n", response)
  ```
</RequestExample>

<ResponseExample>
  ```json Example
  {
    "groups": {
      "oura": [
        {
          "data": [
            {
              "end": "2023-02-13T14:30:52+00:00",
              "start": "2023-02-13T14:30:52+00:00",
              "unit": "g",
              "value": 30
            }
          ],
          "source": {
            "provider": "oura",
            "type": "ring"
          }
        }
      ]
    }
  }
  ```
</ResponseExample>


# Daylight Exposure
Source: https://docs.junction.com/api-reference/data/timeseries/daylight-exposure

GET /v2/timeseries/{user_id}/daylight_exposure/grouped

<Card title="View Full Response Schema »" icon="diamond-turn-right" iconType="sharp-solid" color="#F3A712" href="https://api.tryvital.io/redoc#tag/timeseries/operation/get_daylight_exposure_grouped">
  The Response section on the page still needs work. Click here to check out the complete schema.
</Card>

<RequestExample>
  ```bash cURL
  curl --request GET \
       --url {{BASE_URL}}/v2/timeseries/{user_id}/daylight_exposure/grouped?start_date={{START_DATE}}&end_date={{END_DATE}} \
       --header 'Accept: application/json' \
       --header 'x-vital-api-key: <API_KEY>'
  ```

  ```python Python
  from vital.client import Vital
  from vital.environment import VitalEnvironment

  client = Vital(
    api_key="YOUR_API_KEY",
    environment=VitalEnvironment.SANDBOX
  )

  data = client.vitals.daylight_exposure_grouped(
    user_id="<user_id>", 
    start_date="2021-10-01", 
    end_date="2021-10-02"
  )
  ```

  ```javascript Node
  import { VitalClient, VitalEnvironment } from '@tryvital/vital-node';
  import { VitalsDaylightExposureGroupedRequest } from '@tryvital/vital-node/api/resources/vitals';

  const client = new VitalClient({
      apiKey: '<my_api_key>',
      environment: VitalEnvironment.Sandbox,
  });

  const request: VitalsDaylightExposureGroupedRequest = {
      startDate: "2022-05-01",
      endDate: "2022-06-01"
  }

  const data = await client.vitals.daylightExposureGrouped(
      '<my_user_id>',
      request
  );
  ```

  ```java Java
  import com.vital.api.Vital;
  import com.vital.api.core.Environment;
  import com.vital.api.resources.vitals.requests.VitalsDaylightExposureGroupedRequest;

  Vital vital = Vital.builder()
          .apiKey("YOUR_API_KEY")
          .environment(Environment.SANDBOX)
          .build();

  VitalsDaylightExposureGroupedRequest request = VitalsDaylightExposureGroupedRequest.builder()
          .startDate("2022-05-01")
          .endDate("2022-06-01")
          .build();

  var data = vital.vitals().daylightExposureGrouped("<user_id>", request);
  ```

  ```go Go
  import (
    "context"

    vital "github.com/tryVital/vital-go"
    vitalclient "github.com/tryVital/vital-go/client"
  )

  client := vitalclient.NewClient(
    vitalclient.WithApiKey("<YOUR_API_KEY>"),
    vitalclient.WithBaseURL(vital.Environments.Sandbox),
  )

  EndDate := "2022-06-01"
  request := &vital.VitalsDaylightExposureGroupedRequest{
    StartDate: "2022-05-01",
    EndDate:   &EndDate,
  }

  response, err := client.Vitals.DaylightExposureGrouped(context.TODO(), "*", request)
  if err != nil {
    return err
  }
  fmt.Printf("Received data %s\n", response)
  ```
</RequestExample>

<ResponseExample>
  ```json Example
  {
    "groups": {
      "oura": [
        {
          "data": [
            {
              "end": "2023-02-13T14:57:24+00:00",
              "start": "2023-02-13T14:30:52+00:00",
              "timestamp": "2023-02-13T14:30:52+00:00",
              "unit": "min",
              "value": 45
            }
          ],
          "source": {
            "provider": "oura",
            "type": "ring"
          }
        }
      ]
    }
  }
  ```
</ResponseExample>


# Distance
Source: https://docs.junction.com/api-reference/data/timeseries/distance

GET /v2/timeseries/{user_id}/distance/grouped

<Card title="View Full Response Schema »" icon="diamond-turn-right" iconType="sharp-solid" color="#F3A712" href="https://api.tryvital.io/redoc#tag/timeseries/operation/get_distance_grouped">
  The Response section on the page still needs work. Click here to check out the complete schema.
</Card>

<RequestExample>
  ```bash cURL
  curl --request GET \
       --url {{BASE_URL}}/v2/timeseries/{user_id}/distance/grouped?start_date={{START_DATE}}&end_date={{END_DATE}} \
       --header 'Accept: application/json' \
       --header 'x-vital-api-key: <API_KEY>'
  ```

  ```python Python
  from vital.client import Vital
  from vital.environment import VitalEnvironment

  client = Vital(
    api_key="YOUR_API_KEY",
    environment=VitalEnvironment.SANDBOX
  )

  data = client.vitals.distance_grouped(
    user_id="<user_id>", 
    start_date="2021-10-01", 
    end_date="2021-10-02"
  )
  ```

  ```javascript Node
  import { VitalClient, VitalEnvironment } from '@tryvital/vital-node';
  import { VitalsDistanceGroupedRequest } from '@tryvital/vital-node/api/resources/vitals';

  const client = new VitalClient({
      apiKey: '<my_api_key>',
      environment: VitalEnvironment.Sandbox,
  });

  const request: VitalsDistanceGroupedRequest = {
      startDate: "2022-05-01",
      endDate: "2022-06-01"
  }

  const data = await client.vitals.distanceGrouped(
      '<my_user_id>',
      request
  );
  ```

  ```java Java
  import com.vital.api.Vital;
  import com.vital.api.core.Environment;
  import com.vital.api.resources.vitals.requests.VitalsDistanceGroupedRequest;

  Vital vital = Vital.builder()
          .apiKey("YOUR_API_KEY")
          .environment(Environment.SANDBOX)
          .build();

  VitalsDistanceGroupedRequest request = VitalsDistanceGroupedRequest.builder()
          .startDate("2022-05-01")
          .endDate("2022-06-01")
          .build();

  var data = vital.vitals().distanceGrouped("<user_id>", request);
  ```

  ```go Go
  import (
    "context"

    vital "github.com/tryVital/vital-go"
    vitalclient "github.com/tryVital/vital-go/client"
  )

  client := vitalclient.NewClient(
    vitalclient.WithApiKey("<YOUR_API_KEY>"),
    vitalclient.WithBaseURL(vital.Environments.Sandbox),
  )

  EndDate := "2022-06-01"
  request := &vital.VitalsDistanceGroupedRequest{
    StartDate: "2022-05-01",
    EndDate:   &EndDate,
  }

  response, err := client.Vitals.DistanceGrouped(context.TODO(), "*", request)
  if err != nil {
    return err
  }
  fmt.Printf("Received data %s\n", response)
  ```
</RequestExample>

<ResponseExample>
  ```json Example
  {
    "groups": {
      "oura": [
        {
          "data": [
            {
              "end": "2023-02-13T14:57:24+00:00",
              "start": "2023-02-13T14:30:52+00:00",
              "unit": "m",
              "value": 5.6
            }
          ],
          "source": {
            "provider": "oura",
            "type": "ring"
          }
        }
      ]
    }
  }
  ```
</ResponseExample>


# Electrocardiogram Voltage
Source: https://docs.junction.com/api-reference/data/timeseries/electrocardiogram-voltage

GET /v2/timeseries/{user_id}/electrocardiogram_voltage/grouped

<Card title="View Full Response Schema »" icon="diamond-turn-right" iconType="sharp-solid" color="#F3A712" href="https://api.tryvital.io/redoc#tag/timeseries/operation/get_electrocardiogram_voltage_grouped">
  The Response section on the page still needs work. Click here to check out the complete schema.
</Card>

<RequestExample>
  ```bash cURL
  curl --request GET \
       --url {{BASE_URL}}/v2/timeseries/{user_id}/electrocardiogram_voltage/grouped?start_date={{START_DATE}}&end_date={{END_DATE}} \
       --header 'Accept: application/json' \
       --header 'x-vital-api-key: <API_KEY>'
  ```

  ```python Python
  from vital.client import Vital
  from vital.environment import VitalEnvironment

  client = Vital(
    api_key="YOUR_API_KEY",
    environment=VitalEnvironment.SANDBOX
  )

  data = client.vitals.electrocardiogram_voltage_grouped(
    user_id="<user_id>", 
    start_date="2021-10-01", 
    end_date="2021-10-02"
  )
  ```

  ```javascript Node
  import { VitalClient, VitalEnvironment } from '@tryvital/vital-node';
  import { VitalsElectrocardiogramVoltageGroupedRequest } from '@tryvital/vital-node/api/resources/vitals';

  const client = new VitalClient({
      apiKey: '<my_api_key>',
      environment: VitalEnvironment.Sandbox,
  });

  const request: VitalsElectrocardiogramVoltageGroupedRequest = {
      startDate: "2022-05-01",
      endDate: "2022-06-01"
  }

  const data = await client.vitals.electrocardiogramVoltageGrouped(
      '<my_user_id>',
      request
  );
  ```

  ```java Java
  import com.vital.api.Vital;
  import com.vital.api.core.Environment;
  import com.vital.api.resources.vitals.requests.VitalsElectrocardiogramVoltageGroupedRequest;

  Vital vital = Vital.builder()
          .apiKey("YOUR_API_KEY")
          .environment(Environment.SANDBOX)
          .build();

  VitalsElectrocardiogramVoltageGroupedRequest request = VitalsElectrocardiogramVoltageGroupedRequest.builder()
          .startDate("2022-05-01")
          .endDate("2022-06-01")
          .build();

  var data = vital.vitals().electrocardiogramVoltageGrouped("<user_id>", request);
  ```

  ```go Go
  import (
    "context"

    vital "github.com/tryVital/vital-go"
    vitalclient "github.com/tryVital/vital-go/client"
  )

  client := vitalclient.NewClient(
    vitalclient.WithApiKey("<YOUR_API_KEY>"),
    vitalclient.WithBaseURL(vital.Environments.Sandbox),
  )

  EndDate := "2022-06-01"
  request := &vital.VitalsElectrocardiogramVoltageGroupedRequest{
    StartDate: "2022-05-01",
    EndDate:   &EndDate,
  }

  response, err := client.Vitals.ElectrocardiogramVoltageGrouped(context.TODO(), "*", request)
  if err != nil {
    return err
  }
  fmt.Printf("Received data %s\n", response)
  ```
</RequestExample>

<ResponseExample>
  ```json Example
  {
    "groups": {
      "oura": [
        {
          "data": [
            {
              "timestamp": "2023-02-13T14:30:52+00:00",
              "type": "lead_1",
              "unit": "mV",
              "value": -373
            }
          ],
          "source": {
            "provider": "oura",
            "type": "ring"
          }
        }
      ]
    }
  }
  ```
</ResponseExample>


# Fall
Source: https://docs.junction.com/api-reference/data/timeseries/fall

GET /v2/timeseries/{user_id}/fall/grouped

<Card title="View Full Response Schema »" icon="diamond-turn-right" iconType="sharp-solid" color="#F3A712" href="https://api.tryvital.io/redoc#tag/timeseries/operation/get_fall_grouped">
  The Response section on the page still needs work. Click here to check out the complete schema.
</Card>

<RequestExample>
  ```bash cURL
  curl --request GET \
       --url {{BASE_URL}}/v2/timeseries/{user_id}/fall/grouped?start_date={{START_DATE}}&end_date={{END_DATE}} \
       --header 'Accept: application/json' \
       --header 'x-vital-api-key: <API_KEY>'
  ```

  ```python Python
  from vital.client import Vital
  from vital.environment import VitalEnvironment

  client = Vital(
    api_key="YOUR_API_KEY",
    environment=VitalEnvironment.SANDBOX
  )

  data = client.vitals.fall_grouped(
    user_id="<user_id>", 
    start_date="2021-10-01", 
    end_date="2021-10-02"
  )
  ```

  ```javascript Node
  import { VitalClient, VitalEnvironment } from '@tryvital/vital-node';
  import { VitalsFallGroupedRequest } from '@tryvital/vital-node/api/resources/vitals';

  const client = new VitalClient({
      apiKey: '<my_api_key>',
      environment: VitalEnvironment.Sandbox,
  });

  const request: VitalsFallGroupedRequest = {
      startDate: "2022-05-01",
      endDate: "2022-06-01"
  }

  const data = await client.vitals.fallGrouped(
      '<my_user_id>',
      request
  );
  ```

  ```java Java
  import com.vital.api.Vital;
  import com.vital.api.core.Environment;
  import com.vital.api.resources.vitals.requests.VitalsFallGroupedRequest;

  Vital vital = Vital.builder()
          .apiKey("YOUR_API_KEY")
          .environment(Environment.SANDBOX)
          .build();

  VitalsFallGroupedRequest request = VitalsFallGroupedRequest.builder()
          .startDate("2022-05-01")
          .endDate("2022-06-01")
          .build();

  var data = vital.vitals().fallGrouped("<user_id>", request);
  ```

  ```go Go
  import (
    "context"

    vital "github.com/tryVital/vital-go"
    vitalclient "github.com/tryVital/vital-go/client"
  )

  client := vitalclient.NewClient(
    vitalclient.WithApiKey("<YOUR_API_KEY>"),
    vitalclient.WithBaseURL(vital.Environments.Sandbox),
  )

  EndDate := "2022-06-01"
  request := &vital.VitalsFallGroupedRequest{
    StartDate: "2022-05-01",
    EndDate:   &EndDate,
  }

  response, err := client.Vitals.FallGrouped(context.TODO(), "*", request)
  if err != nil {
    return err
  }
  fmt.Printf("Received data %s\n", response)
  ```
</RequestExample>

<ResponseExample>
  ```json Example
  {
    "groups": {
      "oura": [
        {
          "data": [
            {
              "end": "2023-02-13T14:57:24+00:00",
              "start": "2023-02-13T14:30:52+00:00",
              "timestamp": "2023-02-13T14:30:52+00:00",
              "unit": "count",
              "value": 3
            }
          ],
          "source": {
            "provider": "oura",
            "type": "ring"
          }
        }
      ]
    }
  }
  ```
</ResponseExample>


# Floors Climbed
Source: https://docs.junction.com/api-reference/data/timeseries/floors-climbed

GET /v2/timeseries/{user_id}/floors_climbed/grouped

<Card title="View Full Response Schema »" icon="diamond-turn-right" iconType="sharp-solid" color="#F3A712" href="https://api.tryvital.io/redoc#tag/timeseries/operation/get_floors_climbed_grouped">
  The Response section on the page still needs work. Click here to check out the complete schema.
</Card>

<RequestExample>
  ```bash cURL
  curl --request GET \
       --url {{BASE_URL}}/v2/timeseries/{user_id}/floors_climbed/grouped?start_date={{START_DATE}}&end_date={{END_DATE}} \
       --header 'Accept: application/json' \
       --header 'x-vital-api-key: <API_KEY>'
  ```

  ```python Python
  from vital.client import Vital
  from vital.environment import VitalEnvironment

  client = Vital(
    api_key="YOUR_API_KEY",
    environment=VitalEnvironment.SANDBOX
  )

  data = client.vitals.floors_climbed_grouped(
    user_id="<user_id>", 
    start_date="2021-10-01", 
    end_date="2021-10-02"
  )
  ```

  ```javascript Node
  import { VitalClient, VitalEnvironment } from '@tryvital/vital-node';
  import { VitalsFloorsClimbedGroupedRequest } from '@tryvital/vital-node/api/resources/vitals';

  const client = new VitalClient({
      apiKey: '<my_api_key>',
      environment: VitalEnvironment.Sandbox,
  });

  const request: VitalsFloorsClimbedGroupedRequest = {
      startDate: "2022-05-01",
      endDate: "2022-06-01"
  }

  const data = await client.vitals.floorsClimbedGrouped(
      '<my_user_id>',
      request
  );
  ```

  ```java Java
  import com.vital.api.Vital;
  import com.vital.api.core.Environment;
  import com.vital.api.resources.vitals.requests.VitalsFloorsClimbedGroupedRequest;

  Vital vital = Vital.builder()
          .apiKey("YOUR_API_KEY")
          .environment(Environment.SANDBOX)
          .build();

  VitalsFloorsClimbedGroupedRequest request = VitalsFloorsClimbedGroupedRequest.builder()
          .startDate("2022-05-01")
          .endDate("2022-06-01")
          .build();

  var data = vital.vitals().floorsClimbedGrouped("<user_id>", request);
  ```

  ```go Go
  import (
    "context"

    vital "github.com/tryVital/vital-go"
    vitalclient "github.com/tryVital/vital-go/client"
  )

  client := vitalclient.NewClient(
    vitalclient.WithApiKey("<YOUR_API_KEY>"),
    vitalclient.WithBaseURL(vital.Environments.Sandbox),
  )

  EndDate := "2022-06-01"
  request := &vital.VitalsFloorsClimbedGroupedRequest{
    StartDate: "2022-05-01",
    EndDate:   &EndDate,
  }

  response, err := client.Vitals.FloorsClimbedGrouped(context.TODO(), "*", request)
  if err != nil {
    return err
  }
  fmt.Printf("Received data %s\n", response)
  ```
</RequestExample>

<ResponseExample>
  ```json Example
  {
    "groups": {
      "oura": [
        {
          "data": [
            {
              "end": "2023-02-13T14:57:24+00:00",
              "start": "2023-02-13T14:30:52+00:00",
              "unit": "count",
              "value": 2
            }
          ],
          "source": {
            "provider": "oura",
            "type": "ring"
          }
        }
      ]
    }
  }
  ```
</ResponseExample>


# Forced Expiratory Volume 1
Source: https://docs.junction.com/api-reference/data/timeseries/forced-expiratory-volume-1

GET /v2/timeseries/{user_id}/forced_expiratory_volume_1/grouped

<Card title="View Full Response Schema »" icon="diamond-turn-right" iconType="sharp-solid" color="#F3A712" href="https://api.tryvital.io/redoc#tag/timeseries/operation/get_forced_expiratory_volume_1_grouped">
  The Response section on the page still needs work. Click here to check out the complete schema.
</Card>

<RequestExample>
  ```bash cURL
  curl --request GET \
       --url {{BASE_URL}}/v2/timeseries/{user_id}/forced_expiratory_volume_1/grouped?start_date={{START_DATE}}&end_date={{END_DATE}} \
       --header 'Accept: application/json' \
       --header 'x-vital-api-key: <API_KEY>'
  ```

  ```python Python
  from vital.client import Vital
  from vital.environment import VitalEnvironment

  client = Vital(
    api_key="YOUR_API_KEY",
    environment=VitalEnvironment.SANDBOX
  )

  data = client.vitals.forced_expiratory_volume_1_grouped(
    user_id="<user_id>", 
    start_date="2021-10-01", 
    end_date="2021-10-02"
  )
  ```

  ```javascript Node
  import { VitalClient, VitalEnvironment } from '@tryvital/vital-node';
  import { VitalsForcedExpiratoryVolume1GroupedRequest } from '@tryvital/vital-node/api/resources/vitals';

  const client = new VitalClient({
      apiKey: '<my_api_key>',
      environment: VitalEnvironment.Sandbox,
  });

  const request: VitalsForcedExpiratoryVolume1GroupedRequest = {
      startDate: "2022-05-01",
      endDate: "2022-06-01"
  }

  const data = await client.vitals.forcedExpiratoryVolume1Grouped(
      '<my_user_id>',
      request
  );
  ```

  ```java Java
  import com.vital.api.Vital;
  import com.vital.api.core.Environment;
  import com.vital.api.resources.vitals.requests.VitalsForcedExpiratoryVolume1GroupedRequest;

  Vital vital = Vital.builder()
          .apiKey("YOUR_API_KEY")
          .environment(Environment.SANDBOX)
          .build();

  VitalsForcedExpiratoryVolume1GroupedRequest request = VitalsForcedExpiratoryVolume1GroupedRequest.builder()
          .startDate("2022-05-01")
          .endDate("2022-06-01")
          .build();

  var data = vital.vitals().forcedExpiratoryVolume1Grouped("<user_id>", request);
  ```

  ```go Go
  import (
    "context"

    vital "github.com/tryVital/vital-go"
    vitalclient "github.com/tryVital/vital-go/client"
  )

  client := vitalclient.NewClient(
    vitalclient.WithApiKey("<YOUR_API_KEY>"),
    vitalclient.WithBaseURL(vital.Environments.Sandbox),
  )

  EndDate := "2022-06-01"
  request := &vital.VitalsForcedExpiratoryVolume1GroupedRequest{
    StartDate: "2022-05-01",
    EndDate:   &EndDate,
  }

  response, err := client.Vitals.ForcedExpiratoryVolume1Grouped(context.TODO(), "*", request)
  if err != nil {
    return err
  }
  fmt.Printf("Received data %s\n", response)
  ```
</RequestExample>

<ResponseExample>
  ```json Example
  {
    "groups": {
      "oura": [
        {
          "data": [
            {
              "end": "2023-02-13T14:57:24+00:00",
              "start": "2023-02-13T14:30:52+00:00",
              "timestamp": "2023-02-13T14:30:52+00:00",
              "unit": "L",
              "value": 3.5
            }
          ],
          "source": {
            "provider": "oura",
            "type": "ring"
          }
        }
      ]
    }
  }
  ```
</ResponseExample>


# Forced Vital Capacity
Source: https://docs.junction.com/api-reference/data/timeseries/forced-vital-capacity

GET /v2/timeseries/{user_id}/forced_vital_capacity/grouped

<Card title="View Full Response Schema »" icon="diamond-turn-right" iconType="sharp-solid" color="#F3A712" href="https://api.tryvital.io/redoc#tag/timeseries/operation/get_forced_vital_capacity_grouped">
  The Response section on the page still needs work. Click here to check out the complete schema.
</Card>

<RequestExample>
  ```bash cURL
  curl --request GET \
       --url {{BASE_URL}}/v2/timeseries/{user_id}/forced_vital_capacity/grouped?start_date={{START_DATE}}&end_date={{END_DATE}} \
       --header 'Accept: application/json' \
       --header 'x-vital-api-key: <API_KEY>'
  ```

  ```python Python
  from vital.client import Vital
  from vital.environment import VitalEnvironment

  client = Vital(
    api_key="YOUR_API_KEY",
    environment=VitalEnvironment.SANDBOX
  )

  data = client.vitals.forced_vital_capacity_grouped(
    user_id="<user_id>", 
    start_date="2021-10-01", 
    end_date="2021-10-02"
  )
  ```

  ```javascript Node
  import { VitalClient, VitalEnvironment } from '@tryvital/vital-node';
  import { VitalsForcedVitalCapacityGroupedRequest } from '@tryvital/vital-node/api/resources/vitals';

  const client = new VitalClient({
      apiKey: '<my_api_key>',
      environment: VitalEnvironment.Sandbox,
  });

  const request: VitalsForcedVitalCapacityGroupedRequest = {
      startDate: "2022-05-01",
      endDate: "2022-06-01"
  }

  const data = await client.vitals.forcedVitalCapacityGrouped(
      '<my_user_id>',
      request
  );
  ```

  ```java Java
  import com.vital.api.Vital;
  import com.vital.api.core.Environment;
  import com.vital.api.resources.vitals.requests.VitalsForcedVitalCapacityGroupedRequest;

  Vital vital = Vital.builder()
          .apiKey("YOUR_API_KEY")
          .environment(Environment.SANDBOX)
          .build();

  VitalsForcedVitalCapacityGroupedRequest request = VitalsForcedVitalCapacityGroupedRequest.builder()
          .startDate("2022-05-01")
          .endDate("2022-06-01")
          .build();

  var data = vital.vitals().forcedVitalCapacityGrouped("<user_id>", request);
  ```

  ```go Go
  import (
    "context"

    vital "github.com/tryVital/vital-go"
    vitalclient "github.com/tryVital/vital-go/client"
  )

  client := vitalclient.NewClient(
    vitalclient.WithApiKey("<YOUR_API_KEY>"),
    vitalclient.WithBaseURL(vital.Environments.Sandbox),
  )

  EndDate := "2022-06-01"
  request := &vital.VitalsForcedVitalCapacityGroupedRequest{
    StartDate: "2022-05-01",
    EndDate:   &EndDate,
  }

  response, err := client.Vitals.ForcedVitalCapacityGrouped(context.TODO(), "*", request)
  if err != nil {
    return err
  }
  fmt.Printf("Received data %s\n", response)
  ```
</RequestExample>

<ResponseExample>
  ```json Example
  {
    "groups": {
      "oura": [
        {
          "data": [
            {
              "end": "2023-02-13T14:57:24+00:00",
              "start": "2023-02-13T14:30:52+00:00",
              "timestamp": "2023-02-13T14:30:52+00:00",
              "unit": "L",
              "value": 4.2
            }
          ],
          "source": {
            "provider": "oura",
            "type": "ring"
          }
        }
      ]
    }
  }
  ```
</ResponseExample>


# Glucose
Source: https://docs.junction.com/api-reference/data/timeseries/glucose

GET /v2/timeseries/{user_id}/glucose/grouped

<Card title="View Full Response Schema »" icon="diamond-turn-right" iconType="sharp-solid" color="#F3A712" href="https://api.tryvital.io/redoc#tag/timeseries/operation/get_glucose_grouped">
  The Response section on the page still needs work. Click here to check out the complete schema.
</Card>

<RequestExample>
  ```bash cURL
  curl --request GET \
       --url {{BASE_URL}}/v2/timeseries/{user_id}/glucose/grouped?start_date={{START_DATE}}&end_date={{END_DATE}} \
       --header 'Accept: application/json' \
       --header 'x-vital-api-key: <API_KEY>'
  ```

  ```python Python
  from vital.client import Vital
  from vital.environment import VitalEnvironment

  client = Vital(
    api_key="YOUR_API_KEY",
    environment=VitalEnvironment.SANDBOX
  )

  data = client.vitals.glucose_grouped(
    user_id="<user_id>", 
    start_date="2021-10-01", 
    end_date="2021-10-02"
  )
  ```

  ```javascript Node
  import { VitalClient, VitalEnvironment } from '@tryvital/vital-node';
  import { VitalsGlucoseGroupedRequest } from '@tryvital/vital-node/api/resources/vitals';

  const client = new VitalClient({
      apiKey: '<my_api_key>',
      environment: VitalEnvironment.Sandbox,
  });

  const request: VitalsGlucoseGroupedRequest = {
      startDate: "2022-05-01",
      endDate: "2022-06-01"
  }

  const data = await client.vitals.glucoseGrouped(
      '<my_user_id>',
      request
  );
  ```

  ```java Java
  import com.vital.api.Vital;
  import com.vital.api.core.Environment;
  import com.vital.api.resources.vitals.requests.VitalsGlucoseGroupedRequest;

  Vital vital = Vital.builder()
          .apiKey("YOUR_API_KEY")
          .environment(Environment.SANDBOX)
          .build();

  VitalsGlucoseGroupedRequest request = VitalsGlucoseGroupedRequest.builder()
          .startDate("2022-05-01")
          .endDate("2022-06-01")
          .build();

  var data = vital.vitals().glucoseGrouped("<user_id>", request);
  ```

  ```go Go
  import (
    "context"

    vital "github.com/tryVital/vital-go"
    vitalclient "github.com/tryVital/vital-go/client"
  )

  client := vitalclient.NewClient(
    vitalclient.WithApiKey("<YOUR_API_KEY>"),
    vitalclient.WithBaseURL(vital.Environments.Sandbox),
  )

  EndDate := "2022-06-01"
  request := &vital.VitalsGlucoseGroupedRequest{
    StartDate: "2022-05-01",
    EndDate:   &EndDate,
  }

  response, err := client.Vitals.GlucoseGrouped(context.TODO(), "*", request)
  if err != nil {
    return err
  }
  fmt.Printf("Received data %s\n", response)
  ```
</RequestExample>

<ResponseExample>
  ```json Example
  {
    "groups": {
      "oura": [
        {
          "data": [
            {
              "timestamp": "2023-02-13T14:30:52+00:00",
              "type": "automatic | manual_scan",
              "unit": "mmol/L",
              "value": 0.5
            }
          ],
          "source": {
            "provider": "oura",
            "type": "ring"
          }
        }
      ]
    }
  }
  ```
</ResponseExample>


# Handwashing
Source: https://docs.junction.com/api-reference/data/timeseries/handwashing

GET /v2/timeseries/{user_id}/handwashing/grouped

<Card title="View Full Response Schema »" icon="diamond-turn-right" iconType="sharp-solid" color="#F3A712" href="https://api.tryvital.io/redoc#tag/timeseries/operation/get_handwashing_grouped">
  The Response section on the page still needs work. Click here to check out the complete schema.
</Card>

<RequestExample>
  ```bash cURL
  curl --request GET \
       --url {{BASE_URL}}/v2/timeseries/{user_id}/handwashing/grouped?start_date={{START_DATE}}&end_date={{END_DATE}} \
       --header 'Accept: application/json' \
       --header 'x-vital-api-key: <API_KEY>'
  ```

  ```python Python
  from vital.client import Vital
  from vital.environment import VitalEnvironment

  client = Vital(
    api_key="YOUR_API_KEY",
    environment=VitalEnvironment.SANDBOX
  )

  data = client.vitals.handwashing_grouped(
    user_id="<user_id>", 
    start_date="2021-10-01", 
    end_date="2021-10-02"
  )
  ```

  ```javascript Node
  import { VitalClient, VitalEnvironment } from '@tryvital/vital-node';
  import { VitalsHandwashingGroupedRequest } from '@tryvital/vital-node/api/resources/vitals';

  const client = new VitalClient({
      apiKey: '<my_api_key>',
      environment: VitalEnvironment.Sandbox,
  });

  const request: VitalsHandwashingGroupedRequest = {
      startDate: "2022-05-01",
      endDate: "2022-06-01"
  }

  const data = await client.vitals.handwashingGrouped(
      '<my_user_id>',
      request
  );
  ```

  ```java Java
  import com.vital.api.Vital;
  import com.vital.api.core.Environment;
  import com.vital.api.resources.vitals.requests.VitalsHandwashingGroupedRequest;

  Vital vital = Vital.builder()
          .apiKey("YOUR_API_KEY")
          .environment(Environment.SANDBOX)
          .build();

  VitalsHandwashingGroupedRequest request = VitalsHandwashingGroupedRequest.builder()
          .startDate("2022-05-01")
          .endDate("2022-06-01")
          .build();

  var data = vital.vitals().handwashingGrouped("<user_id>", request);
  ```

  ```go Go
  import (
    "context"

    vital "github.com/tryVital/vital-go"
    vitalclient "github.com/tryVital/vital-go/client"
  )

  client := vitalclient.NewClient(
    vitalclient.WithApiKey("<YOUR_API_KEY>"),
    vitalclient.WithBaseURL(vital.Environments.Sandbox),
  )

  EndDate := "2022-06-01"
  request := &vital.VitalsHandwashingGroupedRequest{
    StartDate: "2022-05-01",
    EndDate:   &EndDate,
  }

  response, err := client.Vitals.HandwashingGrouped(context.TODO(), "*", request)
  if err != nil {
    return err
  }
  fmt.Printf("Received data %s\n", response)
  ```
</RequestExample>

<ResponseExample>
  ```json Example
  {
    "groups": {
      "oura": [
        {
          "data": [
            {
              "end": "2023-02-13T14:57:24+00:00",
              "start": "2023-02-13T14:30:52+00:00",
              "timestamp": "2023-02-13T14:30:52+00:00",
              "unit": "count",
              "value": 1
            }
          ],
          "source": {
            "provider": "oura",
            "type": "ring"
          }
        }
      ]
    }
  }
  ```
</ResponseExample>


# Heart Rate Alert
Source: https://docs.junction.com/api-reference/data/timeseries/heart-rate-alert

GET /v2/timeseries/{user_id}/heart_rate_alert/grouped

<Card title="View Full Response Schema »" icon="diamond-turn-right" iconType="sharp-solid" color="#F3A712" href="https://api.tryvital.io/redoc#tag/timeseries/operation/get_heart_rate_alert_grouped">
  The Response section on the page still needs work. Click here to check out the complete schema.
</Card>

<RequestExample>
  ```bash cURL
  curl --request GET \
       --url {{BASE_URL}}/v2/timeseries/{user_id}/heart_rate_alert/grouped?start_date={{START_DATE}}&end_date={{END_DATE}} \
       --header 'Accept: application/json' \
       --header 'x-vital-api-key: <API_KEY>'
  ```

  ```python Python
  from vital.client import Vital
  from vital.environment import VitalEnvironment

  client = Vital(
    api_key="YOUR_API_KEY",
    environment=VitalEnvironment.SANDBOX
  )

  data = client.vitals.heart_rate_alert_grouped(
    user_id="<user_id>", 
    start_date="2021-10-01", 
    end_date="2021-10-02"
  )
  ```

  ```javascript Node
  import { VitalClient, VitalEnvironment } from '@tryvital/vital-node';
  import { VitalsHeartRateAlertGroupedRequest } from '@tryvital/vital-node/api/resources/vitals';

  const client = new VitalClient({
      apiKey: '<my_api_key>',
      environment: VitalEnvironment.Sandbox,
  });

  const request: VitalsHeartRateAlertGroupedRequest = {
      startDate: "2022-05-01",
      endDate: "2022-06-01"
  }

  const data = await client.vitals.heartRateAlertGrouped(
      '<my_user_id>',
      request
  );
  ```

  ```java Java
  import com.vital.api.Vital;
  import com.vital.api.core.Environment;
  import com.vital.api.resources.vitals.requests.VitalsHeartRateAlertGroupedRequest;

  Vital vital = Vital.builder()
          .apiKey("YOUR_API_KEY")
          .environment(Environment.SANDBOX)
          .build();

  VitalsHeartRateAlertGroupedRequest request = VitalsHeartRateAlertGroupedRequest.builder()
          .startDate("2022-05-01")
          .endDate("2022-06-01")
          .build();

  var data = vital.vitals().heartRateAlertGrouped("<user_id>", request);
  ```

  ```go Go
  import (
    "context"

    vital "github.com/tryVital/vital-go"
    vitalclient "github.com/tryVital/vital-go/client"
  )

  client := vitalclient.NewClient(
    vitalclient.WithApiKey("<YOUR_API_KEY>"),
    vitalclient.WithBaseURL(vital.Environments.Sandbox),
  )

  EndDate := "2022-06-01"
  request := &vital.VitalsHeartRateAlertGroupedRequest{
    StartDate: "2022-05-01",
    EndDate:   &EndDate,
  }

  response, err := client.Vitals.HeartRateAlertGrouped(context.TODO(), "*", request)
  if err != nil {
    return err
  }
  fmt.Printf("Received data %s\n", response)
  ```
</RequestExample>

<ResponseExample>
  ```json Example
  {
    "groups": {
      "oura": [
        {
          "data": [
            {
              "end": "2023-02-13T14:30:52+00:00",
              "start": "2023-02-13T14:30:52+00:00",
              "type": "irregular_rhythm",
              "unit": "count",
              "value": 1
            }
          ],
          "source": {
            "provider": "oura",
            "type": "ring"
          }
        }
      ]
    }
  }
  ```
</ResponseExample>


# Heart Rate Recovery One Minute
Source: https://docs.junction.com/api-reference/data/timeseries/heart-rate-recovery-one-minute

GET /v2/timeseries/{user_id}/heart_rate_recovery_one_minute/grouped

<Card title="View Full Response Schema »" icon="diamond-turn-right" iconType="sharp-solid" color="#F3A712" href="https://api.tryvital.io/redoc#tag/timeseries/operation/get_heart_rate_recovery_one_minute_grouped">
  The Response section on the page still needs work. Click here to check out the complete schema.
</Card>

<RequestExample>
  ```bash cURL
  curl --request GET \
       --url {{BASE_URL}}/v2/timeseries/{user_id}/heart_rate_recovery_one_minute/grouped?start_date={{START_DATE}}&end_date={{END_DATE}} \
       --header 'Accept: application/json' \
       --header 'x-vital-api-key: <API_KEY>'
  ```

  ```python Python
  from vital.client import Vital
  from vital.environment import VitalEnvironment

  client = Vital(
    api_key="YOUR_API_KEY",
    environment=VitalEnvironment.SANDBOX
  )

  data = client.vitals.heart_rate_recovery_one_minute_grouped(
    user_id="<user_id>", 
    start_date="2021-10-01", 
    end_date="2021-10-02"
  )
  ```

  ```javascript Node
  import { VitalClient, VitalEnvironment } from '@tryvital/vital-node';
  import { VitalsHeartRateRecoveryOneMinuteGroupedRequest } from '@tryvital/vital-node/api/resources/vitals';

  const client = new VitalClient({
      apiKey: '<my_api_key>',
      environment: VitalEnvironment.Sandbox,
  });

  const request: VitalsHeartRateRecoveryOneMinuteGroupedRequest = {
      startDate: "2022-05-01",
      endDate: "2022-06-01"
  }

  const data = await client.vitals.heartRateRecoveryOneMinuteGrouped(
      '<my_user_id>',
      request
  );
  ```

  ```java Java
  import com.vital.api.Vital;
  import com.vital.api.core.Environment;
  import com.vital.api.resources.vitals.requests.VitalsHeartRateRecoveryOneMinuteGroupedRequest;

  Vital vital = Vital.builder()
          .apiKey("YOUR_API_KEY")
          .environment(Environment.SANDBOX)
          .build();

  VitalsHeartRateRecoveryOneMinuteGroupedRequest request = VitalsHeartRateRecoveryOneMinuteGroupedRequest.builder()
          .startDate("2022-05-01")
          .endDate("2022-06-01")
          .build();

  var data = vital.vitals().heartRateRecoveryOneMinuteGrouped("<user_id>", request);
  ```

  ```go Go
  import (
    "context"

    vital "github.com/tryVital/vital-go"
    vitalclient "github.com/tryVital/vital-go/client"
  )

  client := vitalclient.NewClient(
    vitalclient.WithApiKey("<YOUR_API_KEY>"),
    vitalclient.WithBaseURL(vital.Environments.Sandbox),
  )

  EndDate := "2022-06-01"
  request := &vital.VitalsHeartRateRecoveryOneMinuteGroupedRequest{
    StartDate: "2022-05-01",
    EndDate:   &EndDate,
  }

  response, err := client.Vitals.HeartRateRecoveryOneMinuteGrouped(context.TODO(), "*", request)
  if err != nil {
    return err
  }
  fmt.Printf("Received data %s\n", response)
  ```
</RequestExample>

<ResponseExample>
  ```json Example
  {
    "groups": {
      "oura": [
        {
          "data": [
            {
              "end": "2023-02-13T14:57:24+00:00",
              "start": "2023-02-13T14:30:52+00:00",
              "timestamp": "2023-02-13T14:30:52+00:00",
              "unit": "count",
              "value": 37
            }
          ],
          "source": {
            "provider": "oura",
            "type": "ring"
          }
        }
      ]
    }
  }
  ```
</ResponseExample>


# Heart Rate
Source: https://docs.junction.com/api-reference/data/timeseries/heartrate

GET /v2/timeseries/{user_id}/heartrate/grouped

<Card title="View Full Response Schema »" icon="diamond-turn-right" iconType="sharp-solid" color="#F3A712" href="https://api.tryvital.io/redoc#tag/timeseries/operation/get_heartrate_grouped">
  The Response section on the page still needs work. Click here to check out the complete schema.
</Card>

<RequestExample>
  ```bash cURL
  curl --request GET \
       --url {{BASE_URL}}/v2/timeseries/{user_id}/heartrate/grouped?start_date={{START_DATE}}&end_date={{END_DATE}} \
       --header 'Accept: application/json' \
       --header 'x-vital-api-key: <API_KEY>'
  ```

  ```python Python
  from vital.client import Vital
  from vital.environment import VitalEnvironment

  client = Vital(
    api_key="YOUR_API_KEY",
    environment=VitalEnvironment.SANDBOX
  )

  data = client.vitals.heartrate_grouped(
    user_id="<user_id>", 
    start_date="2021-10-01", 
    end_date="2021-10-02"
  )
  ```

  ```javascript Node
  import { VitalClient, VitalEnvironment } from '@tryvital/vital-node';
  import { VitalsHeartrateGroupedRequest } from '@tryvital/vital-node/api/resources/vitals';

  const client = new VitalClient({
      apiKey: '<my_api_key>',
      environment: VitalEnvironment.Sandbox,
  });

  const request: VitalsHeartrateGroupedRequest = {
      startDate: "2022-05-01",
      endDate: "2022-06-01"
  }

  const data = await client.vitals.heartrateGrouped(
      '<my_user_id>',
      request
  );
  ```

  ```java Java
  import com.vital.api.Vital;
  import com.vital.api.core.Environment;
  import com.vital.api.resources.vitals.requests.VitalsHeartrateGroupedRequest;

  Vital vital = Vital.builder()
          .apiKey("YOUR_API_KEY")
          .environment(Environment.SANDBOX)
          .build();

  VitalsHeartrateGroupedRequest request = VitalsHeartrateGroupedRequest.builder()
          .startDate("2022-05-01")
          .endDate("2022-06-01")
          .build();

  var data = vital.vitals().heartrateGrouped("<user_id>", request);
  ```

  ```go Go
  import (
    "context"

    vital "github.com/tryVital/vital-go"
    vitalclient "github.com/tryVital/vital-go/client"
  )

  client := vitalclient.NewClient(
    vitalclient.WithApiKey("<YOUR_API_KEY>"),
    vitalclient.WithBaseURL(vital.Environments.Sandbox),
  )

  EndDate := "2022-06-01"
  request := &vital.VitalsHeartrateGroupedRequest{
    StartDate: "2022-05-01",
    EndDate:   &EndDate,
  }

  response, err := client.Vitals.HeartrateGrouped(context.TODO(), "*", request)
  if err != nil {
    return err
  }
  fmt.Printf("Received data %s\n", response)
  ```
</RequestExample>

<ResponseExample>
  ```json Example
  {
    "groups": {
      "oura": [
        {
          "data": [
            {
              "timestamp": "2023-02-13T14:30:52+00:00",
              "unit": "bpm",
              "value": 70
            }
          ],
          "source": {
            "provider": "oura",
            "type": "ring"
          }
        }
      ]
    }
  }
  ```
</ResponseExample>


# Heart Rate Variability
Source: https://docs.junction.com/api-reference/data/timeseries/hrv

GET /v2/timeseries/{user_id}/hrv/grouped

<Card title="View Full Response Schema »" icon="diamond-turn-right" iconType="sharp-solid" color="#F3A712" href="https://api.tryvital.io/redoc#tag/timeseries/operation/get_hrv_grouped">
  The Response section on the page still needs work. Click here to check out the complete schema.
</Card>

<RequestExample>
  ```bash cURL
  curl --request GET \
       --url {{BASE_URL}}/v2/timeseries/{user_id}/hrv/grouped?start_date={{START_DATE}}&end_date={{END_DATE}} \
       --header 'Accept: application/json' \
       --header 'x-vital-api-key: <API_KEY>'
  ```

  ```python Python
  from vital.client import Vital
  from vital.environment import VitalEnvironment

  client = Vital(
    api_key="YOUR_API_KEY",
    environment=VitalEnvironment.SANDBOX
  )

  data = client.vitals.hrv_grouped(
    user_id="<user_id>", 
    start_date="2021-10-01", 
    end_date="2021-10-02"
  )
  ```

  ```javascript Node
  import { VitalClient, VitalEnvironment } from '@tryvital/vital-node';
  import { VitalsHrvGroupedRequest } from '@tryvital/vital-node/api/resources/vitals';

  const client = new VitalClient({
      apiKey: '<my_api_key>',
      environment: VitalEnvironment.Sandbox,
  });

  const request: VitalsHrvGroupedRequest = {
      startDate: "2022-05-01",
      endDate: "2022-06-01"
  }

  const data = await client.vitals.hrvGrouped(
      '<my_user_id>',
      request
  );
  ```

  ```java Java
  import com.vital.api.Vital;
  import com.vital.api.core.Environment;
  import com.vital.api.resources.vitals.requests.VitalsHrvGroupedRequest;

  Vital vital = Vital.builder()
          .apiKey("YOUR_API_KEY")
          .environment(Environment.SANDBOX)
          .build();

  VitalsHrvGroupedRequest request = VitalsHrvGroupedRequest.builder()
          .startDate("2022-05-01")
          .endDate("2022-06-01")
          .build();

  var data = vital.vitals().hrvGrouped("<user_id>", request);
  ```

  ```go Go
  import (
    "context"

    vital "github.com/tryVital/vital-go"
    vitalclient "github.com/tryVital/vital-go/client"
  )

  client := vitalclient.NewClient(
    vitalclient.WithApiKey("<YOUR_API_KEY>"),
    vitalclient.WithBaseURL(vital.Environments.Sandbox),
  )

  EndDate := "2022-06-01"
  request := &vital.VitalsHrvGroupedRequest{
    StartDate: "2022-05-01",
    EndDate:   &EndDate,
  }

  response, err := client.Vitals.HrvGrouped(context.TODO(), "*", request)
  if err != nil {
    return err
  }
  fmt.Printf("Received data %s\n", response)
  ```
</RequestExample>

<ResponseExample>
  ```json Example
  {
    "groups": {
      "oura": [
        {
          "data": [
            {
              "timestamp": "2023-02-13T14:30:52+00:00",
              "unit": "rmssd",
              "value": 48
            }
          ],
          "source": {
            "provider": "oura",
            "type": "ring"
          }
        }
      ]
    }
  }
  ```
</ResponseExample>


# Inhaler Usage
Source: https://docs.junction.com/api-reference/data/timeseries/inhaler-usage

GET /v2/timeseries/{user_id}/inhaler_usage/grouped

<Card title="View Full Response Schema »" icon="diamond-turn-right" iconType="sharp-solid" color="#F3A712" href="https://api.tryvital.io/redoc#tag/timeseries/operation/get_inhaler_usage_grouped">
  The Response section on the page still needs work. Click here to check out the complete schema.
</Card>

<RequestExample>
  ```bash cURL
  curl --request GET \
       --url {{BASE_URL}}/v2/timeseries/{user_id}/inhaler_usage/grouped?start_date={{START_DATE}}&end_date={{END_DATE}} \
       --header 'Accept: application/json' \
       --header 'x-vital-api-key: <API_KEY>'
  ```

  ```python Python
  from vital.client import Vital
  from vital.environment import VitalEnvironment

  client = Vital(
    api_key="YOUR_API_KEY",
    environment=VitalEnvironment.SANDBOX
  )

  data = client.vitals.inhaler_usage_grouped(
    user_id="<user_id>", 
    start_date="2021-10-01", 
    end_date="2021-10-02"
  )
  ```

  ```javascript Node
  import { VitalClient, VitalEnvironment } from '@tryvital/vital-node';
  import { VitalsInhalerUsageGroupedRequest } from '@tryvital/vital-node/api/resources/vitals';

  const client = new VitalClient({
      apiKey: '<my_api_key>',
      environment: VitalEnvironment.Sandbox,
  });

  const request: VitalsInhalerUsageGroupedRequest = {
      startDate: "2022-05-01",
      endDate: "2022-06-01"
  }

  const data = await client.vitals.inhalerUsageGrouped(
      '<my_user_id>',
      request
  );
  ```

  ```java Java
  import com.vital.api.Vital;
  import com.vital.api.core.Environment;
  import com.vital.api.resources.vitals.requests.VitalsInhalerUsageGroupedRequest;

  Vital vital = Vital.builder()
          .apiKey("YOUR_API_KEY")
          .environment(Environment.SANDBOX)
          .build();

  VitalsInhalerUsageGroupedRequest request = VitalsInhalerUsageGroupedRequest.builder()
          .startDate("2022-05-01")
          .endDate("2022-06-01")
          .build();

  var data = vital.vitals().inhalerUsageGrouped("<user_id>", request);
  ```

  ```go Go
  import (
    "context"

    vital "github.com/tryVital/vital-go"
    vitalclient "github.com/tryVital/vital-go/client"
  )

  client := vitalclient.NewClient(
    vitalclient.WithApiKey("<YOUR_API_KEY>"),
    vitalclient.WithBaseURL(vital.Environments.Sandbox),
  )

  EndDate := "2022-06-01"
  request := &vital.VitalsInhalerUsageGroupedRequest{
    StartDate: "2022-05-01",
    EndDate:   &EndDate,
  }

  response, err := client.Vitals.InhalerUsageGrouped(context.TODO(), "*", request)
  if err != nil {
    return err
  }
  fmt.Printf("Received data %s\n", response)
  ```
</RequestExample>

<ResponseExample>
  ```json Example
  {
    "groups": {
      "oura": [
        {
          "data": [
            {
              "end": "2023-02-13T14:57:24+00:00",
              "start": "2023-02-13T14:30:52+00:00",
              "timestamp": "2023-02-13T14:30:52+00:00",
              "unit": "count",
              "value": 2
            }
          ],
          "source": {
            "provider": "oura",
            "type": "ring"
          }
        }
      ]
    }
  }
  ```
</ResponseExample>


# Insulin Injection
Source: https://docs.junction.com/api-reference/data/timeseries/insulin-injection

GET /v2/timeseries/{user_id}/insulin_injection/grouped

<Card title="View Full Response Schema »" icon="diamond-turn-right" iconType="sharp-solid" color="#F3A712" href="https://api.tryvital.io/redoc#tag/timeseries/operation/get_insulin_injection_grouped">
  The Response section on the page still needs work. Click here to check out the complete schema.
</Card>

<RequestExample>
  ```bash cURL
  curl --request GET \
       --url {{BASE_URL}}/v2/timeseries/{user_id}/insulin_injection/grouped?start_date={{START_DATE}}&end_date={{END_DATE}} \
       --header 'Accept: application/json' \
       --header 'x-vital-api-key: <API_KEY>'
  ```

  ```python Python
  from vital.client import Vital
  from vital.environment import VitalEnvironment

  client = Vital(
    api_key="YOUR_API_KEY",
    environment=VitalEnvironment.SANDBOX
  )

  data = client.vitals.insulin_injection_grouped(
    user_id="<user_id>", 
    start_date="2021-10-01", 
    end_date="2021-10-02"
  )
  ```

  ```javascript Node
  import { VitalClient, VitalEnvironment } from '@tryvital/vital-node';
  import { VitalsInsulinInjectionGroupedRequest } from '@tryvital/vital-node/api/resources/vitals';

  const client = new VitalClient({
      apiKey: '<my_api_key>',
      environment: VitalEnvironment.Sandbox,
  });

  const request: VitalsInsulinInjectionGroupedRequest = {
      startDate: "2022-05-01",
      endDate: "2022-06-01"
  }

  const data = await client.vitals.insulinInjectionGrouped(
      '<my_user_id>',
      request
  );
  ```

  ```java Java
  import com.vital.api.Vital;
  import com.vital.api.core.Environment;
  import com.vital.api.resources.vitals.requests.VitalsInsulinInjectionGroupedRequest;

  Vital vital = Vital.builder()
          .apiKey("YOUR_API_KEY")
          .environment(Environment.SANDBOX)
          .build();

  VitalsInsulinInjectionGroupedRequest request = VitalsInsulinInjectionGroupedRequest.builder()
          .startDate("2022-05-01")
          .endDate("2022-06-01")
          .build();

  var data = vital.vitals().insulinInjectionGrouped("<user_id>", request);
  ```

  ```go Go
  import (
    "context"

    vital "github.com/tryVital/vital-go"
    vitalclient "github.com/tryVital/vital-go/client"
  )

  client := vitalclient.NewClient(
    vitalclient.WithApiKey("<YOUR_API_KEY>"),
    vitalclient.WithBaseURL(vital.Environments.Sandbox),
  )

  EndDate := "2022-06-01"
  request := &vital.VitalsInsulinInjectionGroupedRequest{
    StartDate: "2022-05-01",
    EndDate:   &EndDate,
  }

  response, err := client.Vitals.InsulinInjectionGrouped(context.TODO(), "*", request)
  if err != nil {
    return err
  }
  fmt.Printf("Received data %s\n", response)
  ```
</RequestExample>

<ResponseExample>
  ```json Example
  {
    "groups": {
      "oura": [
        {
          "data": [
            {
              "end": "2023-02-13T14:30:52+00:00",
              "start": "2023-02-13T14:30:52+00:00",
              "type": "long_acting",
              "unit": "unit",
              "value": 60
            }
          ],
          "source": {
            "provider": "oura",
            "type": "ring"
          }
        }
      ]
    }
  }
  ```
</ResponseExample>


# Lean Body Mass
Source: https://docs.junction.com/api-reference/data/timeseries/lean-body-mass

GET /v2/timeseries/{user_id}/lean_body_mass/grouped

<Card title="View Full Response Schema »" icon="diamond-turn-right" iconType="sharp-solid" color="#F3A712" href="https://api.tryvital.io/redoc#tag/timeseries/operation/get_lean_body_mass_grouped">
  The Response section on the page still needs work. Click here to check out the complete schema.
</Card>

<RequestExample>
  ```bash cURL
  curl --request GET \
       --url {{BASE_URL}}/v2/timeseries/{user_id}/lean_body_mass/grouped?start_date={{START_DATE}}&end_date={{END_DATE}} \
       --header 'Accept: application/json' \
       --header 'x-vital-api-key: <API_KEY>'
  ```

  ```python Python
  from vital.client import Vital
  from vital.environment import VitalEnvironment

  client = Vital(
    api_key="YOUR_API_KEY",
    environment=VitalEnvironment.SANDBOX
  )

  data = client.vitals.lean_body_mass_grouped(
    user_id="<user_id>", 
    start_date="2021-10-01", 
    end_date="2021-10-02"
  )
  ```

  ```javascript Node
  import { VitalClient, VitalEnvironment } from '@tryvital/vital-node';
  import { VitalsLeanBodyMassGroupedRequest } from '@tryvital/vital-node/api/resources/vitals';

  const client = new VitalClient({
      apiKey: '<my_api_key>',
      environment: VitalEnvironment.Sandbox,
  });

  const request: VitalsLeanBodyMassGroupedRequest = {
      startDate: "2022-05-01",
      endDate: "2022-06-01"
  }

  const data = await client.vitals.leanBodyMassGrouped(
      '<my_user_id>',
      request
  );
  ```

  ```java Java
  import com.vital.api.Vital;
  import com.vital.api.core.Environment;
  import com.vital.api.resources.vitals.requests.VitalsLeanBodyMassGroupedRequest;

  Vital vital = Vital.builder()
          .apiKey("YOUR_API_KEY")
          .environment(Environment.SANDBOX)
          .build();

  VitalsLeanBodyMassGroupedRequest request = VitalsLeanBodyMassGroupedRequest.builder()
          .startDate("2022-05-01")
          .endDate("2022-06-01")
          .build();

  var data = vital.vitals().leanBodyMassGrouped("<user_id>", request);
  ```

  ```go Go
  import (
    "context"

    vital "github.com/tryVital/vital-go"
    vitalclient "github.com/tryVital/vital-go/client"
  )

  client := vitalclient.NewClient(
    vitalclient.WithApiKey("<YOUR_API_KEY>"),
    vitalclient.WithBaseURL(vital.Environments.Sandbox),
  )

  EndDate := "2022-06-01"
  request := &vital.VitalsLeanBodyMassGroupedRequest{
    StartDate: "2022-05-01",
    EndDate:   &EndDate,
  }

  response, err := client.Vitals.LeanBodyMassGrouped(context.TODO(), "*", request)
  if err != nil {
    return err
  }
  fmt.Printf("Received data %s\n", response)
  ```
</RequestExample>

<ResponseExample>
  ```json Example
  {
    "groups": {
      "oura": [
        {
          "data": [
            {
              "end": "2023-02-13T14:57:24+00:00",
              "start": "2023-02-13T14:30:52+00:00",
              "timestamp": "2023-02-13T14:30:52+00:00",
              "unit": "kg",
              "value": 50
            }
          ],
          "source": {
            "provider": "oura",
            "type": "ring"
          }
        }
      ]
    }
  }
  ```
</ResponseExample>


# Mindfulness Minutes
Source: https://docs.junction.com/api-reference/data/timeseries/mindfulness-minutes

GET /v2/timeseries/{user_id}/mindfulness_minutes/grouped

<Card title="View Full Response Schema »" icon="diamond-turn-right" iconType="sharp-solid" color="#F3A712" href="https://api.tryvital.io/redoc#tag/timeseries/operation/get_mindfulness_minutes_grouped">
  The Response section on the page still needs work. Click here to check out the complete schema.
</Card>

<RequestExample>
  ```bash cURL
  curl --request GET \
       --url {{BASE_URL}}/v2/timeseries/{user_id}/mindfulness_minutes/grouped?start_date={{START_DATE}}&end_date={{END_DATE}} \
       --header 'Accept: application/json' \
       --header 'x-vital-api-key: <API_KEY>'
  ```

  ```python Python
  from vital.client import Vital
  from vital.environment import VitalEnvironment

  client = Vital(
    api_key="YOUR_API_KEY",
    environment=VitalEnvironment.SANDBOX
  )

  data = client.vitals.mindfulness_minutes_grouped(
    user_id="<user_id>", 
    start_date="2021-10-01", 
    end_date="2021-10-02"
  )
  ```

  ```javascript Node
  import { VitalClient, VitalEnvironment } from '@tryvital/vital-node';
  import { VitalsMindfulnessMinutesGroupedRequest } from '@tryvital/vital-node/api/resources/vitals';

  const client = new VitalClient({
      apiKey: '<my_api_key>',
      environment: VitalEnvironment.Sandbox,
  });

  const request: VitalsMindfulnessMinutesGroupedRequest = {
      startDate: "2022-05-01",
      endDate: "2022-06-01"
  }

  const data = await client.vitals.mindfulnessMinutesGrouped(
      '<my_user_id>',
      request
  );
  ```

  ```java Java
  import com.vital.api.Vital;
  import com.vital.api.core.Environment;
  import com.vital.api.resources.vitals.requests.VitalsMindfulnessMinutesGroupedRequest;

  Vital vital = Vital.builder()
          .apiKey("YOUR_API_KEY")
          .environment(Environment.SANDBOX)
          .build();

  VitalsMindfulnessMinutesGroupedRequest request = VitalsMindfulnessMinutesGroupedRequest.builder()
          .startDate("2022-05-01")
          .endDate("2022-06-01")
          .build();

  var data = vital.vitals().mindfulnessMinutesGrouped("<user_id>", request);
  ```

  ```go Go
  import (
    "context"

    vital "github.com/tryVital/vital-go"
    vitalclient "github.com/tryVital/vital-go/client"
  )

  client := vitalclient.NewClient(
    vitalclient.WithApiKey("<YOUR_API_KEY>"),
    vitalclient.WithBaseURL(vital.Environments.Sandbox),
  )

  EndDate := "2022-06-01"
  request := &vital.VitalsMindfulnessMinutesGroupedRequest{
    StartDate: "2022-05-01",
    EndDate:   &EndDate,
  }

  response, err := client.Vitals.MindfulnessMinutesGrouped(context.TODO(), "*", request)
  if err != nil {
    return err
  }
  fmt.Printf("Received data %s\n", response)
  ```
</RequestExample>

<ResponseExample>
  ```json Example
  {
    "groups": {
      "oura": [
        {
          "data": [
            {
              "end": "2025-08-22T21:47:21.361461+00:00",
              "start": "2023-02-13T14:57:24+00:00",
              "unit": "min",
              "value": 42
            }
          ],
          "source": {
            "provider": "oura",
            "type": "ring"
          }
        }
      ]
    }
  }
  ```
</ResponseExample>


# Note
Source: https://docs.junction.com/api-reference/data/timeseries/note

GET /v2/timeseries/{user_id}/note/grouped

<Card title="View Full Response Schema »" icon="diamond-turn-right" iconType="sharp-solid" color="#F3A712" href="https://api.tryvital.io/redoc#tag/timeseries/operation/get_note_grouped">
  The Response section on the page still needs work. Click here to check out the complete schema.
</Card>

<RequestExample>
  ```bash cURL
  curl --request GET \
       --url {{BASE_URL}}/v2/timeseries/{user_id}/note/grouped?start_date={{START_DATE}}&end_date={{END_DATE}} \
       --header 'Accept: application/json' \
       --header 'x-vital-api-key: <API_KEY>'
  ```

  ```python Python
  from vital.client import Vital
  from vital.environment import VitalEnvironment

  client = Vital(
    api_key="YOUR_API_KEY",
    environment=VitalEnvironment.SANDBOX
  )

  data = client.vitals.note_grouped(
    user_id="<user_id>", 
    start_date="2021-10-01", 
    end_date="2021-10-02"
  )
  ```

  ```javascript Node
  import { VitalClient, VitalEnvironment } from '@tryvital/vital-node';
  import { VitalsNoteGroupedRequest } from '@tryvital/vital-node/api/resources/vitals';

  const client = new VitalClient({
      apiKey: '<my_api_key>',
      environment: VitalEnvironment.Sandbox,
  });

  const request: VitalsNoteGroupedRequest = {
      startDate: "2022-05-01",
      endDate: "2022-06-01"
  }

  const data = await client.vitals.noteGrouped(
      '<my_user_id>',
      request
  );
  ```

  ```java Java
  import com.vital.api.Vital;
  import com.vital.api.core.Environment;
  import com.vital.api.resources.vitals.requests.VitalsNoteGroupedRequest;

  Vital vital = Vital.builder()
          .apiKey("YOUR_API_KEY")
          .environment(Environment.SANDBOX)
          .build();

  VitalsNoteGroupedRequest request = VitalsNoteGroupedRequest.builder()
          .startDate("2022-05-01")
          .endDate("2022-06-01")
          .build();

  var data = vital.vitals().noteGrouped("<user_id>", request);
  ```

  ```go Go
  import (
    "context"

    vital "github.com/tryVital/vital-go"
    vitalclient "github.com/tryVital/vital-go/client"
  )

  client := vitalclient.NewClient(
    vitalclient.WithApiKey("<YOUR_API_KEY>"),
    vitalclient.WithBaseURL(vital.Environments.Sandbox),
  )

  EndDate := "2022-06-01"
  request := &vital.VitalsNoteGroupedRequest{
    StartDate: "2022-05-01",
    EndDate:   &EndDate,
  }

  response, err := client.Vitals.NoteGrouped(context.TODO(), "*", request)
  if err != nil {
    return err
  }
  fmt.Printf("Received data %s\n", response)
  ```
</RequestExample>

<ResponseExample>
  ```json Example
  {
    "groups": {
      "oura": [
        {
          "data": [
            {
              "end": "2023-02-13T14:30:52+00:00",
              "start": "2023-02-13T14:30:52+00:00",
              "tags": [
                "food",
                "exercise"
              ],
              "unit": "text",
              "value": "Lorem ipsum dolor sit amet"
            }
          ],
          "source": {
            "provider": "oura",
            "type": "ring"
          }
        }
      ]
    }
  }
  ```
</ResponseExample>


# Peak Expiratory Flow Rate
Source: https://docs.junction.com/api-reference/data/timeseries/peak-expiratory-flow-rate

GET /v2/timeseries/{user_id}/peak_expiratory_flow_rate/grouped

<Card title="View Full Response Schema »" icon="diamond-turn-right" iconType="sharp-solid" color="#F3A712" href="https://api.tryvital.io/redoc#tag/timeseries/operation/get_peak_expiratory_flow_rate_grouped">
  The Response section on the page still needs work. Click here to check out the complete schema.
</Card>

<RequestExample>
  ```bash cURL
  curl --request GET \
       --url {{BASE_URL}}/v2/timeseries/{user_id}/peak_expiratory_flow_rate/grouped?start_date={{START_DATE}}&end_date={{END_DATE}} \
       --header 'Accept: application/json' \
       --header 'x-vital-api-key: <API_KEY>'
  ```

  ```python Python
  from vital.client import Vital
  from vital.environment import VitalEnvironment

  client = Vital(
    api_key="YOUR_API_KEY",
    environment=VitalEnvironment.SANDBOX
  )

  data = client.vitals.peak_expiratory_flow_rate_grouped(
    user_id="<user_id>", 
    start_date="2021-10-01", 
    end_date="2021-10-02"
  )
  ```

  ```javascript Node
  import { VitalClient, VitalEnvironment } from '@tryvital/vital-node';
  import { VitalsPeakExpiratoryFlowRateGroupedRequest } from '@tryvital/vital-node/api/resources/vitals';

  const client = new VitalClient({
      apiKey: '<my_api_key>',
      environment: VitalEnvironment.Sandbox,
  });

  const request: VitalsPeakExpiratoryFlowRateGroupedRequest = {
      startDate: "2022-05-01",
      endDate: "2022-06-01"
  }

  const data = await client.vitals.peakExpiratoryFlowRateGrouped(
      '<my_user_id>',
      request
  );
  ```

  ```java Java
  import com.vital.api.Vital;
  import com.vital.api.core.Environment;
  import com.vital.api.resources.vitals.requests.VitalsPeakExpiratoryFlowRateGroupedRequest;

  Vital vital = Vital.builder()
          .apiKey("YOUR_API_KEY")
          .environment(Environment.SANDBOX)
          .build();

  VitalsPeakExpiratoryFlowRateGroupedRequest request = VitalsPeakExpiratoryFlowRateGroupedRequest.builder()
          .startDate("2022-05-01")
          .endDate("2022-06-01")
          .build();

  var data = vital.vitals().peakExpiratoryFlowRateGrouped("<user_id>", request);
  ```

  ```go Go
  import (
    "context"

    vital "github.com/tryVital/vital-go"
    vitalclient "github.com/tryVital/vital-go/client"
  )

  client := vitalclient.NewClient(
    vitalclient.WithApiKey("<YOUR_API_KEY>"),
    vitalclient.WithBaseURL(vital.Environments.Sandbox),
  )

  EndDate := "2022-06-01"
  request := &vital.VitalsPeakExpiratoryFlowRateGroupedRequest{
    StartDate: "2022-05-01",
    EndDate:   &EndDate,
  }

  response, err := client.Vitals.PeakExpiratoryFlowRateGrouped(context.TODO(), "*", request)
  if err != nil {
    return err
  }
  fmt.Printf("Received data %s\n", response)
  ```
</RequestExample>

<ResponseExample>
  ```json Example
  {
    "groups": {
      "oura": [
        {
          "data": [
            {
              "end": "2023-02-13T14:57:24+00:00",
              "start": "2023-02-13T14:30:52+00:00",
              "timestamp": "2023-02-13T14:30:52+00:00",
              "unit": "L/min",
              "value": 450
            }
          ],
          "source": {
            "provider": "oura",
            "type": "ring"
          }
        }
      ]
    }
  }
  ```
</ResponseExample>


# Respiratory Rate
Source: https://docs.junction.com/api-reference/data/timeseries/respiratory-rate

GET /v2/timeseries/{user_id}/respiratory_rate/grouped

<Card title="View Full Response Schema »" icon="diamond-turn-right" iconType="sharp-solid" color="#F3A712" href="https://api.tryvital.io/redoc#tag/timeseries/operation/get_respiratory_rate_grouped">
  The Response section on the page still needs work. Click here to check out the complete schema.
</Card>

<RequestExample>
  ```bash cURL
  curl --request GET \
       --url {{BASE_URL}}/v2/timeseries/{user_id}/respiratory_rate/grouped?start_date={{START_DATE}}&end_date={{END_DATE}} \
       --header 'Accept: application/json' \
       --header 'x-vital-api-key: <API_KEY>'
  ```

  ```python Python
  from vital.client import Vital
  from vital.environment import VitalEnvironment

  client = Vital(
    api_key="YOUR_API_KEY",
    environment=VitalEnvironment.SANDBOX
  )

  data = client.vitals.respiratory_rate_grouped(
    user_id="<user_id>", 
    start_date="2021-10-01", 
    end_date="2021-10-02"
  )
  ```

  ```javascript Node
  import { VitalClient, VitalEnvironment } from '@tryvital/vital-node';
  import { VitalsRespiratoryRateGroupedRequest } from '@tryvital/vital-node/api/resources/vitals';

  const client = new VitalClient({
      apiKey: '<my_api_key>',
      environment: VitalEnvironment.Sandbox,
  });

  const request: VitalsRespiratoryRateGroupedRequest = {
      startDate: "2022-05-01",
      endDate: "2022-06-01"
  }

  const data = await client.vitals.respiratoryRateGrouped(
      '<my_user_id>',
      request
  );
  ```

  ```java Java
  import com.vital.api.Vital;
  import com.vital.api.core.Environment;
  import com.vital.api.resources.vitals.requests.VitalsRespiratoryRateGroupedRequest;

  Vital vital = Vital.builder()
          .apiKey("YOUR_API_KEY")
          .environment(Environment.SANDBOX)
          .build();

  VitalsRespiratoryRateGroupedRequest request = VitalsRespiratoryRateGroupedRequest.builder()
          .startDate("2022-05-01")
          .endDate("2022-06-01")
          .build();

  var data = vital.vitals().respiratoryRateGrouped("<user_id>", request);
  ```

  ```go Go
  import (
    "context"

    vital "github.com/tryVital/vital-go"
    vitalclient "github.com/tryVital/vital-go/client"
  )

  client := vitalclient.NewClient(
    vitalclient.WithApiKey("<YOUR_API_KEY>"),
    vitalclient.WithBaseURL(vital.Environments.Sandbox),
  )

  EndDate := "2022-06-01"
  request := &vital.VitalsRespiratoryRateGroupedRequest{
    StartDate: "2022-05-01",
    EndDate:   &EndDate,
  }

  response, err := client.Vitals.RespiratoryRateGrouped(context.TODO(), "*", request)
  if err != nil {
    return err
  }
  fmt.Printf("Received data %s\n", response)
  ```
</RequestExample>

<ResponseExample>
  ```json Example
  {
    "groups": {
      "oura": [
        {
          "data": [
            {
              "timestamp": "2023-02-13T14:30:52+00:00",
              "unit": "bpm",
              "value": 15.5
            }
          ],
          "source": {
            "provider": "oura",
            "type": "ring"
          }
        }
      ]
    }
  }
  ```
</ResponseExample>


# Sleep Apnea Alert
Source: https://docs.junction.com/api-reference/data/timeseries/sleep-apnea-alert

GET /v2/timeseries/{user_id}/sleep_apnea_alert/grouped

<Card title="View Full Response Schema »" icon="diamond-turn-right" iconType="sharp-solid" color="#F3A712" href="https://api.tryvital.io/redoc#tag/timeseries/operation/get_sleep_apnea_alert_grouped">
  The Response section on the page still needs work. Click here to check out the complete schema.
</Card>

<RequestExample>
  ```bash cURL
  curl --request GET \
       --url {{BASE_URL}}/v2/timeseries/{user_id}/sleep_apnea_alert/grouped?start_date={{START_DATE}}&end_date={{END_DATE}} \
       --header 'Accept: application/json' \
       --header 'x-vital-api-key: <API_KEY>'
  ```

  ```python Python
  from vital.client import Vital
  from vital.environment import VitalEnvironment

  client = Vital(
    api_key="YOUR_API_KEY",
    environment=VitalEnvironment.SANDBOX
  )

  data = client.vitals.sleep_apnea_alert_grouped(
    user_id="<user_id>", 
    start_date="2021-10-01", 
    end_date="2021-10-02"
  )
  ```

  ```javascript Node
  import { VitalClient, VitalEnvironment } from '@tryvital/vital-node';
  import { VitalsSleepApneaAlertGroupedRequest } from '@tryvital/vital-node/api/resources/vitals';

  const client = new VitalClient({
      apiKey: '<my_api_key>',
      environment: VitalEnvironment.Sandbox,
  });

  const request: VitalsSleepApneaAlertGroupedRequest = {
      startDate: "2022-05-01",
      endDate: "2022-06-01"
  }

  const data = await client.vitals.sleepApneaAlertGrouped(
      '<my_user_id>',
      request
  );
  ```

  ```java Java
  import com.vital.api.Vital;
  import com.vital.api.core.Environment;
  import com.vital.api.resources.vitals.requests.VitalsSleepApneaAlertGroupedRequest;

  Vital vital = Vital.builder()
          .apiKey("YOUR_API_KEY")
          .environment(Environment.SANDBOX)
          .build();

  VitalsSleepApneaAlertGroupedRequest request = VitalsSleepApneaAlertGroupedRequest.builder()
          .startDate("2022-05-01")
          .endDate("2022-06-01")
          .build();

  var data = vital.vitals().sleepApneaAlertGrouped("<user_id>", request);
  ```

  ```go Go
  import (
    "context"

    vital "github.com/tryVital/vital-go"
    vitalclient "github.com/tryVital/vital-go/client"
  )

  client := vitalclient.NewClient(
    vitalclient.WithApiKey("<YOUR_API_KEY>"),
    vitalclient.WithBaseURL(vital.Environments.Sandbox),
  )

  EndDate := "2022-06-01"
  request := &vital.VitalsSleepApneaAlertGroupedRequest{
    StartDate: "2022-05-01",
    EndDate:   &EndDate,
  }

  response, err := client.Vitals.SleepApneaAlertGrouped(context.TODO(), "*", request)
  if err != nil {
    return err
  }
  fmt.Printf("Received data %s\n", response)
  ```
</RequestExample>

<ResponseExample>
  ```json Example
  {
    "groups": {
      "oura": [
        {
          "data": [
            {
              "end": "2023-02-13T14:57:24+00:00",
              "start": "2023-02-13T14:30:52+00:00",
              "timestamp": "2023-02-13T14:30:52+00:00",
              "unit": "count",
              "value": 1
            }
          ],
          "source": {
            "provider": "oura",
            "type": "ring"
          }
        }
      ]
    }
  }
  ```
</ResponseExample>


# Sleep Breathing Disturbance
Source: https://docs.junction.com/api-reference/data/timeseries/sleep-breathing-disturbance

GET /v2/timeseries/{user_id}/sleep_breathing_disturbance/grouped

<Card title="View Full Response Schema »" icon="diamond-turn-right" iconType="sharp-solid" color="#F3A712" href="https://api.tryvital.io/redoc#tag/timeseries/operation/get_sleep_breathing_disturbance_grouped">
  The Response section on the page still needs work. Click here to check out the complete schema.
</Card>

<RequestExample>
  ```bash cURL
  curl --request GET \
       --url {{BASE_URL}}/v2/timeseries/{user_id}/sleep_breathing_disturbance/grouped?start_date={{START_DATE}}&end_date={{END_DATE}} \
       --header 'Accept: application/json' \
       --header 'x-vital-api-key: <API_KEY>'
  ```

  ```python Python
  from vital.client import Vital
  from vital.environment import VitalEnvironment

  client = Vital(
    api_key="YOUR_API_KEY",
    environment=VitalEnvironment.SANDBOX
  )

  data = client.vitals.sleep_breathing_disturbance_grouped(
    user_id="<user_id>", 
    start_date="2021-10-01", 
    end_date="2021-10-02"
  )
  ```

  ```javascript Node
  import { VitalClient, VitalEnvironment } from '@tryvital/vital-node';
  import { VitalsSleepBreathingDisturbanceGroupedRequest } from '@tryvital/vital-node/api/resources/vitals';

  const client = new VitalClient({
      apiKey: '<my_api_key>',
      environment: VitalEnvironment.Sandbox,
  });

  const request: VitalsSleepBreathingDisturbanceGroupedRequest = {
      startDate: "2022-05-01",
      endDate: "2022-06-01"
  }

  const data = await client.vitals.sleepBreathingDisturbanceGrouped(
      '<my_user_id>',
      request
  );
  ```

  ```java Java
  import com.vital.api.Vital;
  import com.vital.api.core.Environment;
  import com.vital.api.resources.vitals.requests.VitalsSleepBreathingDisturbanceGroupedRequest;

  Vital vital = Vital.builder()
          .apiKey("YOUR_API_KEY")
          .environment(Environment.SANDBOX)
          .build();

  VitalsSleepBreathingDisturbanceGroupedRequest request = VitalsSleepBreathingDisturbanceGroupedRequest.builder()
          .startDate("2022-05-01")
          .endDate("2022-06-01")
          .build();

  var data = vital.vitals().sleepBreathingDisturbanceGrouped("<user_id>", request);
  ```

  ```go Go
  import (
    "context"

    vital "github.com/tryVital/vital-go"
    vitalclient "github.com/tryVital/vital-go/client"
  )

  client := vitalclient.NewClient(
    vitalclient.WithApiKey("<YOUR_API_KEY>"),
    vitalclient.WithBaseURL(vital.Environments.Sandbox),
  )

  EndDate := "2022-06-01"
  request := &vital.VitalsSleepBreathingDisturbanceGroupedRequest{
    StartDate: "2022-05-01",
    EndDate:   &EndDate,
  }

  response, err := client.Vitals.SleepBreathingDisturbanceGrouped(context.TODO(), "*", request)
  if err != nil {
    return err
  }
  fmt.Printf("Received data %s\n", response)
  ```
</RequestExample>

<ResponseExample>
  ```json Example
  {
    "groups": {
      "oura": [
        {
          "data": [
            {
              "end": "2023-02-13T14:57:24+00:00",
              "start": "2023-02-13T14:30:52+00:00",
              "timestamp": "2023-02-13T14:30:52+00:00",
              "type": "elevated",
              "unit": "count",
              "value": 12
            }
          ],
          "source": {
            "provider": "oura",
            "type": "ring"
          }
        }
      ]
    }
  }
  ```
</ResponseExample>


# Stand Duration
Source: https://docs.junction.com/api-reference/data/timeseries/stand-duration

GET /v2/timeseries/{user_id}/stand_duration/grouped

<Card title="View Full Response Schema »" icon="diamond-turn-right" iconType="sharp-solid" color="#F3A712" href="https://api.tryvital.io/redoc#tag/timeseries/operation/get_stand_duration_grouped">
  The Response section on the page still needs work. Click here to check out the complete schema.
</Card>

<RequestExample>
  ```bash cURL
  curl --request GET \
       --url {{BASE_URL}}/v2/timeseries/{user_id}/stand_duration/grouped?start_date={{START_DATE}}&end_date={{END_DATE}} \
       --header 'Accept: application/json' \
       --header 'x-vital-api-key: <API_KEY>'
  ```

  ```python Python
  from vital.client import Vital
  from vital.environment import VitalEnvironment

  client = Vital(
    api_key="YOUR_API_KEY",
    environment=VitalEnvironment.SANDBOX
  )

  data = client.vitals.stand_duration_grouped(
    user_id="<user_id>", 
    start_date="2021-10-01", 
    end_date="2021-10-02"
  )
  ```

  ```javascript Node
  import { VitalClient, VitalEnvironment } from '@tryvital/vital-node';
  import { VitalsStandDurationGroupedRequest } from '@tryvital/vital-node/api/resources/vitals';

  const client = new VitalClient({
      apiKey: '<my_api_key>',
      environment: VitalEnvironment.Sandbox,
  });

  const request: VitalsStandDurationGroupedRequest = {
      startDate: "2022-05-01",
      endDate: "2022-06-01"
  }

  const data = await client.vitals.standDurationGrouped(
      '<my_user_id>',
      request
  );
  ```

  ```java Java
  import com.vital.api.Vital;
  import com.vital.api.core.Environment;
  import com.vital.api.resources.vitals.requests.VitalsStandDurationGroupedRequest;

  Vital vital = Vital.builder()
          .apiKey("YOUR_API_KEY")
          .environment(Environment.SANDBOX)
          .build();

  VitalsStandDurationGroupedRequest request = VitalsStandDurationGroupedRequest.builder()
          .startDate("2022-05-01")
          .endDate("2022-06-01")
          .build();

  var data = vital.vitals().standDurationGrouped("<user_id>", request);
  ```

  ```go Go
  import (
    "context"

    vital "github.com/tryVital/vital-go"
    vitalclient "github.com/tryVital/vital-go/client"
  )

  client := vitalclient.NewClient(
    vitalclient.WithApiKey("<YOUR_API_KEY>"),
    vitalclient.WithBaseURL(vital.Environments.Sandbox),
  )

  EndDate := "2022-06-01"
  request := &vital.VitalsStandDurationGroupedRequest{
    StartDate: "2022-05-01",
    EndDate:   &EndDate,
  }

  response, err := client.Vitals.StandDurationGrouped(context.TODO(), "*", request)
  if err != nil {
    return err
  }
  fmt.Printf("Received data %s\n", response)
  ```
</RequestExample>

<ResponseExample>
  ```json Example
  {
    "groups": {
      "oura": [
        {
          "data": [
            {
              "end": "2023-02-13T14:57:24+00:00",
              "start": "2023-02-13T14:30:52+00:00",
              "timestamp": "2023-02-13T14:30:52+00:00",
              "unit": "min",
              "value": 15
            }
          ],
          "source": {
            "provider": "oura",
            "type": "ring"
          }
        }
      ]
    }
  }
  ```
</ResponseExample>


# Stand Hour
Source: https://docs.junction.com/api-reference/data/timeseries/stand-hour

GET /v2/timeseries/{user_id}/stand_hour/grouped

<Card title="View Full Response Schema »" icon="diamond-turn-right" iconType="sharp-solid" color="#F3A712" href="https://api.tryvital.io/redoc#tag/timeseries/operation/get_stand_hour_grouped">
  The Response section on the page still needs work. Click here to check out the complete schema.
</Card>

<RequestExample>
  ```bash cURL
  curl --request GET \
       --url {{BASE_URL}}/v2/timeseries/{user_id}/stand_hour/grouped?start_date={{START_DATE}}&end_date={{END_DATE}} \
       --header 'Accept: application/json' \
       --header 'x-vital-api-key: <API_KEY>'
  ```

  ```python Python
  from vital.client import Vital
  from vital.environment import VitalEnvironment

  client = Vital(
    api_key="YOUR_API_KEY",
    environment=VitalEnvironment.SANDBOX
  )

  data = client.vitals.stand_hour_grouped(
    user_id="<user_id>", 
    start_date="2021-10-01", 
    end_date="2021-10-02"
  )
  ```

  ```javascript Node
  import { VitalClient, VitalEnvironment } from '@tryvital/vital-node';
  import { VitalsStandHourGroupedRequest } from '@tryvital/vital-node/api/resources/vitals';

  const client = new VitalClient({
      apiKey: '<my_api_key>',
      environment: VitalEnvironment.Sandbox,
  });

  const request: VitalsStandHourGroupedRequest = {
      startDate: "2022-05-01",
      endDate: "2022-06-01"
  }

  const data = await client.vitals.standHourGrouped(
      '<my_user_id>',
      request
  );
  ```

  ```java Java
  import com.vital.api.Vital;
  import com.vital.api.core.Environment;
  import com.vital.api.resources.vitals.requests.VitalsStandHourGroupedRequest;

  Vital vital = Vital.builder()
          .apiKey("YOUR_API_KEY")
          .environment(Environment.SANDBOX)
          .build();

  VitalsStandHourGroupedRequest request = VitalsStandHourGroupedRequest.builder()
          .startDate("2022-05-01")
          .endDate("2022-06-01")
          .build();

  var data = vital.vitals().standHourGrouped("<user_id>", request);
  ```

  ```go Go
  import (
    "context"

    vital "github.com/tryVital/vital-go"
    vitalclient "github.com/tryVital/vital-go/client"
  )

  client := vitalclient.NewClient(
    vitalclient.WithApiKey("<YOUR_API_KEY>"),
    vitalclient.WithBaseURL(vital.Environments.Sandbox),
  )

  EndDate := "2022-06-01"
  request := &vital.VitalsStandHourGroupedRequest{
    StartDate: "2022-05-01",
    EndDate:   &EndDate,
  }

  response, err := client.Vitals.StandHourGrouped(context.TODO(), "*", request)
  if err != nil {
    return err
  }
  fmt.Printf("Received data %s\n", response)
  ```
</RequestExample>

<ResponseExample>
  ```json Example
  {
    "groups": {
      "oura": [
        {
          "data": [
            {
              "end": "2023-02-13T14:57:24+00:00",
              "start": "2023-02-13T14:30:52+00:00",
              "timestamp": "2023-02-13T14:30:52+00:00",
              "unit": "count",
              "value": 1
            }
          ],
          "source": {
            "provider": "oura",
            "type": "ring"
          }
        }
      ]
    }
  }
  ```
</ResponseExample>


# Steps
Source: https://docs.junction.com/api-reference/data/timeseries/steps

GET /v2/timeseries/{user_id}/steps/grouped

<Card title="View Full Response Schema »" icon="diamond-turn-right" iconType="sharp-solid" color="#F3A712" href="https://api.tryvital.io/redoc#tag/timeseries/operation/get_steps_grouped">
  The Response section on the page still needs work. Click here to check out the complete schema.
</Card>

<RequestExample>
  ```bash cURL
  curl --request GET \
       --url {{BASE_URL}}/v2/timeseries/{user_id}/steps/grouped?start_date={{START_DATE}}&end_date={{END_DATE}} \
       --header 'Accept: application/json' \
       --header 'x-vital-api-key: <API_KEY>'
  ```

  ```python Python
  from vital.client import Vital
  from vital.environment import VitalEnvironment

  client = Vital(
    api_key="YOUR_API_KEY",
    environment=VitalEnvironment.SANDBOX
  )

  data = client.vitals.steps_grouped(
    user_id="<user_id>", 
    start_date="2021-10-01", 
    end_date="2021-10-02"
  )
  ```

  ```javascript Node
  import { VitalClient, VitalEnvironment } from '@tryvital/vital-node';
  import { VitalsStepsGroupedRequest } from '@tryvital/vital-node/api/resources/vitals';

  const client = new VitalClient({
      apiKey: '<my_api_key>',
      environment: VitalEnvironment.Sandbox,
  });

  const request: VitalsStepsGroupedRequest = {
      startDate: "2022-05-01",
      endDate: "2022-06-01"
  }

  const data = await client.vitals.stepsGrouped(
      '<my_user_id>',
      request
  );
  ```

  ```java Java
  import com.vital.api.Vital;
  import com.vital.api.core.Environment;
  import com.vital.api.resources.vitals.requests.VitalsStepsGroupedRequest;

  Vital vital = Vital.builder()
          .apiKey("YOUR_API_KEY")
          .environment(Environment.SANDBOX)
          .build();

  VitalsStepsGroupedRequest request = VitalsStepsGroupedRequest.builder()
          .startDate("2022-05-01")
          .endDate("2022-06-01")
          .build();

  var data = vital.vitals().stepsGrouped("<user_id>", request);
  ```

  ```go Go
  import (
    "context"

    vital "github.com/tryVital/vital-go"
    vitalclient "github.com/tryVital/vital-go/client"
  )

  client := vitalclient.NewClient(
    vitalclient.WithApiKey("<YOUR_API_KEY>"),
    vitalclient.WithBaseURL(vital.Environments.Sandbox),
  )

  EndDate := "2022-06-01"
  request := &vital.VitalsStepsGroupedRequest{
    StartDate: "2022-05-01",
    EndDate:   &EndDate,
  }

  response, err := client.Vitals.StepsGrouped(context.TODO(), "*", request)
  if err != nil {
    return err
  }
  fmt.Printf("Received data %s\n", response)
  ```
</RequestExample>

<ResponseExample>
  ```json Example
  {
    "groups": {
      "oura": [
        {
          "data": [
            {
              "end": "2023-02-13T14:57:24+00:00",
              "start": "2023-02-13T14:30:52+00:00",
              "unit": "count",
              "value": 123
            }
          ],
          "source": {
            "provider": "oura",
            "type": "ring"
          }
        }
      ]
    }
  }
  ```
</ResponseExample>


# Stress Level
Source: https://docs.junction.com/api-reference/data/timeseries/stress-level

GET /v2/timeseries/{user_id}/stress_level/grouped

<Card title="View Full Response Schema »" icon="diamond-turn-right" iconType="sharp-solid" color="#F3A712" href="https://api.tryvital.io/redoc#tag/timeseries/operation/get_stress_level_grouped">
  The Response section on the page still needs work. Click here to check out the complete schema.
</Card>

<RequestExample>
  ```bash cURL
  curl --request GET \
       --url {{BASE_URL}}/v2/timeseries/{user_id}/stress_level/grouped?start_date={{START_DATE}}&end_date={{END_DATE}} \
       --header 'Accept: application/json' \
       --header 'x-vital-api-key: <API_KEY>'
  ```

  ```python Python
  from vital.client import Vital
  from vital.environment import VitalEnvironment

  client = Vital(
    api_key="YOUR_API_KEY",
    environment=VitalEnvironment.SANDBOX
  )

  data = client.vitals.stress_level_grouped(
    user_id="<user_id>", 
    start_date="2021-10-01", 
    end_date="2021-10-02"
  )
  ```

  ```javascript Node
  import { VitalClient, VitalEnvironment } from '@tryvital/vital-node';
  import { VitalsStressLevelGroupedRequest } from '@tryvital/vital-node/api/resources/vitals';

  const client = new VitalClient({
      apiKey: '<my_api_key>',
      environment: VitalEnvironment.Sandbox,
  });

  const request: VitalsStressLevelGroupedRequest = {
      startDate: "2022-05-01",
      endDate: "2022-06-01"
  }

  const data = await client.vitals.stressLevelGrouped(
      '<my_user_id>',
      request
  );
  ```

  ```java Java
  import com.vital.api.Vital;
  import com.vital.api.core.Environment;
  import com.vital.api.resources.vitals.requests.VitalsStressLevelGroupedRequest;

  Vital vital = Vital.builder()
          .apiKey("YOUR_API_KEY")
          .environment(Environment.SANDBOX)
          .build();

  VitalsStressLevelGroupedRequest request = VitalsStressLevelGroupedRequest.builder()
          .startDate("2022-05-01")
          .endDate("2022-06-01")
          .build();

  var data = vital.vitals().stressLevelGrouped("<user_id>", request);
  ```

  ```go Go
  import (
    "context"

    vital "github.com/tryVital/vital-go"
    vitalclient "github.com/tryVital/vital-go/client"
  )

  client := vitalclient.NewClient(
    vitalclient.WithApiKey("<YOUR_API_KEY>"),
    vitalclient.WithBaseURL(vital.Environments.Sandbox),
  )

  EndDate := "2022-06-01"
  request := &vital.VitalsStressLevelGroupedRequest{
    StartDate: "2022-05-01",
    EndDate:   &EndDate,
  }

  response, err := client.Vitals.StressLevelGrouped(context.TODO(), "*", request)
  if err != nil {
    return err
  }
  fmt.Printf("Received data %s\n", response)
  ```
</RequestExample>

<ResponseExample>
  ```json Example
  {
    "groups": {
      "oura": [
        {
          "data": [
            {
              "timestamp": "2023-02-13T14:30:52+00:00",
              "unit": "%",
              "value": 35
            }
          ],
          "source": {
            "provider": "oura",
            "type": "ring"
          }
        }
      ]
    }
  }
  ```
</ResponseExample>


# Uv Exposure
Source: https://docs.junction.com/api-reference/data/timeseries/uv-exposure

GET /v2/timeseries/{user_id}/uv_exposure/grouped

<Card title="View Full Response Schema »" icon="diamond-turn-right" iconType="sharp-solid" color="#F3A712" href="https://api.tryvital.io/redoc#tag/timeseries/operation/get_uv_exposure_grouped">
  The Response section on the page still needs work. Click here to check out the complete schema.
</Card>

<RequestExample>
  ```bash cURL
  curl --request GET \
       --url {{BASE_URL}}/v2/timeseries/{user_id}/uv_exposure/grouped?start_date={{START_DATE}}&end_date={{END_DATE}} \
       --header 'Accept: application/json' \
       --header 'x-vital-api-key: <API_KEY>'
  ```

  ```python Python
  from vital.client import Vital
  from vital.environment import VitalEnvironment

  client = Vital(
    api_key="YOUR_API_KEY",
    environment=VitalEnvironment.SANDBOX
  )

  data = client.vitals.uv_exposure_grouped(
    user_id="<user_id>", 
    start_date="2021-10-01", 
    end_date="2021-10-02"
  )
  ```

  ```javascript Node
  import { VitalClient, VitalEnvironment } from '@tryvital/vital-node';
  import { VitalsUvExposureGroupedRequest } from '@tryvital/vital-node/api/resources/vitals';

  const client = new VitalClient({
      apiKey: '<my_api_key>',
      environment: VitalEnvironment.Sandbox,
  });

  const request: VitalsUvExposureGroupedRequest = {
      startDate: "2022-05-01",
      endDate: "2022-06-01"
  }

  const data = await client.vitals.uvExposureGrouped(
      '<my_user_id>',
      request
  );
  ```

  ```java Java
  import com.vital.api.Vital;
  import com.vital.api.core.Environment;
  import com.vital.api.resources.vitals.requests.VitalsUvExposureGroupedRequest;

  Vital vital = Vital.builder()
          .apiKey("YOUR_API_KEY")
          .environment(Environment.SANDBOX)
          .build();

  VitalsUvExposureGroupedRequest request = VitalsUvExposureGroupedRequest.builder()
          .startDate("2022-05-01")
          .endDate("2022-06-01")
          .build();

  var data = vital.vitals().uvExposureGrouped("<user_id>", request);
  ```

  ```go Go
  import (
    "context"

    vital "github.com/tryVital/vital-go"
    vitalclient "github.com/tryVital/vital-go/client"
  )

  client := vitalclient.NewClient(
    vitalclient.WithApiKey("<YOUR_API_KEY>"),
    vitalclient.WithBaseURL(vital.Environments.Sandbox),
  )

  EndDate := "2022-06-01"
  request := &vital.VitalsUvExposureGroupedRequest{
    StartDate: "2022-05-01",
    EndDate:   &EndDate,
  }

  response, err := client.Vitals.UvExposureGrouped(context.TODO(), "*", request)
  if err != nil {
    return err
  }
  fmt.Printf("Received data %s\n", response)
  ```
</RequestExample>

<ResponseExample>
  ```json Example
  {
    "groups": {
      "oura": [
        {
          "data": [
            {
              "end": "2023-02-13T14:57:24+00:00",
              "start": "2023-02-13T14:30:52+00:00",
              "timestamp": "2023-02-13T14:30:52+00:00",
              "unit": "index",
              "value": 5
            }
          ],
          "source": {
            "provider": "oura",
            "type": "ring"
          }
        }
      ]
    }
  }
  ```
</ResponseExample>


# Vo2 Max
Source: https://docs.junction.com/api-reference/data/timeseries/vo2-max

GET /v2/timeseries/{user_id}/vo2_max/grouped

<Card title="View Full Response Schema »" icon="diamond-turn-right" iconType="sharp-solid" color="#F3A712" href="https://api.tryvital.io/redoc#tag/timeseries/operation/get_vo2_max_grouped">
  The Response section on the page still needs work. Click here to check out the complete schema.
</Card>

<RequestExample>
  ```bash cURL
  curl --request GET \
       --url {{BASE_URL}}/v2/timeseries/{user_id}/vo2_max/grouped?start_date={{START_DATE}}&end_date={{END_DATE}} \
       --header 'Accept: application/json' \
       --header 'x-vital-api-key: <API_KEY>'
  ```

  ```python Python
  from vital.client import Vital
  from vital.environment import VitalEnvironment

  client = Vital(
    api_key="YOUR_API_KEY",
    environment=VitalEnvironment.SANDBOX
  )

  data = client.vitals.vo2_max_grouped(
    user_id="<user_id>", 
    start_date="2021-10-01", 
    end_date="2021-10-02"
  )
  ```

  ```javascript Node
  import { VitalClient, VitalEnvironment } from '@tryvital/vital-node';
  import { VitalsVo2MaxGroupedRequest } from '@tryvital/vital-node/api/resources/vitals';

  const client = new VitalClient({
      apiKey: '<my_api_key>',
      environment: VitalEnvironment.Sandbox,
  });

  const request: VitalsVo2MaxGroupedRequest = {
      startDate: "2022-05-01",
      endDate: "2022-06-01"
  }

  const data = await client.vitals.vo2MaxGrouped(
      '<my_user_id>',
      request
  );
  ```

  ```java Java
  import com.vital.api.Vital;
  import com.vital.api.core.Environment;
  import com.vital.api.resources.vitals.requests.VitalsVo2MaxGroupedRequest;

  Vital vital = Vital.builder()
          .apiKey("YOUR_API_KEY")
          .environment(Environment.SANDBOX)
          .build();

  VitalsVo2MaxGroupedRequest request = VitalsVo2MaxGroupedRequest.builder()
          .startDate("2022-05-01")
          .endDate("2022-06-01")
          .build();

  var data = vital.vitals().vo2MaxGrouped("<user_id>", request);
  ```

  ```go Go
  import (
    "context"

    vital "github.com/tryVital/vital-go"
    vitalclient "github.com/tryVital/vital-go/client"
  )

  client := vitalclient.NewClient(
    vitalclient.WithApiKey("<YOUR_API_KEY>"),
    vitalclient.WithBaseURL(vital.Environments.Sandbox),
  )

  EndDate := "2022-06-01"
  request := &vital.VitalsVo2MaxGroupedRequest{
    StartDate: "2022-05-01",
    EndDate:   &EndDate,
  }

  response, err := client.Vitals.Vo2MaxGrouped(context.TODO(), "*", request)
  if err != nil {
    return err
  }
  fmt.Printf("Received data %s\n", response)
  ```
</RequestExample>

<ResponseExample>
  ```json Example
  {
    "groups": {
      "oura": [
        {
          "data": [
            {
              "end": "2023-02-13T14:57:24+00:00",
              "start": "2023-02-13T14:30:52+00:00",
              "unit": "mL/kg/min",
              "value": 48
            }
          ],
          "source": {
            "provider": "oura",
            "type": "ring"
          }
        }
      ]
    }
  }
  ```
</ResponseExample>


# Waist Circumference
Source: https://docs.junction.com/api-reference/data/timeseries/waist-circumference

GET /v2/timeseries/{user_id}/waist_circumference/grouped

<Card title="View Full Response Schema »" icon="diamond-turn-right" iconType="sharp-solid" color="#F3A712" href="https://api.tryvital.io/redoc#tag/timeseries/operation/get_waist_circumference_grouped">
  The Response section on the page still needs work. Click here to check out the complete schema.
</Card>

<RequestExample>
  ```bash cURL
  curl --request GET \
       --url {{BASE_URL}}/v2/timeseries/{user_id}/waist_circumference/grouped?start_date={{START_DATE}}&end_date={{END_DATE}} \
       --header 'Accept: application/json' \
       --header 'x-vital-api-key: <API_KEY>'
  ```

  ```python Python
  from vital.client import Vital
  from vital.environment import VitalEnvironment

  client = Vital(
    api_key="YOUR_API_KEY",
    environment=VitalEnvironment.SANDBOX
  )

  data = client.vitals.waist_circumference_grouped(
    user_id="<user_id>", 
    start_date="2021-10-01", 
    end_date="2021-10-02"
  )
  ```

  ```javascript Node
  import { VitalClient, VitalEnvironment } from '@tryvital/vital-node';
  import { VitalsWaistCircumferenceGroupedRequest } from '@tryvital/vital-node/api/resources/vitals';

  const client = new VitalClient({
      apiKey: '<my_api_key>',
      environment: VitalEnvironment.Sandbox,
  });

  const request: VitalsWaistCircumferenceGroupedRequest = {
      startDate: "2022-05-01",
      endDate: "2022-06-01"
  }

  const data = await client.vitals.waistCircumferenceGrouped(
      '<my_user_id>',
      request
  );
  ```

  ```java Java
  import com.vital.api.Vital;
  import com.vital.api.core.Environment;
  import com.vital.api.resources.vitals.requests.VitalsWaistCircumferenceGroupedRequest;

  Vital vital = Vital.builder()
          .apiKey("YOUR_API_KEY")
          .environment(Environment.SANDBOX)
          .build();

  VitalsWaistCircumferenceGroupedRequest request = VitalsWaistCircumferenceGroupedRequest.builder()
          .startDate("2022-05-01")
          .endDate("2022-06-01")
          .build();

  var data = vital.vitals().waistCircumferenceGrouped("<user_id>", request);
  ```

  ```go Go
  import (
    "context"

    vital "github.com/tryVital/vital-go"
    vitalclient "github.com/tryVital/vital-go/client"
  )

  client := vitalclient.NewClient(
    vitalclient.WithApiKey("<YOUR_API_KEY>"),
    vitalclient.WithBaseURL(vital.Environments.Sandbox),
  )

  EndDate := "2022-06-01"
  request := &vital.VitalsWaistCircumferenceGroupedRequest{
    StartDate: "2022-05-01",
    EndDate:   &EndDate,
  }

  response, err := client.Vitals.WaistCircumferenceGrouped(context.TODO(), "*", request)
  if err != nil {
    return err
  }
  fmt.Printf("Received data %s\n", response)
  ```
</RequestExample>

<ResponseExample>
  ```json Example
  {
    "groups": {
      "oura": [
        {
          "data": [
            {
              "end": "2023-02-13T14:57:24+00:00",
              "start": "2023-02-13T14:30:52+00:00",
              "timestamp": "2023-02-13T14:30:52+00:00",
              "unit": "cm",
              "value": 90
            }
          ],
          "source": {
            "provider": "oura",
            "type": "ring"
          }
        }
      ]
    }
  }
  ```
</ResponseExample>


# Water
Source: https://docs.junction.com/api-reference/data/timeseries/water

GET /v2/timeseries/{user_id}/water/grouped

<Card title="View Full Response Schema »" icon="diamond-turn-right" iconType="sharp-solid" color="#F3A712" href="https://api.tryvital.io/redoc#tag/timeseries/operation/get_water_grouped">
  The Response section on the page still needs work. Click here to check out the complete schema.
</Card>

<RequestExample>
  ```bash cURL
  curl --request GET \
       --url {{BASE_URL}}/v2/timeseries/{user_id}/water/grouped?start_date={{START_DATE}}&end_date={{END_DATE}} \
       --header 'Accept: application/json' \
       --header 'x-vital-api-key: <API_KEY>'
  ```

  ```python Python
  from vital.client import Vital
  from vital.environment import VitalEnvironment

  client = Vital(
    api_key="YOUR_API_KEY",
    environment=VitalEnvironment.SANDBOX
  )

  data = client.vitals.water_grouped(
    user_id="<user_id>", 
    start_date="2021-10-01", 
    end_date="2021-10-02"
  )
  ```

  ```javascript Node
  import { VitalClient, VitalEnvironment } from '@tryvital/vital-node';
  import { VitalsWaterGroupedRequest } from '@tryvital/vital-node/api/resources/vitals';

  const client = new VitalClient({
      apiKey: '<my_api_key>',
      environment: VitalEnvironment.Sandbox,
  });

  const request: VitalsWaterGroupedRequest = {
      startDate: "2022-05-01",
      endDate: "2022-06-01"
  }

  const data = await client.vitals.waterGrouped(
      '<my_user_id>',
      request
  );
  ```

  ```java Java
  import com.vital.api.Vital;
  import com.vital.api.core.Environment;
  import com.vital.api.resources.vitals.requests.VitalsWaterGroupedRequest;

  Vital vital = Vital.builder()
          .apiKey("YOUR_API_KEY")
          .environment(Environment.SANDBOX)
          .build();

  VitalsWaterGroupedRequest request = VitalsWaterGroupedRequest.builder()
          .startDate("2022-05-01")
          .endDate("2022-06-01")
          .build();

  var data = vital.vitals().waterGrouped("<user_id>", request);
  ```

  ```go Go
  import (
    "context"

    vital "github.com/tryVital/vital-go"
    vitalclient "github.com/tryVital/vital-go/client"
  )

  client := vitalclient.NewClient(
    vitalclient.WithApiKey("<YOUR_API_KEY>"),
    vitalclient.WithBaseURL(vital.Environments.Sandbox),
  )

  EndDate := "2022-06-01"
  request := &vital.VitalsWaterGroupedRequest{
    StartDate: "2022-05-01",
    EndDate:   &EndDate,
  }

  response, err := client.Vitals.WaterGrouped(context.TODO(), "*", request)
  if err != nil {
    return err
  }
  fmt.Printf("Received data %s\n", response)
  ```
</RequestExample>

<ResponseExample>
  ```json Example
  {
    "groups": {
      "oura": [
        {
          "data": [
            {
              "end": "2023-02-13T14:57:24+00:00",
              "start": "2023-02-13T14:30:52+00:00",
              "unit": "ml",
              "value": 400
            }
          ],
          "source": {
            "provider": "oura",
            "type": "ring"
          }
        }
      ]
    }
  }
  ```
</ResponseExample>


# Wheelchair Push
Source: https://docs.junction.com/api-reference/data/timeseries/wheelchair-push

GET /v2/timeseries/{user_id}/wheelchair_push/grouped

<Card title="View Full Response Schema »" icon="diamond-turn-right" iconType="sharp-solid" color="#F3A712" href="https://api.tryvital.io/redoc#tag/timeseries/operation/get_wheelchair_push_grouped">
  The Response section on the page still needs work. Click here to check out the complete schema.
</Card>

<RequestExample>
  ```bash cURL
  curl --request GET \
       --url {{BASE_URL}}/v2/timeseries/{user_id}/wheelchair_push/grouped?start_date={{START_DATE}}&end_date={{END_DATE}} \
       --header 'Accept: application/json' \
       --header 'x-vital-api-key: <API_KEY>'
  ```

  ```python Python
  from vital.client import Vital
  from vital.environment import VitalEnvironment

  client = Vital(
    api_key="YOUR_API_KEY",
    environment=VitalEnvironment.SANDBOX
  )

  data = client.vitals.wheelchair_push_grouped(
    user_id="<user_id>", 
    start_date="2021-10-01", 
    end_date="2021-10-02"
  )
  ```

  ```javascript Node
  import { VitalClient, VitalEnvironment } from '@tryvital/vital-node';
  import { VitalsWheelchairPushGroupedRequest } from '@tryvital/vital-node/api/resources/vitals';

  const client = new VitalClient({
      apiKey: '<my_api_key>',
      environment: VitalEnvironment.Sandbox,
  });

  const request: VitalsWheelchairPushGroupedRequest = {
      startDate: "2022-05-01",
      endDate: "2022-06-01"
  }

  const data = await client.vitals.wheelchairPushGrouped(
      '<my_user_id>',
      request
  );
  ```

  ```java Java
  import com.vital.api.Vital;
  import com.vital.api.core.Environment;
  import com.vital.api.resources.vitals.requests.VitalsWheelchairPushGroupedRequest;

  Vital vital = Vital.builder()
          .apiKey("YOUR_API_KEY")
          .environment(Environment.SANDBOX)
          .build();

  VitalsWheelchairPushGroupedRequest request = VitalsWheelchairPushGroupedRequest.builder()
          .startDate("2022-05-01")
          .endDate("2022-06-01")
          .build();

  var data = vital.vitals().wheelchairPushGrouped("<user_id>", request);
  ```

  ```go Go
  import (
    "context"

    vital "github.com/tryVital/vital-go"
    vitalclient "github.com/tryVital/vital-go/client"
  )

  client := vitalclient.NewClient(
    vitalclient.WithApiKey("<YOUR_API_KEY>"),
    vitalclient.WithBaseURL(vital.Environments.Sandbox),
  )

  EndDate := "2022-06-01"
  request := &vital.VitalsWheelchairPushGroupedRequest{
    StartDate: "2022-05-01",
    EndDate:   &EndDate,
  }

  response, err := client.Vitals.WheelchairPushGrouped(context.TODO(), "*", request)
  if err != nil {
    return err
  }
  fmt.Printf("Received data %s\n", response)
  ```
</RequestExample>

<ResponseExample>
  ```json Example
  {
    "groups": {
      "oura": [
        {
          "data": [
            {
              "end": "2023-02-13T14:57:24+00:00",
              "start": "2023-02-13T14:30:52+00:00",
              "timestamp": "2023-02-13T14:30:52+00:00",
              "unit": "count",
              "value": 52
            }
          ],
          "source": {
            "provider": "oura",
            "type": "ring"
          }
        }
      ]
    }
  }
  ```
</ResponseExample>


# Workout Distance
Source: https://docs.junction.com/api-reference/data/timeseries/workout-distance

GET /v2/timeseries/{user_id}/workout_distance/grouped

<Card title="View Full Response Schema »" icon="diamond-turn-right" iconType="sharp-solid" color="#F3A712" href="https://api.tryvital.io/redoc#tag/timeseries/operation/get_workout_distance_grouped">
  The Response section on the page still needs work. Click here to check out the complete schema.
</Card>

<RequestExample>
  ```bash cURL
  curl --request GET \
       --url {{BASE_URL}}/v2/timeseries/{user_id}/workout_distance/grouped?start_date={{START_DATE}}&end_date={{END_DATE}} \
       --header 'Accept: application/json' \
       --header 'x-vital-api-key: <API_KEY>'
  ```

  ```python Python
  from vital.client import Vital
  from vital.environment import VitalEnvironment

  client = Vital(
    api_key="YOUR_API_KEY",
    environment=VitalEnvironment.SANDBOX
  )

  data = client.vitals.workout_distance_grouped(
    user_id="<user_id>", 
    start_date="2021-10-01", 
    end_date="2021-10-02"
  )
  ```

  ```javascript Node
  import { VitalClient, VitalEnvironment } from '@tryvital/vital-node';
  import { VitalsWorkoutDistanceGroupedRequest } from '@tryvital/vital-node/api/resources/vitals';

  const client = new VitalClient({
      apiKey: '<my_api_key>',
      environment: VitalEnvironment.Sandbox,
  });

  const request: VitalsWorkoutDistanceGroupedRequest = {
      startDate: "2022-05-01",
      endDate: "2022-06-01"
  }

  const data = await client.vitals.workoutDistanceGrouped(
      '<my_user_id>',
      request
  );
  ```

  ```java Java
  import com.vital.api.Vital;
  import com.vital.api.core.Environment;
  import com.vital.api.resources.vitals.requests.VitalsWorkoutDistanceGroupedRequest;

  Vital vital = Vital.builder()
          .apiKey("YOUR_API_KEY")
          .environment(Environment.SANDBOX)
          .build();

  VitalsWorkoutDistanceGroupedRequest request = VitalsWorkoutDistanceGroupedRequest.builder()
          .startDate("2022-05-01")
          .endDate("2022-06-01")
          .build();

  var data = vital.vitals().workoutDistanceGrouped("<user_id>", request);
  ```

  ```go Go
  import (
    "context"

    vital "github.com/tryVital/vital-go"
    vitalclient "github.com/tryVital/vital-go/client"
  )

  client := vitalclient.NewClient(
    vitalclient.WithApiKey("<YOUR_API_KEY>"),
    vitalclient.WithBaseURL(vital.Environments.Sandbox),
  )

  EndDate := "2022-06-01"
  request := &vital.VitalsWorkoutDistanceGroupedRequest{
    StartDate: "2022-05-01",
    EndDate:   &EndDate,
  }

  response, err := client.Vitals.WorkoutDistanceGrouped(context.TODO(), "*", request)
  if err != nil {
    return err
  }
  fmt.Printf("Received data %s\n", response)
  ```
</RequestExample>

<ResponseExample>
  ```json Example
  {
    "groups": {
      "oura": [
        {
          "data": [
            {
              "end": "2023-02-13T14:57:24+00:00",
              "start": "2023-02-13T14:30:52+00:00",
              "timestamp": "2023-02-13T14:30:52+00:00",
              "unit": "m",
              "value": 37
            }
          ],
          "source": {
            "provider": "oura",
            "type": "ring"
          }
        }
      ]
    }
  }
  ```
</ResponseExample>


# Workout Duration
Source: https://docs.junction.com/api-reference/data/timeseries/workout-duration

GET /v2/timeseries/{user_id}/workout_duration/grouped

<Card title="View Full Response Schema »" icon="diamond-turn-right" iconType="sharp-solid" color="#F3A712" href="https://api.tryvital.io/redoc#tag/timeseries/operation/get_workout_duration_grouped">
  The Response section on the page still needs work. Click here to check out the complete schema.
</Card>

<RequestExample>
  ```bash cURL
  curl --request GET \
       --url {{BASE_URL}}/v2/timeseries/{user_id}/workout_duration/grouped?start_date={{START_DATE}}&end_date={{END_DATE}} \
       --header 'Accept: application/json' \
       --header 'x-vital-api-key: <API_KEY>'
  ```

  ```python Python
  from vital.client import Vital
  from vital.environment import VitalEnvironment

  client = Vital(
    api_key="YOUR_API_KEY",
    environment=VitalEnvironment.SANDBOX
  )

  data = client.vitals.workout_duration_grouped(
    user_id="<user_id>", 
    start_date="2021-10-01", 
    end_date="2021-10-02"
  )
  ```

  ```javascript Node
  import { VitalClient, VitalEnvironment } from '@tryvital/vital-node';
  import { VitalsWorkoutDurationGroupedRequest } from '@tryvital/vital-node/api/resources/vitals';

  const client = new VitalClient({
      apiKey: '<my_api_key>',
      environment: VitalEnvironment.Sandbox,
  });

  const request: VitalsWorkoutDurationGroupedRequest = {
      startDate: "2022-05-01",
      endDate: "2022-06-01"
  }

  const data = await client.vitals.workoutDurationGrouped(
      '<my_user_id>',
      request
  );
  ```

  ```java Java
  import com.vital.api.Vital;
  import com.vital.api.core.Environment;
  import com.vital.api.resources.vitals.requests.VitalsWorkoutDurationGroupedRequest;

  Vital vital = Vital.builder()
          .apiKey("YOUR_API_KEY")
          .environment(Environment.SANDBOX)
          .build();

  VitalsWorkoutDurationGroupedRequest request = VitalsWorkoutDurationGroupedRequest.builder()
          .startDate("2022-05-01")
          .endDate("2022-06-01")
          .build();

  var data = vital.vitals().workoutDurationGrouped("<user_id>", request);
  ```

  ```go Go
  import (
    "context"

    vital "github.com/tryVital/vital-go"
    vitalclient "github.com/tryVital/vital-go/client"
  )

  client := vitalclient.NewClient(
    vitalclient.WithApiKey("<YOUR_API_KEY>"),
    vitalclient.WithBaseURL(vital.Environments.Sandbox),
  )

  EndDate := "2022-06-01"
  request := &vital.VitalsWorkoutDurationGroupedRequest{
    StartDate: "2022-05-01",
    EndDate:   &EndDate,
  }

  response, err := client.Vitals.WorkoutDurationGrouped(context.TODO(), "*", request)
  if err != nil {
    return err
  }
  fmt.Printf("Received data %s\n", response)
  ```
</RequestExample>

<ResponseExample>
  ```json Example
  {
    "groups": {
      "oura": [
        {
          "data": [
            {
              "end": "2023-02-13T14:30:52+00:00",
              "intensity": "medium",
              "start": "2023-02-13T14:30:52+00:00",
              "unit": "min",
              "value": 48
            }
          ],
          "source": {
            "provider": "oura",
            "type": "ring"
          }
        }
      ]
    }
  }
  ```
</ResponseExample>


# Workout Swimming Stroke
Source: https://docs.junction.com/api-reference/data/timeseries/workout-swimming-stroke

GET /v2/timeseries/{user_id}/workout_swimming_stroke/grouped

<Card title="View Full Response Schema »" icon="diamond-turn-right" iconType="sharp-solid" color="#F3A712" href="https://api.tryvital.io/redoc#tag/timeseries/operation/get_workout_swimming_stroke_grouped">
  The Response section on the page still needs work. Click here to check out the complete schema.
</Card>

<RequestExample>
  ```bash cURL
  curl --request GET \
       --url {{BASE_URL}}/v2/timeseries/{user_id}/workout_swimming_stroke/grouped?start_date={{START_DATE}}&end_date={{END_DATE}} \
       --header 'Accept: application/json' \
       --header 'x-vital-api-key: <API_KEY>'
  ```

  ```python Python
  from vital.client import Vital
  from vital.environment import VitalEnvironment

  client = Vital(
    api_key="YOUR_API_KEY",
    environment=VitalEnvironment.SANDBOX
  )

  data = client.vitals.workout_swimming_stroke_grouped(
    user_id="<user_id>", 
    start_date="2021-10-01", 
    end_date="2021-10-02"
  )
  ```

  ```javascript Node
  import { VitalClient, VitalEnvironment } from '@tryvital/vital-node';
  import { VitalsWorkoutSwimmingStrokeGroupedRequest } from '@tryvital/vital-node/api/resources/vitals';

  const client = new VitalClient({
      apiKey: '<my_api_key>',
      environment: VitalEnvironment.Sandbox,
  });

  const request: VitalsWorkoutSwimmingStrokeGroupedRequest = {
      startDate: "2022-05-01",
      endDate: "2022-06-01"
  }

  const data = await client.vitals.workoutSwimmingStrokeGrouped(
      '<my_user_id>',
      request
  );
  ```

  ```java Java
  import com.vital.api.Vital;
  import com.vital.api.core.Environment;
  import com.vital.api.resources.vitals.requests.VitalsWorkoutSwimmingStrokeGroupedRequest;

  Vital vital = Vital.builder()
          .apiKey("YOUR_API_KEY")
          .environment(Environment.SANDBOX)
          .build();

  VitalsWorkoutSwimmingStrokeGroupedRequest request = VitalsWorkoutSwimmingStrokeGroupedRequest.builder()
          .startDate("2022-05-01")
          .endDate("2022-06-01")
          .build();

  var data = vital.vitals().workoutSwimmingStrokeGrouped("<user_id>", request);
  ```

  ```go Go
  import (
    "context"

    vital "github.com/tryVital/vital-go"
    vitalclient "github.com/tryVital/vital-go/client"
  )

  client := vitalclient.NewClient(
    vitalclient.WithApiKey("<YOUR_API_KEY>"),
    vitalclient.WithBaseURL(vital.Environments.Sandbox),
  )

  EndDate := "2022-06-01"
  request := &vital.VitalsWorkoutSwimmingStrokeGroupedRequest{
    StartDate: "2022-05-01",
    EndDate:   &EndDate,
  }

  response, err := client.Vitals.WorkoutSwimmingStrokeGrouped(context.TODO(), "*", request)
  if err != nil {
    return err
  }
  fmt.Printf("Received data %s\n", response)
  ```
</RequestExample>

<ResponseExample>
  ```json Example
  {
    "groups": {
      "oura": [
        {
          "data": [
            {
              "end": "2023-02-13T14:57:24+00:00",
              "start": "2023-02-13T14:30:52+00:00",
              "timestamp": "2023-02-13T14:30:52+00:00",
              "unit": "count",
              "value": 37
            }
          ],
          "source": {
            "provider": "oura",
            "type": "ring"
          }
        }
      ]
    }
  }
  ```
</ResponseExample>


# Raw
Source: https://docs.junction.com/api-reference/data/workouts/get-raw

GET /v2/summary/workouts/{user_id}/raw
Get raw workout summary for user_id

<RequestExample>
  ```bash cURL
  curl --request GET \
       --url {{BASE_URL}}/v2/summary/workouts/{user_id}/raw \
       --header 'Accept: application/json' \
       --header 'x-vital-api-key: <API_KEY>'
  ```

  ```python Python
  from vital.client import Vital
  from vital.environment import VitalEnvironment

  client = Vital(
    api_key="YOUR_API_KEY",
    environment=VitalEnvironment.SANDBOX
  )

  data = client.workouts.get_raw("<user_id>", start_date="2021-01-01", end_date="2021-01-02")
  ```

  ```javascript Node
  import { VitalClient, VitalEnvironment } from '@tryvital/vital-node';
  import { WorkoutsGetRawRequest } from '@tryvital/vital-node/api/resources/workouts';

  const client = new VitalClient({
      apiKey: '<my_api_key>',
      environment: VitalEnvironment.Sandbox,
  });

  const request: WorkoutsGetRawRequest = {
      startDate: "2022-05-01",
      endDate: "2022-06-01"
  }

  const data = await client.workouts.getRaw(
      '<my_user_id>',
      request
  );
  ```

  ```java Java
  import com.vital.api.Vital;
  import com.vital.api.core.Environment;
  import com.vital.api.resources.workouts.requests.WorkoutsGetRawRequest;

  Vital vital = Vital.builder()
          .apiKey("YOUR_API_KEY")
          .environment(Environment.SANDBOX)
          .build();

  WorkoutsGetRawRequest request = WorkoutsGetRawRequest.builder()
          .startDate("2022-05-01")
          .endDate("2022-06-01")
          .build();

  var data = vital.workouts().getRaw("<my_user_id>", request);
  ```

  ```go Go
  import (
    "context"

    vital "github.com/tryVital/vital-go"
    vitalclient "github.com/tryVital/vital-go/client"
    "github.com/tryVital/vital-go/option"
  )

  client := vitalclient.NewClient(
    option.WithApiKey("<YOUR_API_KEY>"),
    option.WithBaseURL(vital.Environments.Sandbox),
  )

  EndDate := "2022-06-01"
  request := &vital.WorkoutsGetRawRequest{
    StartDate: "2022-05-01",
    EndDate:   &EndDate,
  }

  response, err := client.Workouts.GetRaw(context.TODO(), "*", request)
  if err != nil {
    return err
  }
  fmt.Printf("Received data %s\n", response)
  ```
</RequestExample>


# Stream
Source: https://docs.junction.com/api-reference/data/workouts/get-stream

GET /v2/timeseries/workouts/{workout_id}/stream

<RequestExample>
  ```bash cURL
  curl --request GET \
       --url {{BASE_URL}}/v2/summary/workouts/{workout_id}/stream \
       --header 'Accept: application/json' \
       --header 'x-vital-api-key: <API_KEY>'
  ```

  ```python Python
  from vital.client import Vital
  from vital.environment import VitalEnvironment

  client = Vital(
    api_key="YOUR_API_KEY",
    environment=VitalEnvironment.SANDBOX
  )

  data = client.workouts.get_by_workout_id("<workout_id>")
  ```

  ```javascript Node
  import { VitalClient, VitalEnvironment } from '@tryvital/vital-node';

  const client = new VitalClient({
      apiKey: '<my_api_key>',
      environment: VitalEnvironment.Sandbox,
  });

  const data = await client.workouts.getByWorkoutId("<workout_id>")
  ```

  ```java Java
  import com.vital.api.Vital;
  import com.vital.api.core.Environment;

  Vital vital = Vital.builder()
          .apiKey("YOUR_API_KEY")
          .environment(Environment.SANDBOX)
          .build();

  var data = vital.workouts().getByWorkoutId("<workout_id>");
  ```

  ```go Go
  import (
    "context"

    vital "github.com/tryVital/vital-go"
    vitalclient "github.com/tryVital/vital-go/client"
    "github.com/tryVital/vital-go/option"
  )

  client := vitalclient.NewClient(
    option.WithApiKey("<YOUR_API_KEY>"),
    option.WithBaseURL(vital.Environments.Sandbox),
  )

  response, err := client.Workouts.GetByWorkoutId(
    context.TODO(), 
    "<workout_id>"
  )
  if err != nil {
    return err
  }
  fmt.Printf("Received data %s\n", response)
  ```
</RequestExample>


# Summary
Source: https://docs.junction.com/api-reference/data/workouts/get-summary

GET /v2/summary/workouts/{user_id}
Get workout summary for user_id

<RequestExample>
  ```bash cURL
  curl --request GET \
       --url {{BASE_URL}}/v2/summary/workouts/{user_id} \
       --header 'Accept: application/json' \
       --header 'x-vital-api-key: <API_KEY>'
  ```

  ```python Python
  from vital.client import Vital
  from vital.environment import VitalEnvironment

  client = Vital(
    api_key="YOUR_API_KEY",
    environment=VitalEnvironment.SANDBOX
  )

  data = client.workouts.get(
      user_id="<user_id>",
      start_date="2022-05-01",
      end_date="2022-06-01"
  )
  ```

  ```javascript Node
  import { VitalClient, VitalEnvironment } from '@tryvital/vital-node';
  import { WorkoutsGetRequest } from '@tryvital/vital-node/api/resources/workouts';

  const client = new VitalClient({
      apiKey: '<my_api_key>',
      environment: VitalEnvironment.Sandbox,
  });

  const request: WorkoutsGetRequest = {
      startDate: "2022-05-01",
      endDate: "2022-06-01"
  }

  const data = await client.workouts.get(
      '<my_user_id>',
      request
  );
  ```

  ```java Java
  import com.vital.api.Vital;
  import com.vital.api.core.Environment;
  import com.vital.api.resources.workouts.requests.WorkoutsGetRequest;

  Vital vital = Vital.builder()
                  .apiKey("YOUR_API_KEY")
                  .environment(Environment.SANDBOX)
                  .build();

  WorkoutsGetRequest request = WorkoutsGetRequest.builder()
                  .startDate("2022-05-01")
                  .endDate("2022-06-01")
                  .build();

  var data = vital.workouts().get("<my_user_id>", request);
  ```

  ```go Go
  import (
    "context"

    vital "github.com/tryVital/vital-go"
    vitalclient "github.com/tryVital/vital-go/client"
    "github.com/tryVital/vital-go/option"
  )

  client := vitalclient.NewClient(
    option.WithApiKey("<YOUR_API_KEY>"),
    option.WithBaseURL(vital.Environments.Sandbox),
  )

  EndDate := "2022-06-01"
  request := &vital.WorkoutsGetRequest{
    StartDate: "2022-05-01",
    EndDate:   &EndDate,
  }

  response, err := client.Workouts.Get(context.TODO(), "*", request)
  if err != nil {
    return err
  }
  fmt.Printf("Received data %s\n", response)
  ```
</RequestExample>


# Data Prioritization
Source: https://docs.junction.com/api-reference/horizon-ai/aggregation/data-prioritization


## Overview

Data prioritization automatically kicks in whenever you use a [Group By clause](/api-reference/horizon-ai/query-dsl/group-by-clause).

Within each group outlined by your [Group By clause](/api-reference/horizon-ai/query-dsl/group-by-clause), the query executor would **implicitly**:

* Sub-group the data further by their Provider and their [Source Type](/wearables/providers/data-attributions);
* Keep only data from the sub-group that has the highest Source Type priority, or the highest Provider priority when multiple sub-group
  exists for the same Source Type.

<Note>
  Data prioritization works only in a [Group By](/api-reference/horizon-ai/query-dsl/group-by-clause) context.
</Note>

<Note>
  If both the *Provider* and *Source Type* Source Columns are present in the [Group By clause](/api-reference/horizon-ai/aggregation/query-dsl/group-by-clause),
  the implicit [Data Prioritization](/api-reference/horizon-ai/aggregation/data-prioritization) behaviour would be disabled.
</Note>

<Accordion title="Example" defaultOpen>
  You are querying Sleep Score grouped by every 1 day:

  ```json
  {
      "select": [
          { "func": "newest", { "value_macro": "sleep_score" } }
      ],
      "group_by": [
          { "date_trunc": { "value": 1, "unit": "day }, "arg": { "index": "sleep" } }
      ]
  }
  ```

  Assuming this timeline:

  * Day 1: The user connected Oura.
  * Day 5: The user connected Apple HealthKit.
  * Both Oura and HealthKit have been consistently sending sleep data every day since connected.

  #### If your team priority states that Apple HealthKit > Oura

  The query result would be:

  * Day 1-4: Sleep Score computed from Oura sleep data
  * Day 5-7: Sleep Score computed from Apple HealthKit sleep data

  ### If your team priority states that Oura > Apple HealthKit

  The query result would be:

  * Day 1-7: Sleep Score computed from Oura sleep data

  <Info>
    Apple HealthKit data are ignored in this case, because Oura is available throughout all
    days and has higher provider priority.
  </Info>
</Accordion>

## Previewing the prioritization effect

You can experiment and preview the effect of prioritization using the [Query API](/api-reference/horizon-ai/aggregation/using-query-api).

By specifying a list of provider slugs in `config.provider_priority_overrides`, you instruct the query executor to treat these providers
as the highest priority — above the team provider priority — specifically in this query invocation.

## Managing Provider Priorities

You can manage the provider priorities for each summary type through the **Data Priority** section of the [Vital Dashboard](https://app.tryvital.io/).

<Note>A larger number indicates a higher priority.</Note>

## Source Type Priorities

We use pre-assigned, non-configurable Source Type priorities that follow the general expectation of data reliability.

*(sorted from highest priority to lowest priority)*

* `lab`
* `automatic`
* `watch`
* `ring`
* `chest_strap`
* `scale`
* `cuff`
* `fingerprick`
* `manual_scan`
* `phone`
* `app`
* `multiple_sources`
* `unknown`


# Examples
Source: https://docs.junction.com/api-reference/horizon-ai/aggregation/examples


A couple of examples to get you started with Continuous Query:

## Daily Sleep Analysis

<CodeGroup>
  ```python Python DSL
  import vitalx.aggregation as va

  va.select(
      va.group_key("*"), 
      va.Sleep.col("efficiency").mean(),
      va.Sleep.score().mean(),
      va.Sleep.chronotype().newest()
  ).group_by(
      va.date_trunc(va.Sleep.index(), 1, "day")
  ).split_by_source(enabled=False)
  .finalize()
  ```

  ```python JSON DSL
  {
    "select": [
      {
        "group_key": "*"
      },
      {
        "arg": {
          "sleep": "efficiency"
        },
        "func": "mean"
      },
      {
        "arg": {
          "value_macro": "sleep_score",
          "version": "automatic"
        },
        "func": "mean"
      },
      {
        "arg": {
          "value_macro": "chronotype",
          "version": "automatic"
        },
        "func": "newest"
      }
    ],
    "group_by": [
      {
        "date_trunc": {
          "value": 1,
          "unit": "day"
        },
        "arg": {
          "index": "sleep"
        }
      }
    ],
    "split_by_source": false
  }
  ```
</CodeGroup>

## Weekly Insights Into Users Activity

<CodeGroup>
  ```python Python DSL
  import vitalx.aggregation as va

  va.select(
      va.group_key("*"), 
      va.Activity.col("heart_rate_resting").mean(),
      va.Activity.col("calories_total").max(),
      va.Activity.col("steps").min(),
      va.Activity.col("duration_active_seconds").mean()
  ).group_by(
      va.date_trunc(va.Activity.index(), 1, "week")
  ).split_by_source(enabled=False)
  .finalize()
  ```

  ```python JSON DSL
  {
    "select": [
      {
        "group_key": "*"
      },
      {
        "arg": {
          "activity": "heart_rate_resting"
        },
        "func": "mean"
      },
      {
        "arg": {
          "activity": "calories_total"
        },
        "func": "max"
      },
      {
        "arg": {
          "activity": "steps"
        },
        "func": "min"
      },
      {
        "arg": {
          "activity": "duration_active_seconds"
        },
        "func": "mean"
      },
    ],
    "group_by": [
      {
        "date_trunc": {
          "value": 1,
          "unit": "week"
        },
        "arg": {
          "index": "activity"
        }
      }
    ],
    "split_by_source": false
  }
  ```
</CodeGroup>


# null
Source: https://docs.junction.com/api-reference/horizon-ai/aggregation/overview


<Card horizontal icon="person-digging" color="#57164A">
  Horizon AI Query is in **closed beta**.

  Interested in the Horizon AI Query? Get in touch with your Customer Success Manager.
</Card>

Horizon AI Query consolidates the multitude of user data collected across [wearable data providers](/wearables/providers/introduction)
and [source types](/wearables/providers/data-attributions#source-type) into simple tabular outputs.

<img src="https://mintcdn.com/vital/img/aggregation/overview.png?maxW=2964&auto=format&n=nR1fvAlwouZ87zVb&q=85&s=776e4e1484c56d8e7784a4dd526c4d75" alt="A high-level illustration of the inputs and outputs of the Aggregation API" width="2964" height="1020" data-path="img/aggregation/overview.png" srcset="https://mintcdn.com/vital/img/aggregation/overview.png?w=280&maxW=2964&auto=format&n=nR1fvAlwouZ87zVb&q=85&s=1493f7d42689a75960a5fc1efec9fac9 280w, https://mintcdn.com/vital/img/aggregation/overview.png?w=560&maxW=2964&auto=format&n=nR1fvAlwouZ87zVb&q=85&s=fbedd5d5b763f290d0ee5536dd804fdf 560w, https://mintcdn.com/vital/img/aggregation/overview.png?w=840&maxW=2964&auto=format&n=nR1fvAlwouZ87zVb&q=85&s=b6ce0f7e9411218e7636d32118a7f84e 840w, https://mintcdn.com/vital/img/aggregation/overview.png?w=1100&maxW=2964&auto=format&n=nR1fvAlwouZ87zVb&q=85&s=d08fa1fc592d141e05ef1601b9d556e3 1100w, https://mintcdn.com/vital/img/aggregation/overview.png?w=1650&maxW=2964&auto=format&n=nR1fvAlwouZ87zVb&q=85&s=a6a0431a9a58b0a515ba8aa00b2d5ecf 1650w, https://mintcdn.com/vital/img/aggregation/overview.png?w=2500&maxW=2964&auto=format&n=nR1fvAlwouZ87zVb&q=85&s=638ae4c71175382fd164de34793dddd9 2500w" data-optimize="true" data-opv="2" />

<Card title="Consolidation" icon="merge" horizontal>
  Work with simple tabular outputs, and offload the dirty work to Horizon AI — the data gathering, prioritization and sanitization
  processes across multiple providers and source types.
</Card>

<Card title="Data prioritization" icon="bars-staggered" horizontal>
  Provider priorities can be configured at team level. Query-level priority overrides are also supported to enable
  experimentations.
</Card>

<Card title="Aggregate in floating time" icon="timeline-arrow" horizontal>
  Work with time zone agnostic outputs that are indexed in the user's perception of time (i.e., *floating time*).
</Card>

## Query API and Continuous Query

You can use Horizon AI Query through two mediums:

### Query API

* Rapid Insights: Ideal for quick analysis, allowing developers to experiment with individual user data immediately.
* Flexible Outputs: Produces easy-to-use DataFrames that work seamlessly with popular data analysis tools.
* Cost and Time Efficiency: Get aggregated insights without having to dump all user data from the API.
* Build Dynamic Dashboards: Queries are adjustable and executed in real time, suitable for dynamic dashboards that need to support flexible adjustments of query based on user inputs.

### Continuous Query

* Automatic Evaluation: Best suited for scenarios requiring ongoing data monitoring and updates, automatically re-evaluating queries when new data is available.
* Streamlined Workflows: Minimizes manual effort and efficiently manages large datasets, making it ideal for continuous reporting and collaboration within teams.
* Pushed Changes: New and changed query results are pushed to you as webhooks via svix or ETL Pipelines

### Decision Guide

<Steps>
  <Step title="Experiment with Query API">
    Start with Query API if you need quick insights, one-time analysis or query experimentation using an individual user's data.
  </Step>

  <Step title="Productize with Continuous Query">
    Switch to Continuous Query once you have queries which you wish to turn into a continuously updated, named dataset and to receive change events for.
  </Step>
</Steps>

Choose based on your current needs — rapid analysis and iteration with Query API or continual data monitoring with Continuous Query. Both features use the same Query DSL, complement each other and can adapt as your product evolves.


# Column expressions
Source: https://docs.junction.com/api-reference/horizon-ai/aggregation/query-dsl/column-expressions


## Table Column expression

Your Query Instruction can pull data from [Junction summary and timeseries resources](/wearables/providers/resources)
through Table Column expressions.

Each Table Column expression can select one column (a field) of the table (the Vital resource).
You can use multiple Table Column expressions to select multiple columns in the same query.

<Info>
  Cross-table query instruction is not supported — you cannot mix Table Column expressions from
  different tables in the same query instruction.
</Info>

<Note>
  Column expressions for Electrocardiogram, Sleep Cycle, Menstrual Cycle and lab testing biomarkers are planned to be introduced in the future.
</Note>

### Summaries

| Table                                  | Python DSL           | JSON DSL               |
| -------------------------------------- | -------------------- | ---------------------- |
| Activity daily summary<br />`activity` | `Activity.col("$1")` | `{ "activity": "$1" }` |
| Body summary<br />`body`               | `Body.col("$1")`     | `{ "body": "$1" }`     |
| Sleep summary<br />`sleep`             | `Sleep.col("$1")`    | `{ "sleep": "$1" }`    |
| Workout summary<br />`workout`         | `Workout.col("$1")`  | `{ "workout": "$1" }`  |
| Meal summary<br />`meal`               | `Meal.col("$1")`     | `{ "meal": "$1" }`     |

### Timeseries

| Table                      | Python DSL                         | JSON DSL                               |
| -------------------------- | ---------------------------------- | -------------------------------------- |
| Timeseries Resource fields | `Timeseries.col("$1").field("$2")` | `{ "timeseries": "$1", "field": "$2"}` |

## Source Column expression

You can use a Source Column expression to refer to Data Source fields common to Junction resources.

Note that some Source Column expression may not be valid in the implicit query context. For example, `source_sport` is not a valid Source Column
expression in a query that is selecting from the Sleep resource.

<Note>
  If both the *Provider* and *Source Type* Source Columns are present in the [Group By clause](/api-reference/horizon-ai/aggregation/query-dsl/group-by-clause),
  the implicit [Data Prioritization](/api-reference/horizon-ai/aggregation/data-prioritization) behaviour would be disabled.
</Note>

| Column        | Python DSL                        | JSON DSL                           | Available in                   |
| ------------- | --------------------------------- | ---------------------------------- | ------------------------------ |
| Provider      | `Source.col("source_provider")`   | `{ "source": "source_provider" }`  | All Tables                     |
| Source Type   | `Source.col("source_type")`       | `{ "source": "source_type" }`      | All Tables                     |
| Source App ID | `Source.col("source_app_id")`     | `{ "source": "source_app_id" }`    | All summary tables             |
| Workout ID    | `Source.col("source_workout_id")` | `{ "source": "source_workout_id"}` | Workout Stream timeseries only |
| Sport         | `Source.col("source_sport")`      | `{ "source": "source_sport" }`     | Workout Stream timeseries only |

## Index Column expression

Each Vital resource has a primary datetime index. Your Query Instruction can reference this datetime
index using the special Index Column expression:

| Table                                  | Index                  | Python DSL         | JSON DSL                  |
| -------------------------------------- | ---------------------- | ------------------ | ------------------------- |
| Activity daily summary<br />`activity` | Calendar date          | `Activity.index()` | `{ "index": "activity" }` |
| Body summary<br />`body`               | Measurement datetime   | `Body.index()`     | `{ "index": "body" }`     |
| Sleep summary<br />`sleep`             | Session end datetime   | `Sleep.index()`    | `{ "index": "sleep" }`    |
| Workout summary<br />`workout`         | Session start datetime | `Workout.index()`  | `{ "index": "workout" }`  |

## Group Key Column expression

When your Query Instruction uses [the `group_by` clause](/api-reference/horizon-ai/aggregation/query-dsl/group-by-clause), each expression
in the `group_by` clause creates a temporary Group Key Column (`group_key.$OFFSET`). These temporary columns are then used to
facilitate the data grouping and aggregation as specified by your Query Instruction.

You can refer to these columns using the special Group Key Column expression:

| Group Key Columns | Python DSL       | JSON DSL               |
| ----------------- | ---------------- | ---------------------- |
| All               | `group_key("*")` | `{ "group_key": "*" }` |
| The `$N`-th key   | `group_key($N)`  | `{ "group_key": $N }`  |


# GROUP BY clause
Source: https://docs.junction.com/api-reference/horizon-ai/aggregation/query-dsl/group-by-clause


## Overview

You specify how Horizon AI Query should dissect the selected data through a Group By clause. The [Aggregate expressions](/api-reference/horizon-ai/aggregation/query-dsl/select-clause#aggregate-a-table-column)
you specify would then be applied to the resulting groups.

Your Group By clause can contain one or more of the following expressions:

* a [Date Truncate expression](#group-by-a-truncated-datetime)

  * A synchronous [Query](/api-reference/horizon-ai/aggregation/using-query-api) can have at most one [Date Truncate expression](#group-by-a-truncated-datetime)
  * A [Continuous Query](/api-reference/horizon-ai/aggregation/using-continuous-query) must have exactly one [Date Truncate expression](#group-by-a-truncated-datetime).

* a [Date Part expression](#group-by-a-date-or-time-component)

* a [Table Column expression](#group-by-a-table-column-expression)

* a [Source Column expression](#group-by-a-source-column-expression)

You can mix and match any expression types, and organize them in any order. [Group Key Column expression](/api-reference/horizon-ai/aggregation/query-dsl/select-clause#select-the-group-key-columns)
tracks your declaration order.

## Group by a truncated datetime

Group the input rows based on the specified column expression truncated to the specified granularity.
This is similar to the `DATE_TRUNC` function in SQL.

<AccordionGroup>
  <Accordion title="Input argument" icon="arrow-right-to-bracket" iconType="duotone" defaultOpen>
    | Argument    | Remarks                                                                                                                                                           |
    | ----------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
    | date\_trunc | The date or time period to truncate the input datetime to.                                                                                                        |
    | arg         | The input expression — only an [Index Column expression](/api-reference/horizon-ai/aggregation/query-dsl/column-expressions#index-column-expression) is accepted. |
  </Accordion>

  <Accordion title="Output column name" icon="line-columns" iconType="duotone" defaultOpen>
    `group_key.$OFFSET` if this is the N-th expression in the `group_by` clause.

    See also: [Select the group key columns](/api-reference/horizon-ai/aggregation/query-dsl/select-clause#select-the-group-key-columns)
  </Accordion>
</AccordionGroup>

<CodeGroup>
  ```python Python DSL
  import vitalx.aggregation as va

  # Truncate to every 1 day.
  va.select(...).group_by(
      va.date_trunc(va.Sleep.index(), 1, "day"),
  )

  # Truncate to every 3 months.
  va.select(...).group_by(
      va.date_trunc(va.Sleep.index(), 3, "month"),
  )
  ```

  ```python JSON DSL
  # Truncate to every 1 day.
  {
      "group_by": [
          {
              "date_trunc": { "value": 1, "unit": "day" },
              "arg": { "index": "sleep" }
          }
      ]
  }

  # Truncate to every 3 months.
  {
      "group_by": [
          {
              "date_trunc": { "value": 3, "unit": "month" },
              "arg": { "index": "sleep" }
          }
      ]
  }
  ```
</CodeGroup>

## Group by a date or time component

Group the input rows based on a specific date or time component extracted from the specified column expression.
This is similar to the `DATE_PART` function in SQL.

<AccordionGroup>
  <Accordion title="Input argument" icon="arrow-right-to-bracket" iconType="duotone" defaultOpen>
    | Argument   | Remarks                                                                                                                                                           |
    | ---------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
    | date\_part | The date or time unit to extract.                                                                                                                                 |
    | arg        | The input expression — only an [Index Column expression](/api-reference/horizon-ai/aggregation/query-dsl/column-expressions#index-column-expression) is accepted. |
  </Accordion>

  <Accordion title="Output column name" icon="line-columns" iconType="duotone" defaultOpen>
    `group_key.$OFFSET` if this is the N-th expression in the `group_by` clause.

    See also: [Select the group key columns](/api-reference/horizon-ai/aggregation/query-dsl/select-clause#select-the-group-key-columns)
  </Accordion>
</AccordionGroup>

<CodeGroup>
  ```python Python DSL
  import vitalx.aggregation as va

  # Extract the weekday
  va.select(...).group_by(
      va.date_part(va.Sleep.index(), "weekday"),
  )

  # Extract the day-of-month
  va.select(...).group_by(
      va.date_part(va.Sleep.index(), "day")
  )
  ```

  ```python JSON DSL
  # Extract the weekday
  {
      "group_by": [
          {
              "date_part": "weekday",
              "arg": { "index": "sleep" }
          }
      ]
  }

  # Extract the day-of-month
  {
      "group_by": [
          {
              "date_part": "day",
              "arg": { "index": "sleep" }
          }
      ]
  }
  ```
</CodeGroup>

## Group by a Table Column expression

Group the input rows based on a [Table Column expression](/api-reference/horizon-ai/aggregation/query-dsl/column-expressions#table-column-expression).
This is similar to the generic `GROUP BY` clause in SQL.

<AccordionGroup>
  <Accordion title="Input argument" icon="arrow-right-to-bracket" iconType="duotone" defaultOpen>
    Any [Table Column expressions](/api-reference/horizon-ai/aggregation/query-dsl/column-expressions#table-column-expression) — summary or timeseries.
  </Accordion>

  <Accordion title="Output column name" icon="line-columns" iconType="duotone" defaultOpen>
    `group_key.$OFFSET` if this is the N-th expression in the `group_by` clause.

    See also: [Select the group key columns](/api-reference/horizon-ai/aggregation/query-dsl/select-clause#select-the-group-key-columns)
  </Accordion>
</AccordionGroup>

<CodeGroup>
  ```python Python DSL
  import vitalx.aggregation as va

  # Group by calendar date and Stand Hour type (idle vs stand)

  va.select(
      va.group_key("*"),
      va.Timeseries.col("stand_hour").field("value").sum()
  ).group_by(
      va.date_trunc(va.Timeseries.index(), 1, "day"),
      va.Timeseries.col("stand_hour").field("type")
  )
  ```

  ```python JSON DSL

  # Group by calendar date and Stand Hour type (idle vs stand)
  {
      "group_by": [
          {
              "date_trunc": {
                  "value": 1,
                  "unit": "day"
              },
              "arg": { "index": "timeseries" }
          },
          {
              "timeseries": "stand_hour",
              "field": "type"
          }
      ]
  }
  ```
</CodeGroup>

## Group by a Source Column expression

Group the input rows based on a [Source Column expression](/api-reference/horizon-ai/aggregation/query-dsl/column-expressions#source-column-expression).
This is similar to a generic `GROUP BY` clause in SQL.

<Note>
  If both the *Provider* and *Source Type* Source Columns are present in the [Group By clause](/api-reference/horizon-ai/aggregation/query-dsl/group-by-clause),
  the implicit [Data Prioritization](/api-reference/horizon-ai/aggregation/data-prioritization) behaviour would be disabled.
</Note>

<AccordionGroup>
  <Accordion title="Input argument" icon="arrow-right-to-bracket" iconType="duotone" defaultOpen>
    Any [Source Column expressions](/api-reference/horizon-ai/aggregation/query-dsl/column-expressions#source-column-expression) valid in the query context.
  </Accordion>

  <Accordion title="Output column name" icon="line-columns" iconType="duotone" defaultOpen>
    `group_key.$OFFSET` if this is the N-th expression in the `group_by` clause.

    See also: [Select the group key columns](/api-reference/horizon-ai/aggregation/query-dsl/select-clause#select-the-group-key-columns)
  </Accordion>
</AccordionGroup>

<CodeGroup>
  ```python Python DSL
  import vitalx.aggregation as va

  # Group by the source provider and source type
  va.select(...).group_by(
      va.date_trunc(va.Sleep.index(), 1, "week"),
      va.Source.col("source_provider"),
      va.Source.col("source_type")
  )

  ```

  ```python JSON DSL
  # Group by the source provider and source type
  {
      "group_by": [
          {
              "date_trunc": {
                  "value": 1,
                  "unit": "week"
              },
              "arg": { "index": "sleep" }
          },
          { "source": "source_provider" },
          { "source": "source_type" }
      ]
  }
  ```
</CodeGroup>


# SELECT clause
Source: https://docs.junction.com/api-reference/horizon-ai/aggregation/query-dsl/select-clause


## Select a table column

Select a specific table column using a [Table Column expression](/api-reference/horizon-ai/aggregation/query-dsl/column-expressions).

<Accordion title="Output column name" icon="line-columns" iconType="duotone" defaultOpen>
  The name of column being selected.
</Accordion>

<CodeGroup>
  ```python Python DSL
  import vitalx.aggregation as va

  va.select(va.Sleep.col("efficiency"))
  ```

  ```python JSON DSL
  {
      "select": [
          { "sleep": "efficiency" }
      ]
  }
  ```
</CodeGroup>

## Perform an analysis and select the output value

Perform data analysis with in-built algorithms using value macro expressions:

* [Sleep Analysis](/api-reference/horizon-ai/aggregation/query-dsl/sleep-analysis) value macro expressions

<Accordion title="Output column name" icon="line-columns" iconType="duotone" defaultOpen>
  The name of the value macro, e.g., `sleep_score` for the Chronotype value macro.
</Accordion>

<CodeGroup>
  ```python Python DSL
  import vitalx.aggregation as va

  va.select(va.Sleep.chronotype())
  ```

  ```python JSON DSL
  {
      "select": [
          { "value_macro": "chronotype" }
      ]
  }
  ```
</CodeGroup>

## Aggregate a table column

Aggregate a [Table Column expression](/api-reference/horizon-ai/aggregation/query-dsl/column-expressions) with respect to the `group_by` clause.

The specified aggregate function is applied to each and every group created by the `group_by` clause.
The result set is N aggregated values where N is the number of groups.

<AccordionGroup>
  <Accordion title="Statistical functions" icon="chart-column" iconType="duotone" defaultOpen>
    | Aggregate function | Python DSL       | JSON DSL                                  |
    | ------------------ | ---------------- | ----------------------------------------- |
    | Minimum            | `$EXPR.min()`    | `{ "aggregate": "min", "arg": $EXPR }`    |
    | Maximum            | `$EXPR.max()`    | `{ "aggregate": "max", "arg": $EXPR }`    |
    | Mean               | `$EXPR.mean()`   | `{ "aggregate": "mean", "arg": $EXPR }`   |
    | Median             | `$EXPR.median()` | `{ "aggregate": "median", "arg": $EXPR }` |
    | Standard Deviation | `$EXPR.stddev()` | `{ "aggregate": "stddev", "arg": $EXPR }` |
    | Count              | `$EXPR.count()`  | `{ "aggregate": "count", "arg": $EXPR }`  |
    | Oldest Value       | `$EXPR.oldest()` | `{ "aggregate": "oldest", "arg": $EXPR }` |
    | Newest Value       | `$EXPR.newest()` | `{ "aggregate": "newest", "arg": $EXPR }` |
  </Accordion>

  <Accordion title="Math functions" icon="sigma" iconType="duotone" defaultOpen>
    | Aggregate function | Python DSL    | JSON DSL                               |
    | ------------------ | ------------- | -------------------------------------- |
    | Sum                | `$EXPR.sum()` | `{ "aggregate": "sum", "arg": $EXPR }` |
  </Accordion>

  <Accordion title="Output column name" icon="line-columns" iconType="duotone" defaultOpen>
    * the aggregation function name, e.g., `sum`; or
    * if the Split by Source mode is enabled — `$FUNCTION_NAME.$SOURCE_COLUMN_NAME`, e.g., `mean.efficiency`.
  </Accordion>
</AccordionGroup>

<CodeGroup>
  ```python Python DSL
  import vitalx.aggregation as va

  va.select(
      va.Sleep.col("stage_asleep_second").newest()
  )
  ```

  ```python JSON DSL
  {
      "select": [
          {
              "aggregate": "newest",
              "arg": { "sleep": "stage_asleep_second" }
          }
      ]
  }
  ```
</CodeGroup>

## Select the Index Column

Select the primary datetime index of the table using the [Index Column expression](/api-reference/horizon-ai/aggregation/query-dsl/column-expressions#index-column-expression).

<Accordion title="Output column name" icon="line-columns" iconType="duotone" defaultOpen>
  `timestamp` (constant).
</Accordion>

<CodeGroup>
  ```python Python DSL
  import vitalx.aggregation as va

  va.select(va.Sleep.col("efficiency"))
  ```

  ```python JSON DSL
  {
      "select": [
          { "sleep": "efficiency" }
      ]
  }
  ```
</CodeGroup>

## Select the Group Key Columns

Select the [Group Key Columns](/api-reference/horizon-ai/aggregation/query-dsl/column-expressions#group-key-column-expression) associated
with the `group_by` clause.

You can select one specific group key column by offset, or select all group key columns with a `*` wildcard.

<Accordion title="Output column name" icon="line-columns" iconType="duotone" defaultOpen>
  `group_key.$OFFSET`, where `$OFFSET` corresponds to the N-th expression of the `group_by` clause.
</Accordion>

<CodeGroup>
  ```python Python DSL
  import vitalx.aggregation as va

  # Select all group key columns
  va.select(va.group_key("*"))

  # Select the 2nd group key column
  va.select(va.group_key(2))
  ```

  ```python JSON DSL
  # Select all group key columns
  {
      "select": [
          { "group_key": "*" }
      ]
  }

  # Select the 2nd group key column
  {
      "select": [
          { "group_key": 2 }
      ]
  }
  ```
</CodeGroup>


# Sleep Analysis
Source: https://docs.junction.com/api-reference/horizon-ai/aggregation/query-dsl/sleep-analysis

Value macro expressions for Sleep Analysis

## Chronotype

Determine the chronotype of each sleep session.

<Accordion title="Output column name" icon="line-columns" iconType="duotone" defaultOpen>
  `chronotype`
</Accordion>

### Get last chronotype of the week

<CodeGroup>
  ```python Python DSL
  import vitalx.aggregation as va

  va.select(
      va.Sleep.chronotype().latest()
  ).group_by(
      date_trunc(Sleep.index(), 1, "week")
  )
  ```

  ```python JSON DSL
  {
      "select": [
          { "func": "latest", "arg": { "value_macro": "chronotype" } }
      ],
      "group_by": [
          {
              "date_trunc": {
                  "unit": "week",
                  "value": 1
              }
          }
      ]
  }
  ```
</CodeGroup>

### Get chronotype

<CodeGroup>
  ```python Python DSL
  import vitalx.aggregation as va

  va.select(va.Sleep.chronotype())
  ```

  ```python JSON DSL
  {
      "select": [
          { "value_macro": "chronotype" }
      ]
  }
  ```
</CodeGroup>

## Sleep Score

Calculate a Sleep Score (0 to 100) for each sleep session.

<Accordion title="Output column name" icon="line-columns" iconType="duotone" defaultOpen>
  `sleep_score`
</Accordion>

### Get mean sleep score of the week

<CodeGroup>
  ```python Python DSL
  import vitalx.aggregation as va

  va.select(
      va.Sleep.score().mean()
  ).group_by(
      date_trunc(Sleep.index(), 1, "week")
  )
  ```

  ```python JSON DSL
  {
      "select": [
          { "func": "mean", "arg": { "value_macro": "sleep_score" } }
      ],
      "group_by": [
          {
              "date_trunc": {
                  "unit": "week",
                  "value": 1
              }
          }
      ]
  }
  ```
</CodeGroup>

### Get sleep score

<CodeGroup>
  ```python Python DSL
  import vitalx.aggregation as va

  va.select(va.Sleep.score())
  ```

  ```python JSON DSL
  {
      "select": [
          { "value_macro": "sleep_score" }
      ]
  }
  ```
</CodeGroup>


# Query a single user
Source: https://docs.junction.com/api-reference/horizon-ai/aggregation/query-one

post /aggregate/v1/user/{user_id}/query

<Card horizontal icon="person-digging" color="#57164A">
  Horizon AI Query is in **closed beta**.

  Interested in the Horizon AI Query? Get in touch with your Customer Success Manager.
</Card>

<AccordionGroup>
  <Accordion title="Receiving data in JSON" icon="brackets-curly" defaultOpen>
    JSON is the default output format. Each query instruction outputs one entry containing a dataframe to the `$.results` array,
    in the declaration order of the query instructions.

    ```json
    {
        "results": [
            "table": {
                "index": [...],
                "min": [...],
                "max": [...],
                "mean": [...],
                "newest": [...]
            }
        ]
    }
    ```
  </Accordion>

  <Accordion title="Receiving data in Parquet" icon="chevrons-up" defaultOpen>
    Specify `Accept: application/vnd.vital.tar+gzip+parquet` in your request header.

    The response body is a gzipped Tarball of multiple Parquet files, namely `0.parquet`, `1.parquet`, `2.parquet`, etc.
    The numbering corresponds to the declaration order of the query instructions.
  </Accordion>
</AccordionGroup>


# Using Continuous Query
Source: https://docs.junction.com/api-reference/horizon-ai/aggregation/using-continuous-query


<Card horizontal icon="person-digging" color="#57164A">
  Horizon AI Query is in **closed beta**.

  Interested in the Horizon AI Query? Get in touch with your Customer Success Manager.
</Card>

You can create a **Continuous Query** to have your [Horizon AI Query](/api-reference/horizon-ai/aggregation/overview)
automatically evaluated by Junction as needed, and receive any query result changes through [your Webhook or ETL Pipeline destinations](/webhooks/introduction).

<AccordionGroup>
  <Accordion title="Automatic Evaluation" icon="wand-sparkles" defaultOpen>
    Continuous Query runs automatically on all existing and new Users in your Team;
  </Accordion>

  <Accordion title="Continuous Change Monitoring" icon="camera-cctv" defaultOpen>
    Continuous Query is scheduled intelligently in response to any new data points or updates discovered through device data connections
    made through [Junction Link](/wearables/connecting-providers/introduction) and [Junction Mobile SDKs](/wearables/sdks/vital-health).
  </Accordion>

  <Accordion title="Result Pushing" icon="webhook" defaultOpen>
    Junction pushes any Continuous Query result table changes to your Webhook or ETL Pipeline destinations.
  </Accordion>

  <Accordion title="Result Pulling" icon="table" defaultOpen>
    The latest result table can be queried through [Junction API](/api-reference/horizon-ai/continuous-query/get-result-table) at any time.
  </Accordion>
</AccordionGroup>

<img src="https://mintcdn.com/vital/img/aggregation/continuous-query.png?maxW=2250&auto=format&n=nR1fvAlwouZ87zVb&q=85&s=c2a8a8d5ea7e9a8a108d9429df53badc" alt="A high-level illustration of the continuous query structure" width="2250" height="758" data-path="img/aggregation/continuous-query.png" srcset="https://mintcdn.com/vital/img/aggregation/continuous-query.png?w=280&maxW=2250&auto=format&n=nR1fvAlwouZ87zVb&q=85&s=1a020ad95ea622a4ec536be6d6afff98 280w, https://mintcdn.com/vital/img/aggregation/continuous-query.png?w=560&maxW=2250&auto=format&n=nR1fvAlwouZ87zVb&q=85&s=7d49d225e33ed606e18fe712b798cc0e 560w, https://mintcdn.com/vital/img/aggregation/continuous-query.png?w=840&maxW=2250&auto=format&n=nR1fvAlwouZ87zVb&q=85&s=76dc6981d86e86c9d8b47a717240a160 840w, https://mintcdn.com/vital/img/aggregation/continuous-query.png?w=1100&maxW=2250&auto=format&n=nR1fvAlwouZ87zVb&q=85&s=cc3af5ab60d997bec0a8c8e5ffb477bf 1100w, https://mintcdn.com/vital/img/aggregation/continuous-query.png?w=1650&maxW=2250&auto=format&n=nR1fvAlwouZ87zVb&q=85&s=15a2f892b18986a0231c22590f3cbe30 1650w, https://mintcdn.com/vital/img/aggregation/continuous-query.png?w=2500&maxW=2250&auto=format&n=nR1fvAlwouZ87zVb&q=85&s=cab289423bcb4c3d58a64a1c544468f6 2500w" data-optimize="true" data-opv="2" />

With Continuous Query, you can focus on adding value to your product with the aggregated data insights:

* you need not build your own scalable data pipeline from scratch to ingest, store and aggregate standardized device data.
* you need not poll the Query API to receive query results.

## Continuous Query requirements

While Continuous Query uses the same [Query DSL](/api-reference/horizon-ai/aggregation/query-dsl/) as the Query API, some
restrictions are in place:

* The query must [group by a truncated datetime](/api-reference/horizon-ai/aggregation/query-dsl/group-by-clause#group-by-a-truncated-datetime).
* The query must [select all group key columns](/api-reference/horizon-ai/aggregation/query-dsl/select-clause#select-the-group-key-columns).

<Note>
  Do reach out to us if your use case is hampered by these restrictions.
</Note>

## Subscribing to query result changes

When a Continuous Query is re-evaluated and the result set has changed, Junction sends a [Result Table Changed](/event-catalog/continuous_query.result_table.changed)
data event to your [your Webhook or ETL Pipeline destinations](/webhooks/introduction).

This data event includes only the delta (new rows or changed rows with respect to the [group keys](]\(/api-reference/horizon-ai/aggregation/query-dsl/select-clause#select-the-group-key-columns\))).
To re-fetch the whole result set, use the [Get Result Table](/api-reference/horizon-ai/continuous-query/get-result-table) endpoint.

```json
{
  "event_type": "continuous_query.result_table.changed",
  "user_id": "4a29dbc7-6db3-4c83-bfac-70a20a4be1b2",
  "client_user_id": "01HW3FSNVCHC3B2QB5N0ZAAAVG",
  "team_id": "6b74423d-0504-4470-9afb-477252ccf67a",
  "data": [
    {
      "data": {
        "group_key.0": [
          "2025-02-17T00:00:00"
        ],
        "mean.efficiency": [
          98.22
        ],
        "mean.sleep_score": [
          76.75
        ],
        "min.sleep_score": [
          61
        ],
        "newest.chronotype": [
          "third"
        ]
      },
      "query_id": "b59425f8-eb5a-4c60-ae95-eda70179da04",
      "query_slug": "sleep-analysis-v1"
    }
  ]
}
```

## Managing your Continuous Queries

You can manage your Continuous Query using our [Org Management API](/api-reference/org-management):

* [Create Continuous Query Endpoint](/api-reference/horizon-ai/continuous-query/create)
* [List Continuous Queries Endpoint](/api-reference/horizon-ai/continuous-query/list)

You can also manage them through the *Continuous Query* section of the Vital Dashboard:

<img src="https://mintcdn.com/vital/img/aggregation/query-creator-dashboard.png?maxW=2208&auto=format&n=nR1fvAlwouZ87zVb&q=85&s=cdca997980f44cf16265e7428ce4d4de" alt="Screenshot of the query creator" width="2208" height="1076" data-path="img/aggregation/query-creator-dashboard.png" srcset="https://mintcdn.com/vital/img/aggregation/query-creator-dashboard.png?w=280&maxW=2208&auto=format&n=nR1fvAlwouZ87zVb&q=85&s=500d4df0e1440264357a6837429f9b1b 280w, https://mintcdn.com/vital/img/aggregation/query-creator-dashboard.png?w=560&maxW=2208&auto=format&n=nR1fvAlwouZ87zVb&q=85&s=f5c2277e5d0546133099c222716c0402 560w, https://mintcdn.com/vital/img/aggregation/query-creator-dashboard.png?w=840&maxW=2208&auto=format&n=nR1fvAlwouZ87zVb&q=85&s=542a7a275ef1f1439085a806535eea8b 840w, https://mintcdn.com/vital/img/aggregation/query-creator-dashboard.png?w=1100&maxW=2208&auto=format&n=nR1fvAlwouZ87zVb&q=85&s=89c95b5f4e7f34b1d0eda98df9099c80 1100w, https://mintcdn.com/vital/img/aggregation/query-creator-dashboard.png?w=1650&maxW=2208&auto=format&n=nR1fvAlwouZ87zVb&q=85&s=36d7ce5333d0c54b00332db993f50382 1650w, https://mintcdn.com/vital/img/aggregation/query-creator-dashboard.png?w=2500&maxW=2208&auto=format&n=nR1fvAlwouZ87zVb&q=85&s=56288e4ba05c1950a254a87d3c6f2f0e 2500w" data-optimize="true" data-opv="2" />


# Using Query API
Source: https://docs.junction.com/api-reference/horizon-ai/aggregation/using-query-api


<Card horizontal icon="person-digging" color="#57164A">
  Horizon AI Query is in **closed beta**.

  Interested in the Horizon AI Query? Get in touch with your Customer Success Manager.
</Card>

You can make use of the Query API through these mediums:

| Channel                                                                             | Remarks                                                                                                                         |
| ----------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- |
| [Vital Horizon AI Python SDK](/api-reference/horizon-ai/python-sdk/getting-started) | The `vitalx-aggregation` package provides an expressive Python Query DSL with [Polars DataFrame](https://pola.rs) integrations. |
| [Vital Aggregation API endpoint](/api-reference/horizon-ai/aggregation/query-one)   | JSON API calls.                                                                                                                 |
| [Typed bindings of Vital API](/home/libraries)                                      | Call the Aggregation API in Go, Java, Node and Python.                                                                          |


# Create a Continuous Query
Source: https://docs.junction.com/api-reference/horizon-ai/continuous-query/create

post /v1/org/{org_id}/team/{team_id}/{environment}/continuous_query

<Card horizontal icon="person-digging" color="#57164A">
  Horizon AI Query is in **closed beta**.

  Interested in the Horizon AI Query? Get in touch with your Customer Success Manager.
</Card>

<Info>
  [Junction Management API](/api-details/junction-management-api) is available for [the Scale plan](https://tryvital.io/pricing).
</Info>

<Tip>
  The base URL of this endpoint is `https://api.tryvital.io/management/`.

  The endpoint accepts only [Management Key](/api-details/junction-management-api#authentication) (`X-Management-Key`).
  Team API Key is not accepted.
</Tip>


# Get User Result Table
Source: https://docs.junction.com/api-reference/horizon-ai/continuous-query/get-result-table

get /aggregate/v1/user/{user_id}/continuous_query/{query_id_or_slug}/result_table

<Card horizontal icon="person-digging" color="#57164A">
  Horizon AI Query is in **closed beta**.

  Interested in the Horizon AI Query? Get in touch with your Customer Success Manager.
</Card>


# Get Continuous Query Task History
Source: https://docs.junction.com/api-reference/horizon-ai/continuous-query/get-task-history

get /aggregate/v1/user/{user_id}/continuous_query/{query_id_or_slug}/task_history

<Card horizontal icon="person-digging" color="#57164A">
  Horizon AI Query is in **closed beta**.

  Interested in the Horizon AI Query? Get in touch with your Customer Success Manager.
</Card>


# List all Continuous Queries
Source: https://docs.junction.com/api-reference/horizon-ai/continuous-query/list

get /v1/org/{org_id}/team/{team_id}/{environment}/continuous_query

<Card horizontal icon="person-digging" color="#57164A">
  Horizon AI Query is in **closed beta**.

  Interested in the Horizon AI Query? Get in touch with your Customer Success Manager.
</Card>

<Info>
  [Junction Management API](/api-details/junction-management-api) is available for [the Scale plan](https://tryvital.io/pricing).
</Info>

<Tip>
  The base URL of this endpoint is `https://api.tryvital.io/management/`.

  The endpoint accepts only [Management Key](/api-details/junction-management-api#authentication) (`X-Management-Key`).
  Team API Key is not accepted.
</Tip>


# Update a Continuous Query
Source: https://docs.junction.com/api-reference/horizon-ai/continuous-query/update

patch /v1/org/{org_id}/team/{team_id}/{environment}/continuous_query/{query_id}

<Card horizontal icon="person-digging" color="#57164A">
  Horizon AI Query is in **closed beta**.

  Interested in the Horizon AI Query? Get in touch with your Customer Success Manager.
</Card>

<Info>
  [Junction Management API](/api-details/junction-management-api) is available for [the Scale plan](https://tryvital.io/pricing).
</Info>

<Tip>
  The base URL of this endpoint is `https://api.tryvital.io/management/`.

  The endpoint accepts only [Management Key](/api-details/junction-management-api#authentication) (`X-Management-Key`).
  Team API Key is not accepted.
</Tip>


# Getting Started
Source: https://docs.junction.com/api-reference/horizon-ai/python-sdk/getting-started


<Note>
  The [`vital` PyPI package](/home/libraries)  (Vital API Python SDK) provides typed bindings
  of the Vital API in Python that tracks our OpenAPI Schema.

  Horizon AI Python SDK is a standalone product offering, separately from the `vital` PyPI package.
</Note>

**Horizon AI Python SDK** bridges Vital's data aggregation and intelligence capabilities with the
rich Python ecosystem for scientific computing and data analysis.

## Authentication

<AccordionGroup>
  <Accordion title="Deployed Services" icon="server" defaultOpen>
    Use the same [Vital API Keys](/api-details/authentication#server-to-server) your system used to interact with Vital API.

    To set the Vital API Key for the Horizon AI Python SDK, you can:

    * Pass the Vital API Key explicitly to the Horizon AI SDK entity's constructor (e.g., the Query Executor); or
    * Set the Vital API Key as the `VITAL_API_KEY` environment variable.
  </Accordion>

  <Accordion title="Data Scientists and Developers" icon="user" defaultOpen>
    Sign-in locally on your machine with your [Vital Dashboard](https://app.tryvital.io/) account. You can
    do so through the [Horizon AI SDK Command Line Tool](#sdk-command-line-tool) as detailed below.
  </Accordion>
</AccordionGroup>

## Installation

### Aggregation API

<Steps>
  <Step title="Add a dependency">
    Add the `vitalx-aggregation` package to your project.

    ```bash
    poetry add vitalx-aggregation
    ```
  </Step>
</Steps>

### SDK Command Line Tool

<Steps>
  <Step title="Add a dependency">
    Add the `vitalx-cli` package as a dev dependency to your project.

    ```bash
    poetry add -G dev vitalx-cli
    ```
  </Step>

  <Step title="Start the device authentication process">
    Create the `~/.vitalx` directory, and grant it execute permission. The SDK requires execute
    permission to maintain a file lock.

    ```bash
    mkdir -p ~/.vitalx && chmod +x ~/.vitalx
    ```

    Call the `auth login` CLI subcommand on the `vitalx-cli` package to start the authentication
    process.

    ```bash
    poetry run vitalx-cli auth login
    ```
  </Step>

  <Step title="Sign in with your Vital Dashboard account">
    You would be prompted in your default web browser to sign-in to the [Vital Dashboard](https://app.tryvital.io/).
    You will then be asked to confirm the device authorization.

    <Frame>
      <img src="https://mintcdn.com/vital/img/horizon-ai/python-sdk-cli-signin.png?maxW=860&auto=format&n=nR1fvAlwouZ87zVb&q=85&s=f91837889fe6f5d65c91f41cb05ec1cf" alt="Device Confirmation prompt" width="300" width="860" height="1148" data-path="img/horizon-ai/python-sdk-cli-signin.png" srcset="https://mintcdn.com/vital/img/horizon-ai/python-sdk-cli-signin.png?w=280&maxW=860&auto=format&n=nR1fvAlwouZ87zVb&q=85&s=8d306d62974076f2f5b38eb40d240f05 280w, https://mintcdn.com/vital/img/horizon-ai/python-sdk-cli-signin.png?w=560&maxW=860&auto=format&n=nR1fvAlwouZ87zVb&q=85&s=c76dee7454de57c99fe6f1f7bdcc7e55 560w, https://mintcdn.com/vital/img/horizon-ai/python-sdk-cli-signin.png?w=840&maxW=860&auto=format&n=nR1fvAlwouZ87zVb&q=85&s=aa1d15f3fb57fae97441b0462b94f408 840w, https://mintcdn.com/vital/img/horizon-ai/python-sdk-cli-signin.png?w=1100&maxW=860&auto=format&n=nR1fvAlwouZ87zVb&q=85&s=87ad014a9b5fd2cf81fccf5576f593c6 1100w, https://mintcdn.com/vital/img/horizon-ai/python-sdk-cli-signin.png?w=1650&maxW=860&auto=format&n=nR1fvAlwouZ87zVb&q=85&s=8df2b663894755b470fe035ee0d2cfef 1650w, https://mintcdn.com/vital/img/horizon-ai/python-sdk-cli-signin.png?w=2500&maxW=860&auto=format&n=nR1fvAlwouZ87zVb&q=85&s=d007a2f8d5875118221b3bb941c368bb 2500w" data-optimize="true" data-opv="2" />
    </Frame>
  </Step>

  <Step title="Voila!">
    You have now signed-in. You can now use any Horizon AI SDK entity without a Vital API Key.

    <Note>
      Your permanent session is stored at `~/.vitalx/`.
    </Note>
  </Step>
</Steps>

## Example

[tryvital/vitalx-notebook](https://github.com/tryVital/vitalx-notebook) is a pre-configured Jupyter Notebook project
with dependencies on Aggregation API and SDK Command Line Tool pre-configured.

The notebook also includes an example to compute *Chronotypes* using the Aggregation API.


# Get ABN Form PDF
Source: https://docs.junction.com/api-reference/lab-testing/abn-pdf

GET /v3/order/{order_id}/abn_pdf
GET ABN pdf for an order

Retrieving ABNs is currently in closed beta.

When [getting an order](/api-reference/lab-testing/get-order#response-has-abn), you can view the `has_abn` field to determine if an ABN form is available for this order.

<RequestExample>
  ```bash cURL
  curl --request GET \
       --url '{{BASE_URL}}/v3/order/<order_id>/abn_pdf' \
       --header 'accept: application/pdf' \
       --header 'x-vital-api-key: {YOUR_KEY}'
       --output file.pdf
  ```

  ```python Python
  from vital import Client

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

  data = client.LabTests.get_order_abn_pdf(order_id='<order_id>');
  ```

  ```javascript Node
  import { VitalClient, VitalEnvironment } from '@tryvital/vital-node';

  const client = new VitalClient({
      apiKey: '<my_api_key>',
      environment: VitalEnvironment.Sandbox,
  });

  const data = await client.labTests.getOrderAbnPdf("<order_id>");
  ```

  ```java Java
  import com.vital.api.Vital;
  import com.vital.api.core.Environment;

  Vital vital = Vital.builder()
          .apiKey("YOUR_API_KEY")
          .environment(Environment.SANDBOX)
          .build();

  var data = vital.labTests().getOrderAbnPdf("<order_id>");
  ```

  ```go Go
  import (
    "context"

    vital "github.com/tryVital/vital-go"
    vitalclient "github.com/tryVital/vital-go/client"
    "github.com/tryVital/vital-go/option"
  )

  client := vitalclient.NewClient(
    option.WithApiKey("<YOUR_API_KEY>"),
    option.WithBaseURL(vital.Environments.Sandbox),
  )

  response, err := client.LabTests.getOrderAbnPdf(context.TODO(), "<order_id>")
  if err != nil {
    return err
  }
  fmt.Printf("Received data %s\n", response)
  ```
</RequestExample>


# Get Area Info
Source: https://docs.junction.com/api-reference/lab-testing/area-info

GET /v3/order/area/info
GET information about an area with respect to lab-testing.

Information returned:
* Whether a given zip code is served by our Phlebotomy network.
* List of Lab locations in the area.

<RequestExample>
  ```bash cURL
  curl --request GET \
       --url '{{BASE_URL}}/v3/order/area/info?zip_code=85004' \
       --header 'accept: application/json' \
       --header 'x-vital-api-key: {YOUR_KEY}'
  ```

  ```python Python
  from vital.client import Vital
  from vital.environment import VitalEnvironment

  client = Vital(
    api_key="YOUR_API_KEY",
    environment=VitalEnvironment.SANDBOX
  )

  data = client.lab_tests.get_area_info(zip_code="85004")
  ```

  ```javascript Node
  import { VitalClient, VitalEnvironment } from '@tryvital/vital-node';
  import { LabTestsGetAreaInfoRequest } from '@tryvital/vital-node/api/resources/labTests';

  const client = new VitalClient({
      apiKey: '<my_api_key>',
      environment: VitalEnvironment.Sandbox,
  });

  const request: LabTestsGetAreaInfoRequest = {
      zipCode: "85004"
  }

  const data = await client.labTests.getAreaInfo(request);
  ```

  ```java Java
  import com.vital.api.Vital;
  import com.vital.api.core.Environment;
  import com.vital.api.resources.labtests.requests.LabTestsGetAreaInfoRequest;

  Vital vital = Vital.builder()
          .apiKey("YOUR_API_KEY")
          .environment(Environment.SANDBOX)
          .build();

  LabTestsGetAreaInfoRequest request = LabTestsGetAreaInfoRequest.builder()
          .zipCode("85004")
          .build();

  var data = vital.labTests().getAreaInfo(request);
  ```

  ```go Go
  import (
    "context"

    vital "github.com/tryVital/vital-go"
    vitalclient "github.com/tryVital/vital-go/client"
    "github.com/tryVital/vital-go/option"
  )

  client := vitalclient.NewClient(
    option.WithApiKey("<YOUR_API_KEY>"),
    option.WithBaseURL(vital.Environments.Sandbox),
  )

  request := &vital.LabTestsGetAreaInfoRequest{
    ZipCode: "85004",
  }

  response, err := client.LabTests.GetAreaInfo(context.TODO(), request)
  if err != nil {
    return err
  }
  fmt.Printf("Received data %s\n", response)
  ```
</RequestExample>

<ResponseExample>
  ```json Response
  {
    "zip_code": "85004",
    "phlebotomy": {
      "is_served": true,
      "providers": [
          {
            "name": "getlabs",
            "tier": ["appointment-ready"]
          },
          {
            "name": "phlebfinders",
            "tier": ["appointment-request"]
          }
      ]
    },
    "central_labs": {
      "labcorp": {
        "patient_service_centers": {
          "within_radius": 5,
          "radius": "25",
          "capabilities": ["stat"]
        }
      }
    }
  }
  ```
</ResponseExample>


# Get Order Appointment Availability
Source: https://docs.junction.com/api-reference/lab-testing/at-home-phlebotomy/appointment-availability

POST /v3/order/phlebotomy/appointment/availability
Return the available time slots to book an appointment with a phlebotomist
for the given address and order.

<RequestExample>
  ```bash cURL
  curl --request POST \
       --url '{{BASE_URL}}/v3/order/phlebotomy/appointment/availability' \
       --header 'accept: application/json' \
       --header 'x-vital-api-key: {YOUR_KEY}' \
       --data '
  {
      "first_line": "256 West Lincoln Street",
      "second_line": "14",
      "city": "Phoenix",
      "state": "AZ",
      "zip_code": "85004",
  }
  '
  ```

  ```python Python
  from vital.client import Vital
  from vital.environment import VitalEnvironment
  from vital.types.us_address import UsAddress


  client = Vital(
    api_key="YOUR_API_KEY",
    environment=VitalEnvironment.SANDBOX
  )

  request = UsAddress(
      first_line="123 Main St",
      second_line="",
      city="San Francisco",
      state="CA",
      zip_code="94111",
      unit="",
  )


  data = client.lab_tests.get_phlebotomy_appointment_availability(request=request)
  ```

  ```javascript Node
  import { VitalClient, VitalEnvironment } from '@tryvital/vital-node';
  import { UsAddress } from '@tryvital/vital-node/api';

  const client = new VitalClient({
      apiKey: '<my_api_key>',
      environment: VitalEnvironment.Sandbox,
  });

  const request: UsAddress = {
      firstLine: "123 Main St",
      city: "San Francisco",
      state: "CA",
      zipCode: "94105",
  }

  const data = await client.labTests.getPhlebotomyAppointmentAvailability(request);
  ```

  ```java Java
  import com.vital.api.Vital;
  import com.vital.api.core.Environment;
  import com.vital.api.types.UsAddress;

  Vital vital = Vital.builder()
          .apiKey("YOUR_API_KEY")
          .environment(Environment.SANDBOX)
          .build();

  UsAddress request = UsAddress
      .builder()
      .firstLine("<first_line")
      .city("<city>")
      .state("<state>")
      .zipCode("<zip_code>")
      .build();

  var data = vital.labTests().getPhlebotomyAppointmentAvailability(request);
  ```

  ```go Go
  import (
    "context"

    vital "github.com/tryVital/vital-go"
    vitalclient "github.com/tryVital/vital-go/client"
    "github.com/tryVital/vital-go/option"
  )

  client := vitalclient.NewClient(
    option.WithApiKey("<YOUR_API_KEY>"),
    option.WithBaseURL(vital.Environments.Sandbox),
  )

  request := &vital.UsAddress{
      FirstLine: "123 Main St",
      City:      "New York",
      State:     "NY",
      ZipCode:   "10001",
  }

  response, err := client.LabTests.GetPhlebotomyAppointmentAvailability(context.TODO(), request)
  if err != nil {
      return err
  }
  fmt.Printf("Received data %s\n", response)
  ```
</RequestExample>

<ResponseExample>
  ```json Response
  {
      "timezone":"America/Phoenix",
      "slots": [
          {
              "date":"2023-05-09",
              "slots": [
                  {
                      "booking_key": "foo123",
                      "start": "2023-05-09T17:00:00+00:00",
                      "end": "2023-05-09T19:00:00+00:00",
                      "expires_at": "2023-05-09T12:39:57.827000+00:00",
                      "price": 3500,
                      "is_priority": true,
                      "num_appointments_available": 5
                  },
                  ...
              ],
          },
          {
              "date":"2023-05-10",
              "slots": [
                  {
                      "booking_key": "bar456",
                      "start": "2023-05-10T12:00:00+00:00",
                      "end": "2023-05-10T14:00:00+00:00",
                      "expires_at": "2023-05-09T12:39:57.852000+00:00",
                      "price": 7900,
                      "is_priority": true,
                      "num_appointments_available": 5
                  },
                  ...
              ],
          },
      ]
  }
  ```
</ResponseExample>


# Book Phlebotomy Appointment
Source: https://docs.junction.com/api-reference/lab-testing/at-home-phlebotomy/appointment-booking

POST /v3/order/{order_id}/phlebotomy/appointment/book
Book an at-home phlebotomy appointment.

<RequestExample>
  ```bash cURL
  curl --request POST \
       --url '{{BASE_URL}}/v3/order/413d7205-f8a9-42ed-aa4a-edb99e481ca0/phlebotomy/appointment/book' \
       --header 'accept: application/json' \
       --header 'x-vital-api-key: {YOUR_KEY}' \
       --data '
  {
      "booking_key": "foo123"
  }
  '
  ```

  ```python Python
  from vital.client import Vital
  from vital.environment import VitalEnvironment

  client = Vital(
    api_key="YOUR_API_KEY",
    environment=VitalEnvironment.SANDBOX
  )

  data = client.lab_tests.book_phlebotomy_appointment(order_id="<order_id>", booking_key="<booking_key>")
  ```

  ```javascript Node
  import { VitalClient, VitalEnvironment } from '@tryvital/vital-node';
  import { AppointmentBookingRequest } from '@tryvital/vital-node/api';

  const client = new VitalClient({
      apiKey: '<my_api_key>',
      environment: VitalEnvironment.Sandbox,
  });

  const request: AppointmentBookingRequest = {
      bookingKey: "<booking_key>",
  }
  const data = await client.labTests.bookPhlebotomyAppointment("<order_id>", request);
  ```

  ```java Java
  import com.vital.api.Vital;
  import com.vital.api.core.Environment;
  import com.vital.api.resources.labtests.requests.AppointmentBookingRequest;

  Vital vital = Vital.builder()
          .apiKey("YOUR_API_KEY")
          .environment(Environment.SANDBOX)
          .build();

  AppointmentBookingRequest request = AppointmentBookingRequest
          .builder()
          .bookingKey("<booking_key>")
          .build();

  var data = vital.labTests().bookPhlebotomyAppointment("<order_id>", request);
  ```

  ```go Go
  import (
    "context"

    vital "github.com/tryVital/vital-go"
    vitalclient "github.com/tryVital/vital-go/client"
    "github.com/tryVital/vital-go/option"
  )

  client := vitalclient.NewClient(
    option.WithApiKey("<YOUR_API_KEY>"),
    option.WithBaseURL(vital.Environments.Sandbox),
  )

  request := &vital.AppointmentBookingRequest{
      BookingKey: "<booking_key>",
  }

  response, err := client.LabTests.BookPhlebotomyAppointment(context.TODO(), "<order_id>", request)
  if err != nil {
      return err
  }
  fmt.Printf("Received data %s\n", response)
  ```
</RequestExample>

<ResponseExample>
  ```json Response
  {
      "id": "413d7205-f8a9-42ed-aa4a-edb99e481ca0",
      "user_id": "202b2c2f-fb4c-44dc-a4f8-621186fde227",
      "address": {
          "first_line": "West Lincoln Street",
          "second_line": "",
          "city": "Phoenix",
          "state": "AZ",
          "zip_code": "85004",
          "unit": "14"
      },
      "location": {
          "lng": -112.0772235,
          "lat": 33.4421912
      },
      "start_at": "2023-05-15T16:00:00+00:00",
      "end_at": "2023-05-15T18:00:00+00:00",
      "iana_timezone": "America/Phoenix",
      "type": "phlebotomy",
      "provider": "getlabs",
      "status": "pending",
      "provider_id": "e89eb489-7382-4966-bb14-7ab4763eba6c",
      "can_reschedule":true
  }
  ```
</ResponseExample>


# Get Phlebotomy Appointment Cancellation Reasons
Source: https://docs.junction.com/api-reference/lab-testing/at-home-phlebotomy/appointment-cancellation-reasons

GET /v3/order/phlebotomy/appointment/cancellation-reasons
Get the list of reasons for cancelling an at-home phlebotomy appointment.

<RequestExample>
  ```bash cURL
  curl --request GET \
       --url '{{BASE_URL}}/v3/order/phlebotomy/appointment/cancellation-reasons' \
       --header 'accept: application/json' \
       --header 'x-vital-api-key: {YOUR_KEY}'
  '
  ```

  ```python Python
  from vital.client import Vital
  from vital.environment import VitalEnvironment

  client = Vital(
    api_key="YOUR_API_KEY",
    environment=VitalEnvironment.SANDBOX
  )

  data = client.lab_tests.get_phlebotomy_appointment_cancellation_reason();
  ```

  ```javascript Node
  import { VitalClient, VitalEnvironment } from '@tryvital/vital-node';

  const client = new VitalClient({
      apiKey: '<my_api_key>',
      environment: VitalEnvironment.Sandbox,
  });

  const data = await client.labTests.getPhlebotomyAppointmentCancellationReason();
  ```

  ```java Java
  import com.vital.api.Vital;
  import com.vital.api.core.Environment;

  Vital vital = Vital.builder()
          .apiKey("YOUR_API_KEY")
          .environment(Environment.SANDBOX)
          .build();

  var data = vital.labTests().getPhlebotomyAppointmentCancellationReason();
  ```

  ```go Go
  import (
    "context"

    vital "github.com/tryVital/vital-go"
    vitalclient "github.com/tryVital/vital-go/client"
    "github.com/tryVital/vital-go/option"
  )

  client := vitalclient.NewClient(
    option.WithApiKey("<YOUR_API_KEY>"),
    option.WithBaseURL(vital.Environments.Sandbox),
  )

  response, err := client.LabTests.GetPhlebotomyAppointmentCancellationReason(context.TODO())
  if err != nil {
      return err
  }
  fmt.Printf("Received data %s\n", response)
  ```
</RequestExample>

<ResponseExample>
  ```json
  [
     {
        "id": "5c0257ef-6fea-4a22-b20a-3ddab573d5c9",
        "name": "Did not fast for appointment",
        "is_refundable": true
     },
     {
        "id": "448c519c-64b4-4497-ae73-622fa93371b3",
        "name": "Do not trust company",
        "is_refundable": true
     },
     {
        "id": "d378e152-12d1-433e-9dd1-e0410f9331dc",
        "name": "Getlabs cannot deliver to my preferred lab",
        "is_refundable": true
     },
     {
        "id": "5330c863-ac80-4316-901b-d305d0df74d5",
        "name": "No longer interested",
        "is_refundable": true
     },
     {
        "id": "2b9f23fd-163e-4483-bb10-90c74a67e0dc",
        "name": "Other",
        "is_refundable": true
     },
     {
        "id": "98f861dd-fe61-4817-a9d6-1b99b19cd0fb",
        "name": "Provider asked me to cancel",
        "is_refundable": true
     },
     {
        "id": "7dfd7da5-ed6e-40bb-a7e4-c8003f0c10a9",
        "name": "Scheduled for wrong patient",
        "is_refundable": true
     },
     {
        "id": "796da8c8-e654-4347-8ded-1026410c1976",
        "name": "Scheduled time no longer works",
        "is_refundable": true
     },
     {
        "id": "ba02af35-a34f-4a7a-abe5-5f766e8f6cd1",
        "name": "Unable to get lab order from provider",
        "is_refundable": true
     },
     {
        "id": "0c9425db-f11e-49c5-b976-3c0d1d4a4ea8",
        "name": "Wanted to book in-person appointment",
        "is_refundable": true
     },
     {
        "id": "2599a0ea-0b4a-42fe-8df6-d8f7c68182e7",
        "name": "Went to lab for appointment",
        "is_refundable": true
     }
  ]
  ```
</ResponseExample>


# Cancel Phlebotomy Appointment
Source: https://docs.junction.com/api-reference/lab-testing/at-home-phlebotomy/appointment-cancelling

PATCH /v3/order/{order_id}/phlebotomy/appointment/cancel
Cancel a previously booked at-home phlebotomy appointment.

<RequestExample>
  ```bash cURL
  curl --request PATCH \
       --url '{{BASE_URL}}/v3/order/413d7205-f8a9-42ed-aa4a-edb99e481ca0/phlebotomy/appointment/cancel' \
       --header 'accept: application/json' \
       --header 'x-vital-api-key: {YOUR_KEY}' \
       --data '
  {
      "cancellation_reason_id": "7dfd7da5-ed6e-40bb-a7e4-c8003f0c10a9"
  }
  '
  ```

  ```python Python
  from vital.client import Vital
  from vital.environment import VitalEnvironment

  client = Vital(
    api_key="YOUR_API_KEY",
    environment=VitalEnvironment.SANDBOX
  )

  data = client.lab_tests.get_phlebotomy_appointment_cancellation_reason();
  ```

  ```javascript Node
  import { VitalClient, VitalEnvironment } from '@tryvital/vital-node';
  import {  AppointmentCancelRequest } from '@tryvital/vital-node/api';

  const client = new VitalClient({
      apiKey: '<my_api_key>',
      environment: VitalEnvironment.Sandbox,
  });

  const request: AppointmentCancelRequest = {
      cancellationReasonId: "<reason_id>",
  }

  const data = await client.labTests.cancelPhlabotomyAppointment("<order_id>", request);
  ```

  ```java Java
  import com.vital.api.Vital;
  import com.vital.api.core.Environment;
  import com.vital.api.resources.labtests.requests.AppointmentCancelRequest;

  Vital vital = Vital.builder()
          .apiKey("YOUR_API_KEY")
          .environment(Environment.SANDBOX)
          .build();

  AppointmentCancelRequest request = AppointmentCancelRequest
          .builder()
          .cancellationReasonId("<reason_id")
          .build();

  var data = vital.labTests().cancelPhlabotomyAppointment("<order_id>", request);
  ```

  ```go Go
  import (
    "context"

    vital "github.com/tryVital/vital-go"
    vitalclient "github.com/tryVital/vital-go/client"
    "github.com/tryVital/vital-go/option"
  )

  client := vitalclient.NewClient(
    option.WithApiKey("<YOUR_API_KEY>"),
    option.WithBaseURL(vital.Environments.Sandbox),
  )

  request := &vital.AppointmentCancelRequest{
      CancellationReasonId: "<cancellation_reason_id>",
  }

  response, err := client.LabTests.CancelPhlabotomyAppointment(context.TODO(), "<order_id>", request)
  if err != nil {
      return err
  }
  fmt.Printf("Received data %s\n", response)
  ```
</RequestExample>

<ResponseExample>
  ```json Response
  {
      "id": "413d7205-f8a9-42ed-aa4a-edb99e481ca0",
      "user_id": "202b2c2f-fb4c-44dc-a4f8-621186fde227",
      "address": {
          "first_line": "West Lincoln Street",
          "second_line": "",
          "city": "Phoenix",
          "state": "AZ",
          "zip_code": "85004",
          "unit": "14"
      },
      "location": {
          "lng": -112.0772235,
          "lat": 33.4421912
      },
      "start_at": "2023-05-17T20:00:00+00:00",
      "end_at": "2023-05-17T22:00:00+00:00",
      "iana_timezone": "America/Phoenix",
      "type": "phlebotomy",
      "provider": "getlabs",
      "status": "cancelled",
      "provider_id": "e89eb489-7382-4966-bb14-7ab4763eba6c",
      "can_reschedule": true
  }
  ```
</ResponseExample>


# Request Phlebotomy Appointment
Source: https://docs.junction.com/api-reference/lab-testing/at-home-phlebotomy/appointment-request

POST /v3/order/{order_id}/phlebotomy/appointment/request
Request an at-home phlebotomy appointment.

<RequestExample>
  ```bash cURL
  curl --request POST \
       --url '{{BASE_URL}}/v3/order/413d7205-f8a9-42ed-aa4a-edb99e481ca0/phlebotomy/appointment/request' \
       --header 'accept: application/json' \
       --header 'x-vital-api-key: {YOUR_KEY}' \
       --data '
  {
      "address":
      {
          "first_line": "256 West Lincoln Street",
          "second_line": "14",
          "city": "Phoenix",
          "state": "AZ",
          "zip_code": "85004",
      }
      "provider": "phlebfinders"
  }
  '
  ```

  ```python Python
  from vital.client import Vital
  from vital.environment import VitalEnvironment

  client = Vital(
    api_key="YOUR_API_KEY",
    environment=VitalEnvironment.SANDBOX
  )

  request = RequestAppointmentRequest(
      address= UsAddress(
          first_line="123 Main St",
          second_line="",
          city="San Francisco",
          state="CA",
          zip_code="94111",
          unit="",
      ),
      provider="phlebfinders"
  )

  data = client.lab_tests.request_phlebotomy_appointment(order_id="<order_id>", request=request)
  ```

  ```javascript Node
  import { VitalClient, VitalEnvironment } from '@tryvital/vital-node';
  import { RequestAppointmentRequest } from '@tryvital/vital-node/api';

  const client = new VitalClient({
      apiKey: '<my_api_key>',
      environment: VitalEnvironment.Sandbox,
  });

  const address: UsAddress = {
      firstLine: "123 Main St",
      city: "San Francisco",
      state: "CA",
      zipCode: "94105",
  }

  const request: RequestAppointmentRequest = {
      address: address,
      provider: "phlebfinders"
  }

  const data = await client.labTests.requestPhlebotomyAppointment("<order_id>", request);
  ```

  ```java Java
  import com.vital.api.Vital;
  import com.vital.api.core.Environment;
  import com.vital.api.resources.labtests.requests.RequestAppointmentRequest;

  Vital vital = Vital.builder()
          .apiKey("YOUR_API_KEY")
          .environment(Environment.SANDBOX)
          .build();

  UsAddress address = UsAddress
      .builder()
      .firstLine("<first_line")
      .city("<city>")
      .state("<state>")
      .zipCode("<zip_code>")
      .build();

  RequestAppointmentRequest request = RequestAppointmentRequest
          .builder()
          .address(address)
          .provider("phlebfinders")
          .build();

  var data = vital.labTests().requestPhlebotomyAppointment("<order_id>", request);
  ```

  ```go Go
  import (
    "context"

    vital "github.com/tryVital/vital-go"
    vitalclient "github.com/tryVital/vital-go/client"
    "github.com/tryVital/vital-go/option"
  )

  client := vitalclient.NewClient(
    option.WithApiKey("<YOUR_API_KEY>"),
    option.WithBaseURL(vital.Environments.Sandbox),
  )

  address := &vital.UsAddress{
      FirstLine: "123 Main St",
      City:      "New York",
      State:     "NY",
      ZipCode:   "10001",
  }
  request := &vital.RequestAppointmentRequest{
      Address: address,
      Provider: "phlebfinders",
  }

  response, err := client.LabTests.RequestPhlebotomyAppointment(context.TODO(), "<order_id>", request)
  if err != nil {
      return err
  }
  fmt.Printf("Received data %s\n", response)
  ```
</RequestExample>

<ResponseExample>
  ```json Response
  {
      "id": "413d7205-f8a9-42ed-aa4a-edb99e481ca0",
      "user_id": "202b2c2f-fb4c-44dc-a4f8-621186fde227",
      "address": {
          "first_line": "West Lincoln Street",
          "second_line": "",
          "city": "Phoenix",
          "state": "AZ",
          "zip_code": "85004",
          "unit": "14"
      },
      "location": {
          "lng": -112.0772235,
          "lat": 33.4421912
      },
      "type": "phlebotomy",
      "provider": "phlebfinders",
      "status": "pending",
      "provider_id": "e89eb489-7382-4966-bb14-7ab4763eba6c",
      "can_reschedule":false
  }
  ```
</ResponseExample>


# Reschedule Phlebotomy Appointment
Source: https://docs.junction.com/api-reference/lab-testing/at-home-phlebotomy/appointment-rescheduling

PATCH /v3/order/{order_id}/phlebotomy/appointment/reschedule
Reschedule a previously booked at-home phlebotomy appointment.

<RequestExample>
  ```bash cURL
  curl --request PATCH \
       --url '{{BASE_URL}}/v3/order/413d7205-f8a9-42ed-aa4a-edb99e481ca0/phlebotomy/appointment/reschedule' \
       --header 'accept: application/json' \
       --header 'x-vital-api-key: {YOUR_KEY}' \
       --data '
  {
      "booking_key": "bar456"
  }
  '
  ```

  ```python Python
  from vital.client import Vital
  from vital.environment import VitalEnvironment

  client = Vital(
    api_key="YOUR_API_KEY",
    environment=VitalEnvironment.SANDBOX
  )

  data = client.lab_tests.reschedule_phlebotomy_appointment(order_id="<order_id>", booking_key="<booking_key>");
  ```

  ```javascript Node
  import { VitalClient, VitalEnvironment } from '@tryvital/vital-node';
  import {  AppointmentRescheduleRequest } from '@tryvital/vital-node/api';

  const client = new VitalClient({
      apiKey: '<my_api_key>',
      environment: VitalEnvironment.Sandbox,
  });

  const request: AppointmentRescheduleRequest = {
      bookingKey: "<reason_id>",
  }

  const data = await client.labTests.reschedulePhlebotomyAppointment("<order_id>", request);
  ```

  ```java Java
  import com.vital.api.Vital;
  import com.vital.api.core.Environment;
  import com.vital.api.resources.labtests.requests.AppointmentRescheduleRequest;

  Vital vital = Vital.builder()
          .apiKey("YOUR_API_KEY")
          .environment(Environment.SANDBOX)
          .build();

  AppointmentRescheduleRequest request = AppointmentRescheduleRequest
          .builder()
          .bookingKey("<booking_key>")
          .build();

  var data = vital.labTests().reschedulePhlebotomyAppointment("<order_id>", request);
  ```

  ```go Go
  import (
    "context"

    vital "github.com/tryVital/vital-go"
    vitalclient "github.com/tryVital/vital-go/client"
    "github.com/tryVital/vital-go/option"
  )

  client := vitalclient.NewClient(
    option.WithApiKey("<YOUR_API_KEY>"),
    option.WithBaseURL(vital.Environments.Sandbox),
  )

  request := &vital.AppointmentRescheduleRequest{
      BookingKey: "<booking_key>",
  }

  response, err := client.LabTests.ReschedulePhlebotomyAppointment(context.TODO(), "<order_id>", request)
  if err != nil {
      return err
  }
  fmt.Printf("Received data %s\n", response)
  ```
</RequestExample>

<ResponseExample>
  ```json Response
  {
      "id": "413d7205-f8a9-42ed-aa4a-edb99e481ca0",
      "user_id": "202b2c2f-fb4c-44dc-a4f8-621186fde227",
      "address": {
          "first_line": "West Lincoln Street",
          "second_line": "",
          "city": "Phoenix",
          "state": "AZ",
          "zip_code": "85004",
          "unit":"14"
      },
      "location": {
          "lng": -112.0772235,
          "lat": 33.4421912
      },
      "start_at": "2023-05-17T20:00:00+00:00",
      "end_at": "2023-05-17T22:00:00+00:00",
      "iana_timezone": "America/Phoenix",
      "type": "phlebotomy",
      "provider": "getlabs",
      "status": "pending",
      "provider_id": "e89eb489-7382-4966-bb14-7ab4763eba6c",
      "can_reschedule": true
  }
  ```
</ResponseExample>


# Get Phlebotomy Appointment
Source: https://docs.junction.com/api-reference/lab-testing/at-home-phlebotomy/get-appointment

GET /v3/order/{order_id}/phlebotomy/appointment
Get the appointment associated with an order.

<RequestExample>
  ```bash cURL
  curl --request GET \
       --url '{{BASE_URL}}/v3/order/413d7205-f8a9-42ed-aa4a-edb99e481ca0/phlebotomy/appointment' \
       --header 'accept: application/json' \
       --header 'x-vital-api-key: {YOUR_KEY}'
  ```

  ```python Python
  from vital.client import Vital
  from vital.environment import VitalEnvironment

  client = Vital(
    api_key="YOUR_API_KEY",
    environment=VitalEnvironment.SANDBOX
  )

  data = client.lab_tests.get_phlebotomy_appointment(order_id="<order_id>")
  ```

  ```javascript Node
  import { VitalClient, VitalEnvironment } from '@tryvital/vital-node';

  const client = new VitalClient({
      apiKey: '<my_api_key>',
      environment: VitalEnvironment.Sandbox,
  });

  const data = await client.labTests.getPhlebotomyAppointment("<order_id>");
  ```

  ```java Java
  import com.vital.api.Vital;
  import com.vital.api.core.Environment;

  Vital vital = Vital.builder()
          .apiKey("YOUR_API_KEY")
          .environment(Environment.SANDBOX)
          .build();

  var data = vital.labTests().getPhlebotomyAppointment("<order_id>");
  ```

  ```go Go
  import (
    "context"

    vital "github.com/tryVital/vital-go"
    vitalclient "github.com/tryVital/vital-go/client"
    "github.com/tryVital/vital-go/option"
  )

  client := vitalclient.NewClient(
    option.WithApiKey("<YOUR_API_KEY>"),
    option.WithBaseURL(vital.Environments.Sandbox),
  )

  response, err := client.LabTests.GetPhlebotomyAppointment(context.TODO(), "<order_id>")
  if err != nil {
      return err
  }
  fmt.Printf("Received data %s\n", response)
  ```
</RequestExample>

<ResponseExample>
  ```json Response
  {
      "id": "413d7205-f8a9-42ed-aa4a-edb99e481ca0",
      "user_id": "202b2c2f-fb4c-44dc-a4f8-621186fde227",
      "address": {
          "first_line": "West Lincoln Street",
          "second_line": "",
          "city": "Phoenix",
          "state": "AZ",
          "zip_code": "85004",
          "unit": "14"
      },
      "location": {
          "lng": -112.0772235,
          "lat": 33.4421912
      },
      "start_at": "2023-05-17T20:00:00+00:00",
      "end_at": "2023-05-17T22:00:00+00:00",
      "iana_timezone": "America/Phoenix",
      "type": "phlebotomy",
      "provider": "getlabs",
      "status": "pending",
      "provider_id": "e89eb489-7382-4966-bb14-7ab4763eba6c",
      "can_reschedule": true
  }
  ```
</ResponseExample>


# Get Available Biomarkers
Source: https://docs.junction.com/api-reference/lab-testing/biomarkers

GET /v3/lab_tests/markers
GET all the markers for the given lab.

<RequestExample>
  ```bash cURL
  curl --request GET \
       --url '{{BASE_URL}}/v3/lab_tests/markers' \
       --header 'accept: application/json' \
       --header 'x-vital-api-key: {YOUR_KEY}'
  ```

  ```python Python
  from vital.client import Vital
  from vital.environment import VitalEnvironment

  client = Vital(
    api_key="YOUR_API_KEY",
    environment=VitalEnvironment.SANDBOX
  )

  data = client.lab_tests.get_markers()
  ```

  ```javascript Node
  import { VitalClient, VitalEnvironment } from '@tryvital/vital-node';

  const client = new VitalClient({
      apiKey: '<my_api_key>',
      environment: VitalEnvironment.Sandbox,
  });

  const data = await client.labTests.getMarkers();
  ```

  ```java Java
  import com.vital.api.Vital;
  import com.vital.api.core.Environment;

  Vital vital = Vital.builder()
          .apiKey("YOUR_API_KEY")
          .environment(Environment.SANDBOX)
          .build();

  var data = vital.labTests().getMarkers(); 
  ```

  ```go Go
  import (
    "context"

    vital "github.com/tryVital/vital-go"
    vitalclient "github.com/tryVital/vital-go/client"
    "github.com/tryVital/vital-go/option"
  )

  client := vitalclient.NewClient(
    option.WithApiKey("<YOUR_API_KEY>"),
    option.WithBaseURL(vital.Environments.Sandbox),
  )

  response, err := client.LabTests.GetMarkers(context.TODO())
  if err != nil {
    return err
  }
  fmt.Printf("Received data %s\n", response)
  ```
</RequestExample>

<ResponseExample>
  ```json Response
  {
    "markers": [
        {
            "id": 202,
            "name": "Acetylcholine Receptor (AChR) Antibodies, Complete Profile with Reflex to MuSK Antibodies",
            "slug": "acetylcholine-receptor-achr-antibodies-complete-profile-with-reflex-to-musk-antibodies",
            "description": "Acetylcholine Receptor (AChR) Antibodies, Complete Profile with Reflex to MuSK Antibodies",
            "lab_id": 6,
            "provider_id": "165605",
            "type": "biomarker",
            "unit": null,
            "price": "N/A",
            "expected_results": [
                {
                    "id": 2938,
                    "name": "AChR Blocking Abs, Serum",
                    "slug": "achr-blocking-abs-serum",
                    "lab_id": 6,
                    "provider_id": "085927",
                    "loinc": {
                        "id": 3514,
                        "name": "Acetylcholine receptor blocking Ab Qn (S)",
                        "slug": "acetylcholine-receptor-blocking-ab-qn-s",
                        "code": "11561-8",
                        "unit": "%{inhibition}"
                    }
                },
                {
                    "id": 2939,
                    "name": "AChR Binding Abs, Serum",
                    "slug": "achr-binding-abs-serum",
                    "lab_id": 6,
                    "provider_id": "085904",
                    "loinc": {
                        "id": 3174,
                        "name": "Acetylcholine receptor binding Ab (S) [Moles/Vol]",
                        "slug": "acetylcholine-receptor-binding-ab-s-moles-vol",
                        "code": "11034-6",
                        "unit": "nmol/L"
                    }
                },
                {
                    "id": 2940,
                    "name": "AChR-modulating Ab",
                    "slug": "achr-modulating-ab",
                    "lab_id": 6,
                    "provider_id": "505199",
                    "loinc": {
                        "id": 61121,
                        "name": "Acetylcholine receptor modulation Ab FC Ql (S)",
                        "slug": "acetylcholine-receptor-modulation-ab-fc-ql-s",
                        "code": "99062-2",
                        "unit": null
                    }
                }
            ]
        },
    ],
    "total": 2,
    "page": 1,
    "size": 2
  }
  ```
</ResponseExample>


# Cancel Order
Source: https://docs.junction.com/api-reference/lab-testing/cancel-order

POST /v3/order/{order_id}/cancel
POST cancel order

<RequestExample>
  ```python Python
  from vital import Client

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

  data = client.LabTests.cancel_order(order_id='<order_id>');
  ```

  ```javascript Node
  import { VitalClient, VitalEnvironment } from '@tryvital/vital-node';

  const client = new VitalClient({
      apiKey: '<my_api_key>',
      environment: VitalEnvironment.Sandbox,
  });

  const data = await client.labTests.cancelOrder("<order_id>");
  ```

  ```java Java
  import com.vital.api.Vital;
  import com.vital.api.core.Environment;

  Vital vital = Vital.builder()
          .apiKey("YOUR_API_KEY")
          .environment(Environment.SANDBOX)
          .build();

  var data = vital.labTests().cancelOrder("<order_id>");
  ```

  ```go Go
  import (
    "context"

    vital "github.com/tryVital/vital-go"
    vitalclient "github.com/tryVital/vital-go/client"
    "github.com/tryVital/vital-go/option"
  )

  client := vitalclient.NewClient(
    option.WithApiKey("<YOUR_API_KEY>"),
    option.WithBaseURL(vital.Environments.Sandbox),
  )

  response, err := client.LabTests.CancelOrder(context.TODO(), "<order_id>")
  if err != nil {
    return err
  }
  fmt.Printf("Received data %s\n", response)
  ```
</RequestExample>

<ResponseExample>
  ```json Response
  [
    {
      "order": {
        "title": "ClientFacingOrder",
        "required": [
          "user_id",
          "id",
          "team_id",
          "patient_details",
          "patient_address",
          "lab_test",
          "details",
          "created_at",
          "updated_at",
          "events"
        ],
        "type": "object",
        "properties": {
          "user_id": {
            "title": "User Id",
            "type": "string",
            "description": "User id returned by vital create user request. This id should be stored in your database against the user and used for all interactions with the vital api.",
            "format": "uuid"
          },
          "user_key": {
            "title": "User Key",
            "type": "string",
            "description": "User key returned by vital create user key request. This key should be stored in your database against the user and used for all interactions with the vital api.",
            "format": "uuid",
            "deprecated": true
          },
          "id": {
            "title": "Id",
            "type": "string",
            "description": "The Vital Order ID",
            "format": "uuid"
          },
          "team_id": {
            "title": "Team Id",
            "type": "string",
            "description": "Your team id.",
            "format": "uuid"
          },
          "patient_details": {
            "title": "Patient Details",
            "allOf": [
              {
                "title": "PatientDetails",
                "required": ["dob", "gender"],
                "type": "object",
                "properties": {
                  "dob": {
                    "title": "Dob",
                    "type": "string",
                    "format": "date-time"
                  },
                  "gender": {
                    "title": "Gender",
                    "type": "string"
                  },
                  "email": {
                    "title": "Email",
                    "type": "string"
                  }
                }
              }
            ],
            "description": "Patient Details"
          },
          "patient_address": {
            "title": "Patient Address",
            "allOf": [
              {
                "title": "PatientAddress",
                "required": [
                  "receiver_name",
                  "street",
                  "city",
                  "state",
                  "zip",
                  "country",
                  "phone_number"
                ],
                "type": "object",
                "properties": {
                  "receiver_name": {
                    "title": "Receiver Name",
                    "type": "string"
                  },
                  "street": {
                    "title": "Street",
                    "type": "string"
                  },
                  "street_number": {
                    "title": "Street Number",
                    "type": "string"
                  },
                  "city": {
                    "title": "City",
                    "type": "string"
                  },
                  "state": {
                    "title": "State",
                    "type": "string"
                  },
                  "zip": {
                    "title": "Zip",
                    "type": "string"
                  },
                  "country": {
                    "title": "Country",
                    "type": "string"
                  },
                  "phone_number": {
                    "title": "Phone Number",
                    "type": "string"
                  }
                }
              }
            ],
            "description": "Patient Address"
          },
          "lab_test": {
            "title": "Lab Test",
            "allOf": [
              {
                "title": "LabTestInDB",
                "required": [
                  "slug",
                  "name",
                  "sample_type",
                  "method",
                  "lab_id",
                  "price",
                  "is_active",
                  "created_at",
                  "updated_at",
                  "id"
                ],
                "type": "object",
                "properties": {
                  "slug": {
                    "title": "Slug",
                    "type": "string"
                  },
                  "name": {
                    "title": "Name",
                    "type": "string"
                  },
                  "description": {
                    "title": "Description",
                    "type": "string"
                  },
                  "sample_type": {
                    "title": "LabTestSampleType",
                    "enum": ["dried_blood_spot"],
                    "type": "string",
                    "description": "The type of sample used to perform a lab test."
                  },
                  "method": {
                    "title": "LabTestMethod",
                    "enum": ["testkit", "walk_in_test"],
                    "type": "string",
                    "description": "The method used to perform a lab test."
                  },
                  "lab_id": {
                    "title": "Lab Id",
                    "type": "integer"
                  },
                  "skus": {
                    "title": "Skus",
                    "type": "array",
                    "items": {
                      "type": "object"
                    }
                  },
                  "price": {
                    "title": "Price",
                    "type": "number"
                  },
                  "is_active": {
                    "title": "Is Active",
                    "type": "boolean"
                  },
                  "turnaround_time_lower": {
                    "title": "Turnaround Time Lower",
                    "type": "integer"
                  },
                  "turnaround_time_upper": {
                    "title": "Turnaround Time Upper",
                    "type": "integer"
                  },
                  "created_at": {
                    "title": "Created At",
                    "type": "string",
                    "format": "date-time"
                  },
                  "updated_at": {
                    "title": "Updated At",
                    "type": "string",
                    "format": "date-time"
                  },
                  "id": {
                    "title": "Id",
                    "type": "string",
                    "format": "uuid"
                  },
                  "lab": {
                    "title": "LabInDB",
                    "required": [
                      "slug",
                      "name",
                      "first_line_address",
                      "city",
                      "zipcode",
                      "id"
                    ],
                    "type": "object",
                    "properties": {
                      "slug": {
                        "title": "Slug",
                        "type": "string"
                      },
                      "name": {
                        "title": "Name",
                        "type": "string"
                      },
                      "first_line_address": {
                        "title": "First Line Address",
                        "type": "string"
                      },
                      "city": {
                        "title": "City",
                        "type": "string"
                      },
                      "zipcode": {
                        "title": "Zipcode",
                        "type": "string"
                      },
                      "clia": {
                        "title": "Clia",
                        "type": "string"
                      },
                      "created_at": {
                        "title": "Created At",
                        "type": "string",
                        "format": "date-time"
                      },
                      "updated_at": {
                        "title": "Updated At",
                        "type": "string",
                        "format": "date-time"
                      },
                      "id": {
                        "title": "Id",
                        "type": "integer"
                      }
                    }
                  },
                  "markers": {
                    "title": "Markers",
                    "type": "array",
                    "items": {
                      "title": "MarkerInDB",
                      "required": ["name", "slug", "description", "id"],
                      "type": "object",
                      "properties": {
                        "name": {
                          "title": "Name",
                          "type": "string"
                        },
                        "slug": {
                          "title": "Slug",
                          "type": "string"
                        },
                        "description": {
                          "title": "Description",
                          "type": "string"
                        },
                        "created_at": {
                          "title": "Created At",
                          "type": "string",
                          "format": "date-time"
                        },
                        "updated_at": {
                          "title": "Updated At",
                          "type": "string",
                          "format": "date-time"
                        },
                        "id": {
                          "title": "Id",
                          "type": "integer"
                        }
                      }
                    }
                  }
                },
                "description": "Schema for a LabTest in the database."
              }
            ],
            "description": "The Vital Test associated with the order"
          },
          "details": {
            "title": "Details",
            "anyOf": [
              {
                "title": "ClientFacingWalkInOrderDetails",
                "required": ["type"],
                "type": "object",
                "properties": {
                  "type": {
                    "title": "Type",
                    "enum": ["walk_in_test"],
                    "type": "string"
                  },
                  "data": {
                    "title": "ClientFacingWalkInTestOrder",
                    "required": ["id", "created_at", "updated_at"],
                    "type": "object",
                    "properties": {
                      "id": {
                        "title": "Id",
                        "type": "string",
                        "description": "The Vital walk-in test Order ID",
                        "format": "uuid"
                      },
                      "created_at": {
                        "title": "Created At",
                        "type": "string",
                        "format": "date-time"
                      },
                      "updated_at": {
                        "title": "Updated At",
                        "type": "string",
                        "format": "date-time"
                      }
                    },
                    "description": "Schema for a walk-in test order in the client facing API.\n\nTo be used as part of a ClientFacingOrder.",
                    "example": {
                      "id": "0651ee15-31a1-461b-9c10-86aa960da6c9",
                      "created_at": "2020-01-01T00:00:00Z",
                      "updated_at": "2020-01-01T00:00:00Z"
                    }
                  }
                }
              },
              {
                "title": "ClientFacingTestKitOrderDetails",
                "required": ["type"],
                "type": "object",
                "properties": {
                  "type": {
                    "title": "Type",
                    "enum": ["testkit"],
                    "type": "string"
                  },
                  "data": {
                    "title": "ClientFacingTestkitOrder",
                    "required": ["id", "created_at", "updated_at"],
                    "type": "object",
                    "properties": {
                      "id": {
                        "title": "Id",
                        "type": "string",
                        "description": "The Vital TestKit Order ID",
                        "format": "uuid"
                      },
                      "shipment": {
                        "title": "Shipment",
                        "allOf": [
                          {
                            "title": "ClientFacingShipment",
                            "required": [
                              "id",
                              "outbound_tracking_number",
                              "outbound_tracking_url",
                              "inbound_tracking_number",
                              "inbound_tracking_url",
                              "outbound_courier",
                              "inbound_courier",
                              "notes"
                            ],
                            "type": "object",
                            "properties": {
                              "id": {
                                "title": "Id",
                                "type": "string",
                                "description": "The Vital Shipment ID",
                                "format": "uuid"
                              },
                              "outbound_tracking_number": {
                                "title": "Outbound Tracking Number",
                                "type": "string",
                                "description": "Tracking number for delivery to customer"
                              },
                              "outbound_tracking_url": {
                                "title": "Outbound Tracking Url",
                                "type": "string",
                                "description": "Tracking url for delivery to customer"
                              },
                              "inbound_tracking_number": {
                                "title": "Inbound Tracking Number",
                                "type": "string",
                                "description": "Tracking number for delivery to lab"
                              },
                              "inbound_tracking_url": {
                                "title": "Inbound Tracking Url",
                                "type": "string",
                                "description": "Tracking url for delivery to lab"
                              },
                              "outbound_courier": {
                                "title": "Outbound Courier",
                                "type": "string",
                                "description": "Courier used for delivery to customer"
                              },
                              "inbound_courier": {
                                "title": "Inbound Courier",
                                "type": "string",
                                "description": "Courier used for delivery to lab"
                              },
                              "notes": {
                                "title": "Notes",
                                "type": "string",
                                "description": "Notes associated to the Vital shipment"
                              }
                            },
                            "description": "Schema for a Shipment in the client facing API.\n\nTo be used as part of a ClientFacingTestkitOrder.",
                            "example": {
                              "id": "dcab86c6-a315-493d-97aa-2fd0fa649130",
                              "outbound_tracking_number": "<outbound_tracking_number>",
                              "outbound_tracking_url": "<outbound_tracking_url>",
                              "inbound_tracking_number": "<inbound_tracking_number>",
                              "inbound_tracking_url": "<inbound_tracking_url>",
                              "outbound_courier": "usps",
                              "inbound_courier": "usps",
                              "notes": "<notes>"
                            }
                          }
                        ],
                        "description": "Shipment object"
                      },
                      "created_at": {
                        "title": "Created At",
                        "type": "string",
                        "format": "date-time"
                      },
                      "updated_at": {
                        "title": "Updated At",
                        "type": "string",
                        "format": "date-time"
                      }
                    },
                    "description": "Schema for a testkit order in the client facing API.\n\nTo be used as part of a ClientFacingOrder.",
                    "example": {
                      "id": "43697a79-298f-43db-9703-e4cf16006c66",
                      "shipment": {
                        "id": "51caeb91-cc5c-4f82-a4c2-6f23b68e54c5",
                        "outbound_tracking_number": "<outbound_tracking_number>",
                        "outbound_tracking_url": "<outbound_tracking_url>",
                        "inbound_tracking_number": "<inbound_tracking_number>",
                        "inbound_tracking_url": "<inbound_tracking_url>",
                        "outbound_courier": "usps",
                        "inbound_courier": "usps",
                        "notes": "<notes>",
                        "created_at": "2020-01-01T00:00:00.000Z",
                        "updated_at": "2020-01-01T00:00:00.000Z"
                      },
                      "created_at": "2020-01-01T00:00:00Z",
                      "updated_at": "2020-01-01T00:00:00Z"
                    }
                  }
                }
              }
            ]
          },
          "sample_id": {
            "title": "Sample Id",
            "type": "string",
            "description": "Sample ID"
          },
          "notes": {
            "title": "Notes",
            "type": "string",
            "description": "Notes associated with the order"
          },
          "created_at": {
            "title": "Created At",
            "type": "string",
            "description": "When your order was created",
            "format": "date-time"
          },
          "updated_at": {
            "title": "Updated At",
            "type": "string",
            "description": "When your order was last updated",
            "format": "date-time"
          },
          "events": {
            "title": "Events",
            "type": "array",
            "items": {
              "title": "ClientFacingOrderEvent",
              "required": ["id", "created_at", "status"],
              "type": "object",
              "properties": {
                "id": {
                  "title": "Id",
                  "type": "integer"
                },
                "created_at": {
                  "title": "Created At",
                  "type": "string",
                  "format": "date-time"
                },
                "status": {
                  "title": "OrderV2Status",
                  "enum": [
                    "received.walk_in_test.requisition_created",
                    "completed.walk_in_test.order_completed",
                    "failed.walk_in_test.sample_error",
                    "received.testkit.ordered",
                    "received.testkit.requisition_created",
                    "collecting_sample.testkit.transit_customer",
                    "collecting_sample.testkit.out_for_delivery",
                    "collecting_sample.testkit.with_customer",
                    "collecting_sample.testkit.transit_lab",
                    "collecting_sample.testkit.problem_in_transit_customer",
                    "collecting_sample.testkit.problem_in_transit_lab",
                    "sample_with_lab.testkit.delivered_to_lab",
                    "completed.testkit.completed",
                    "failed.testkit.failure_to_deliver_to_customer",
                    "failed.testkit.failure_to_deliver_to_lab",
                    "failed.testkit.sample_error",
                    "failed.testkit.lost",
                    "cancelled.testkit.cancelled",
                    "cancelled.testkit.do_not_process"
                  ],
                  "type": "string",
                  "description": "An enumeration."
                }
              }
            }
          },
          "status": {
            "title": "OrderV2TopLevelStatus",
            "enum": [
              "received",
              "collecting_sample",
              "sample_with_lab",
              "completed",
              "cancelled",
              "failed"
            ],
            "type": "string",
            "description": "An enumeration."
          }
        },
        "example": {
          "id": "0ee312e2-6773-4a21-a6e1-506882cd98ed",
          "team_id": "cbb64555-af07-46c1-be09-ef89308e9b60",
          "user_id": "94e2d9f2-d600-4a23-9f08-536df378e2c7",
          "patient_details": {
            "dob": "2020-01-01",
            "gender": "male"
          },
          "patient_address": {
            "receiver_name": "John Doe",
            "first_line": "123 Main St.",
            "second_line": "Apt. 208",
            "city": "San Francisco",
            "state": "CA",
            "zip": "91189",
            "country": "United States",
            "phone_number": "+1123456789"
          },
          "details": {
            "type": "testkit",
            "data": {
              "id": "a655f0e4-6405-4a1d-80b7-66f06c2108a7",
              "shipment": {
                "id": "d55210cc-3d9f-4115-8262-5013f700c7be",
                "outbound_tracking_number": "<outbound_tracking_number>",
                "outbound_tracking_url": "<outbound_tracking_url>",
                "inbound_tracking_number": "<inbound_tracking_number>",
                "inbound_tracking_url": "<inbound_tracking_url>",
                "outbound_courier": "usps",
                "inbound_courier": "usps",
                "notes": "<notes>",
                "created_at": "2020-01-01T00:00:00.000Z",
                "updated_at": "2020-01-01T00:00:00.000Z"
              },
              "created_at": "2020-01-01T00:00:00Z",
              "updated_at": "2020-01-01T00:00:00Z"
            }
          },
          "lab_test": {
            "name": "Lipids Panel",
            "description": "Cholesterol test",
            "method": "testkit"
          },
          "sample_id": "123456789",
          "notes": "This is a note",
          "created_at": "2020-01-01T00:00:00Z",
          "updated_at": "2020-01-01T00:00:00Z",
          "status": "collecting_sample",
          "events": [
            {
              "id": 1,
              "created_at": "2022-01-01T00:00:00Z",
              "status": "received.testkit.ordered"
            },
            {
              "id": 2,
              "created_at": "2022-01-02T00:00:00Z",
              "status": "received.testkit.requisition_created"
            },
            {
              "id": 3,
              "created_at": "2022-01-03T00:00:00Z",
              "status": "collecting_sample.testkit.transit_customer"
            }
          ]
        }
      },
      "status": {
        "title": "Status",
        "type": "string"
      },
      "message": {
        "title": "Message",
        "type": "string"
      }
    }
  ]
  ```
</ResponseExample>


# Create Order
Source: https://docs.junction.com/api-reference/lab-testing/create-order

POST /v3/order

<RequestExample>
  ```python Python
  from vital.client import Vital
  from vital.environment import VitalEnvironment
  from vital.types.gender import Gender
  from vital.types.patient_address_compatible import PatientAddressCompatible
  from vital.types.patient_details import PatientDetails
  from datetime import datetime

  client = Vital(
    api_key="YOUR_API_KEY",
    environment=VitalEnvironment.SANDBOX
  )

  data = client.lab_tests.create_order(
      user_id="63661a2b-2bb3-4125-bb1a-b590f64f057f",
      lab_test_id="5b41f610-ebc5-4803-8f0c-a61c3bdc7faf",
      patient_details=PatientDetails(
          first_name="John",
          last_name="Doe",
          dob=datetime.fromisoformat("2020-01-01"),
          gender=Gender.MALE,
          phone_number="+1123456789",
          email="email@email.com"
      ),
      patient_address=PatientAddressCompatible(
        receiver_name="john Doe",
        first_line="123 Main St.",
        second_line="Apt. 208",
        city="San Francisco",
        state="CA",
        zip="91189",
        country="US",
        phone_number="+1123456789"
      ),
  )
  ```

  ```javascript Node
  import { VitalClient, VitalEnvironment } from '@tryvital/vital-node';
  import { CreateOrderRequestCompatible} from '@tryvital/vital-node/api/resources/labTests';
  import { Gender } from '@tryvital/vital-node/api';

  const client = new VitalClient({
      apiKey: '<my_api_key>',
      environment: VitalEnvironment.Sandbox,
  });

  const request: CreateOrderRequestCompatible = {
      userId: "63661a2b-2bb3-4125-bb1a-b590f64f057f",
      labTestId: "5b41f610-ebc5-4803-8f0c-a61c3bdc7faf",
      patientDetails: {
          firstName: "John",
          lastName: "Doe",
          dob: new Date("2020-01-01"),
          gender: Gender.Male,
          phoneNumber: "+1123456789",
          email: "email@email.com"
      },
      patientAddress: {
        receiverName: "john Doe",
        first_line: "123 Main St.",
        second_line: "Apt. 208",
        city: "San Francisco",
        state: "CA",
        zip: "91189",
        country: "US",
        phoneNumber: "+1123456789"
      },
  }

  const data = await client.labTests.createOrder(request)
  ```

  ```java Java
  import com.vital.api.Vital;
  import com.vital.api.core.Environment;
  import com.vital.api.resources.labtests.requests.LabTestsGetAreaInfoRequest;

  Vital vital = Vital.builder()
        .apiKey("YOUR_API_KEY")
        .environment(Environment.SANDBOX)
        .build();

  PatientDetails details = PatientDetails.builder()
        .firstName("John")
        .lastName("Doe")
        .dob(OffsetDateTime.parse("2020-01-01"))
        .gender(Gender.MALE)
        .phoneNumber("+1123456789")
        .email("email@email.com")
        .build();

  PatientAddressCompatible address = PatientAddressCompatible
        .builder()
        .first_line("123 Main St.")
        .city("San Francisco")
        .state("CA")
        .zip("91189")
        .country("US")
        .phoneNumber("+1123456789")
        .build();

  CreateOrderRequestCompatible request = CreateOrderRequestCompatible
        .builder()
        .userId("63661a2b-2bb3-4125-bb1a-b590f64f057f")
        .labTestId("5b41f610-ebc5-4803-8f0c-a61c3bdc7faf")
        .patientDetails(details)
        .patientAddress(address)
        .build();

  var data = vital.labTests().createOrder(request);
  ```

  ```go Go
  import (
    "context"

    vital "github.com/tryVital/vital-go"
    vitalclient "github.com/tryVital/vital-go/client"
    "github.com/tryVital/vital-go/option"
  )

  client := vitalclient.NewClient(
    option.WithApiKey("<YOUR_API_KEY>"),
    option.WithBaseURL(vital.Environments.Sandbox),
  )

  details := &vital.PatientDetails{
     FirstName:   "John",
     LastName:    "Doe",
     Dob:         time.Date(2020, 1, 1, 0, 0, 0, 0, time.UTC),
     Gender:      vital.GenderMale,
     PhoneNumber: "+1123456789",
     Email:       "email@email.com",
  }

  address := &vital.PatientAddressCompatible{
     ReceiverName: vital.String("john Doe"),
     FirstLine:    "123 Main St.",
     SecondLine:   vital.String("Apt. 208"),
     City:         "San Francisco",
     State:        "CA",
     Zip:          "91189",
     Country:      "US",
     PhoneNumber:  vital.String("+1123456789"),
  }

  request := &vital.CreateOrderRequestCompatible{
     UserId:         "63661a2b-2bb3-4125-bb1a-b590f64f057f",
     LabTestId:      "5b41f610-ebc5-4803-8f0c-a61c3bdc7faf",
     PatientDetails: details,
     PatientAddress: address,
  }

  response, err := client.LabTests.CreateOrder(context.TODO(), request)
  if err != nil {
     return err
  }
  fmt.Printf("Received data %s\n", response)
  ```
</RequestExample>

<ResponseExample>
  ```json Response
  {
     "order": {
        "id": "ea7eae96-2c25-404f-b043-bfc08584610d",
        "team_id": "c26a9cc7-cdff-4f23-a5f6-74d40088c16a",
        "user_id": "63661a2b-2bb3-4125-bb1a-b590f64f057f",
        "patient_details": {
           "dob": "2020-01-01",
           "gender": "male"
        },
        "patient_address": {
           "receiver_name": "John Doe",
           "first_line": "123 Main St.",
           "second_line": "Apt. 208",
           "city": "San Francisco",
           "state": "CA",
           "zip": "91189",
           "country": "United States",
           "phone_number": "+1123456789"
        },
        "priority": false,
        "health_insurance_id": "33ec11aa-d8bf-4f46-950d-c9171be3c22f",
        "details": {
           "type": "testkit",
           "data": {
           "id": "a655f0e4-6405-4a1d-80b7-66f06c2108a7",
           "shipment": {
              "id": "d55210cc-3d9f-4115-8262-5013f700c7be",
              "outbound_tracking_number": "<outbound_tracking_number>",
              "outbound_tracking_url": "<outbound_tracking_url>",
              "inbound_tracking_number": "<inbound_tracking_number>",
              "inbound_tracking_url": "<inbound_tracking_url>",
              "outbound_courier": "usps",
              "inbound_courier": "usps",
              "notes": "<notes>",
              "created_at": "2020-01-01T00:00:00.000Z",
              "updated_at": "2020-01-01T00:00:00.000Z"
           },
           "created_at": "2020-01-01T00:00:00Z",
           "updated_at": "2020-01-01T00:00:00Z"
           }
        },
        "lab_test": {
           "name": "Lipids Panel",
           "description": "Cholesterol test",
           "method": "testkit"
        },
        "sample_id": "123456789",
        "notes": "This is a note",
        "created_at": "2020-01-01T00:00:00Z",
        "updated_at": "2020-01-01T00:00:00Z",
        "status": "collecting_sample",
        "events": [
           {
           "id": 1,
           "created_at": "2022-01-01T00:00:00Z",
           "status": "received.testkit.ordered"
           },
           {
           "id": 2,
           "created_at": "2022-01-02T00:00:00Z",
           "status": "received.testkit.requisition_created"
           },
           {
           "id": 3,
           "created_at": "2022-01-03T00:00:00Z",
           "status": "collecting_sample.testkit.transit_customer"
           }
        ]
     },
     "status": "string",
     "message": "string"
  }
  ```
</ResponseExample>


# Create Unregistered Testkit Order
Source: https://docs.junction.com/api-reference/lab-testing/create-unregistered-order

POST /v3/order/testkit
Creates an order for an unregistered testkit

<RequestExample>
  ```python Python
  from vital import Client

  client = Client(api_key, "sandbox")

  data = client.LabTests.create_unregistered_testkit_order(
    user_id="63661a2b-2bb3-4125-bb1a-b590f64f057f",
    lab_test_id="5b41f610-ebc5-4803-8f0c-a61c3bdc7faf",
    shipping_details={
      "receiver_name": "john Doe",
      "street": "123 Main St.",
      "street_number": "Apt. 208",
      "city": "San Francisco",
      "state": "CA",
      "zip": "91189",
      "country": "US",
      "phone_number": "+11234567890"
    }
  )
  ```

  ```javascript Node
  import { VitalClient, VitalEnvironment } from '@tryvital/vital-node';
  import { CreateRegistrableTestkitOrderRequest} from '@tryvital/vital-node/api/resources/testkit';

  const client = new VitalClient({
      apiKey: '<my_api_key>',
      environment: VitalEnvironment.Sandbox,
  });

  const request: CreateRegistrableTestkitOrderRequest = {
      userId: "<user_id>",
      labTestId: "<lab_test_id>",
      shippingDetails: {
          receiverName: "<receiver_name>",
          firstLine: "<address_1>",
          city: "<city>",
          state: "<state>",
          zip: "<zip>",
          country: "<country>",
          phoneNumber: "<phone_number>",
      },
  };

  const data = await client.testkit.createOrder(request);
  ```

  ```java Java
  import com.vital.api.Vital;
  import com.vital.api.core.Environment;

  Vital vital = Vital.builder()
          .apiKey("YOUR_API_KEY")
          .environment(Environment.SANDBOX)
          .build();

  var data = vital.labTests().getOrder("<order_id>");
  ```

  ```go Go
  import (
    "context"

    vital "github.com/tryVital/vital-go"
    vitalclient "github.com/tryVital/vital-go/client"
    "github.com/tryVital/vital-go/option"
  )

  client := vitalclient.NewClient(
    option.WithApiKey("<YOUR_API_KEY>"),
    option.WithBaseURL(vital.Environments.Sandbox),
  )

  response, err := client.LabTests.GetOrders(context.TODO(), "<order_id>")
  if err != nil {
    return err
  }
  fmt.Printf("Received data %s\n", response)
  ```

  ```bash cURL
  curl --request POST \
       --url https://api.tryvital.io/v3/order/testkit/ \
       --header 'Accept: application/json'
       --header 'x-vital-api-key: <API_KEY>' \
       --data '
  {
      "user_id": "63661a2b-2bb3-4125-bb1a-b590f64f057f",
      "lab_test_id": "5b41f610-ebc5-4803-8f0c-a61c3bdc7faf",
      "shipping_details": {
        "receiver_name": "john Doe",
        "street": "123 Main St.",
        "street_number": "Apt. 208",
        "city": "San Francisco",
        "state": "CA",
        "zip": "91189",
        "country": "US",
        "phone_number": "+1123456789"
      }
  }
  '
  ```
</RequestExample>

<ResponseExample>
  ```json Response

  "order": {
      "id": "96edc6ef-3b2c-412b-b9e5-96f361f93aec",
      "team_id": "b080b20c-e162-4cf1-9c7d-8faee72ee08e",
      "user_id": "9f1e094e-1641-466b-b668-d4d3300e569f",
      "shipping_details": {
        "receiver_name": "John Doe",
        "first_line": "123 Main St.",
        "second_line": "Apt. 208",
        "city": "San Francisco",
        "state": "CA",
        "zip": "91189",
        "country": "United States",
        "phone_number": "+11234567890"
      },
      "details": {
        "type": "testkit",
        "data": {
          "id": "a655f0e4-6405-4a1d-80b7-66f06c2108a7",
          "created_at": "2020-01-01T00:00:00Z",
          "updated_at": "2020-01-01T00:00:00Z"
        }
      },
      "lab_test": {
        "name": "Lipids Panel",
        "description": "Cholesterol test",
        "method": "testkit"
      },
      "sample_id": "123456789",
      "health_insurace_id": "7695cc28-f9e5-400d-95d2-ec7d9ec580df",
      "notes": "This is a note",
      "created_at": "2020-01-01T00:00:00Z",
      "updated_at": "2020-01-01T00:00:00Z",
      "status": "received",
      "events": [
        {
          "id": 1,
          "created_at": "2022-01-01T00:00:00Z",
          "status": "received.testkit.ordered"
        },
        {
          "id": 2,
          "created_at": "2022-01-02T00:00:00Z",
          "status": "received.testkit.awaiting_registration"
        },
      ]
    },
    "status": "string",
    "message": "string"
  }
  ```
</ResponseExample>


# Get Order
Source: https://docs.junction.com/api-reference/lab-testing/get-order

GET /v3/order/{order_id}
GET individual order by ID.

<RequestExample>
  ```python Python
  from vital import Client

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

  data = client.LabTests.get_order(order_id='<order_id>');
  ```

  ```javascript Node
  import { VitalClient, VitalEnvironment } from '@tryvital/vital-node';

  const client = new VitalClient({
      apiKey: '<my_api_key>',
      environment: VitalEnvironment.Sandbox,
  });

  const data = await client.labTests.getOrder("<order_id>");
  ```

  ```java Java
  import com.vital.api.Vital;
  import com.vital.api.core.Environment;

  Vital vital = Vital.builder()
          .apiKey("YOUR_API_KEY")
          .environment(Environment.SANDBOX)
          .build();

  var data = vital.labTests().getOrder("<order_id>");
  ```

  ```go Go
  import (
    "context"

    vital "github.com/tryVital/vital-go"
    vitalclient "github.com/tryVital/vital-go/client"
    "github.com/tryVital/vital-go/option"
  )

  client := vitalclient.NewClient(
    option.WithApiKey("<YOUR_API_KEY>"),
    option.WithBaseURL(vital.Environments.Sandbox),
  )

  response, err := client.LabTests.GetOrders(context.TODO(), "<order_id>")
  if err != nil {
    return err
  }
  fmt.Printf("Received data %s\n", response)
  ```
</RequestExample>

<ResponseExample>
  ```json Response
  {
    "id": "0ee312e2-6773-4a21-a6e1-506882cd98ed",
    "team_id": "cbb64555-af07-46c1-be09-ef89308e9b60",
    "user_id": "94e2d9f2-d600-4a23-9f08-536df378e2c7",
    "patient_details": {
      "dob": "2020-01-01",
      "gender": "male"
    },
    "priority": false,
    "patient_address": {
      "receiver_name": "John Doe",
      "first_line": "123 Main St.",
      "second_line": "Apt. 208",
      "city": "San Francisco",
      "state": "CA",
      "zip": "91189",
      "country": "United States",
      "phone_number": "+1123456789"
    },
    "details": {
      "type": "testkit",
      "data": {
        "id": "a655f0e4-6405-4a1d-80b7-66f06c2108a7",
        "shipment": {
          "id": "d55210cc-3d9f-4115-8262-5013f700c7be",
          "outbound_tracking_number": "<outbound_tracking_number>",
          "outbound_tracking_url": "<outbound_tracking_url>",
          "inbound_tracking_number": "<inbound_tracking_number>",
          "inbound_tracking_url": "<inbound_tracking_url>",
          "outbound_courier": "usps",
          "inbound_courier": "usps",
          "notes": "<notes>",
          "created_at": "2020-01-01T00:00:00.000Z",
          "updated_at": "2020-01-01T00:00:00.000Z"
        },
        "created_at": "2020-01-01T00:00:00Z",
        "updated_at": "2020-01-01T00:00:00Z"
      }
    },
    "lab_test": {
      "name": "Lipids Panel",
      "description": "Cholesterol test",
      "method": "testkit"
    },
    "sample_id": "123456789",
    "notes": "This is a note",
    "created_at": "2020-01-01T00:00:00Z",
    "updated_at": "2020-01-01T00:00:00Z",
    "status": "collecting_sample",
    "events": [
      {
        "id": 1,
        "created_at": "2022-01-01T00:00:00Z",
        "status": "received.testkit.ordered"
      },
      {
        "id": 2,
        "created_at": "2022-01-02T00:00:00Z",
        "status": "received.testkit.requisition_created"
      },
      {
        "id": 3,
        "created_at": "2022-01-03T00:00:00Z",
        "status": "collecting_sample.testkit.transit_customer"
      }
    ]
  }
  ```
</ResponseExample>


# Get Orders
Source: https://docs.junction.com/api-reference/lab-testing/get-orders

GET /v3/orders
GET many orders with filters.

<RequestExample>
  ```bash cURL
  curl --request GET \
       --url '{{BASE_URL}}/v3/orders' \
       --header 'accept: application/json' \
       --header 'x-vital-api-key: {YOUR_KEY}'
  '
  ```

  ```python Python
  from vital.client import Vital
  from vital.environment import VitalEnvironment
  from vital.types.shipping_address import ShippingAddress


  client = Vital(
    api_key="YOUR_API_KEY",
    environment=VitalEnvironment.SANDBOX
  )

  shipping_details = ShippingAddress(
      receiver_name="John Doe",
      first_line="123 Main St",
      second_line="",
      city="San Francisco",
      state="CA",
      zip="94103",
      country="US",
      phone_number="4155551234"
  )


  data = client.testkit.create_order(user_id="<user_id>", lab_test_id="<lab_test_id>", shipping_details=shipping_details)
  ```

  ```javascript Node
  import { VitalClient, VitalEnvironment } from '@tryvital/vital-node';
  import { CreateRegistrableTestkitOrderRequest} from '@tryvital/vital-node/api/resources/testkit';

  const client = new VitalClient({
      apiKey: '<my_api_key>',
      environment: VitalEnvironment.Sandbox,
  });

  const request: CreateRegistrableTestkitOrderRequest = {
      userId: "<user_id>",
      labTestId: "<lab_test_id>",
      shippingDetails: {
          receiverName: "<receiver_name>",
          firstLine: "<address_1>",
          city: "<city>",
          state: "<state>",
          zip: "<zip>",
          country: "<country>",
          phoneNumber: "<phone_number>",
      },
  };

  const data = await client.testkit.createOrder(request);
  ```

  ```java Java
  import com.vital.api.Vital;
  import com.vital.api.core.Environment;
  import com.vital.api.resources.testkit.requests.CreateRegistrableTestkitOrderRequest;
  import com.vital.api.types.ShippingAddress;

  Vital vital = Vital.builder()
          .apiKey("YOUR_API_KEY")
          .environment(Environment.SANDBOX)
          .build();

  ShippingAddress address = ShippingAddress
          .builder()
          .receiverName("John Doe")
          .firstLine("<first_line>")
          .city("<city>")
          .state("<state>")
          .zip("<zip>")
          .country("<country>")
          .phoneNumber("<phone_number>")
          .build();

  CreateRegistrableTestkitOrderRequest request = CreateRegistrableTestkitOrderRequest
          .builder()
          .userId("<user_id>")
          .labTestId("<lab_test_id")
          .shippingDetails(address)
          .build();

  var data = vital.testkit().createOrder(request);
  ```

  ```go Go
  import (
    "context"

    vital "github.com/tryVital/vital-go"
    vitalclient "github.com/tryVital/vital-go/client"
    "github.com/tryVital/vital-go/option"
  )

  request := &vital.CreateRegistrableTestkitOrderRequest{
    UserId:    "<user_id>",
    LabTestId: "<lab_test_id>",
    ShippingDetails: &vital.ShippingAddress{
      ReceiverName: "<receiver_name>",
      FirstLine:    "<first_line>",
      City:         "<city>",
      State:        "<state>",
      Zip:          "<zip>",
      Country:      "<country>",
    },
  }

  response, err := client.Testkit.CreateOrder(context.TODO(), request)
  if err != nil {
    return err
  }
  fmt.Printf("Received data %s\n", response)
  ```
</RequestExample>

<ResponseExample>
  ```json Response
  {
    "orders": [
      {
        "id": "0ee312e2-6773-4a21-a6e1-506882cd98ed",
        "team_id": "cbb64555-af07-46c1-be09-ef89308e9b60",
        "user_id": "94e2d9f2-d600-4a23-9f08-536df378e2c7",
        "patient_details": {
          "dob": "2020-01-01",
          "gender": "male"
        },
        "priority": false,
        "patient_address": {
          "receiver_name": "John Doe",
          "first_line": "123 Main St.",
          "second_line": "Apt. 208",
          "city": "San Francisco",
          "state": "CA",
          "zip": "91189",
          "country": "United States",
          "phone_number": "+1123456789"
        },
        "details": {
          "type": "testkit",
          "data": {
            "id": "a655f0e4-6405-4a1d-80b7-66f06c2108a7",
            "shipment": {
              "id": "d55210cc-3d9f-4115-8262-5013f700c7be",
              "outbound_tracking_number": "<outbound_tracking_number>",
              "outbound_tracking_url": "<outbound_tracking_url>",
              "inbound_tracking_number": "<inbound_tracking_number>",
              "inbound_tracking_url": "<inbound_tracking_url>",
              "outbound_courier": "usps",
              "inbound_courier": "usps",
              "notes": "<notes>",
              "created_at": "2020-01-01T00:00:00.000Z",
              "updated_at": "2020-01-01T00:00:00.000Z"
            },
            "created_at": "2020-01-01T00:00:00Z",
            "updated_at": "2020-01-01T00:00:00Z"
          }
        },
        "lab_test": {
          "name": "Lipids Panel",
          "description": "Cholesterol test",
          "method": "testkit"
        },
        "sample_id": "123456789",
        "notes": "This is a note",
        "created_at": "2020-01-01T00:00:00Z",
        "updated_at": "2020-01-01T00:00:00Z",
        "status": "collecting_sample",
        "events": [
          {
            "id": 1,
            "created_at": "2022-01-01T00:00:00Z",
            "status": "received.testkit.ordered"
          },
          {
            "id": 2,
            "created_at": "2022-01-02T00:00:00Z",
            "status": "received.testkit.requisition_created"
          },
          {
            "id": 3,
            "created_at": "2022-01-03T00:00:00Z",
            "status": "collecting_sample.testkit.transit_customer"
          }
        ]
      }
    ],
    "total": 1,
    "page": 1,
    "size": 50
  }
  ```
</ResponseExample>


# Import Order
Source: https://docs.junction.com/api-reference/lab-testing/import-order

POST /v3/order/import

<Card horizontal icon="person-digging" color="#57164A">
  This feature is in **closed beta**.

  Interested in this feature? Get in touch with your Customer Success Manager.
</Card>

<RequestExample>
  ```python Python
  from vital.client import Vital
  from vital.environment import VitalEnvironment
  from vital.types.billing import Billing
  from vital.types.gender import Gender
  from vital.types.lab_test_collection_method import LabTestCollectionMethod
  from vital.types.order_set_request import OrderSetRequest
  from vital.types.patient_address_compatible import PatientAddressCompatible
  from vital.types.patient_details import PatientDetails
  from vital.types.physician_create_request import PhysicianCreateRequest
  from datetime import datetime

  client = Vital(
    api_key="YOUR_API_KEY",
    environment=VitalEnvironment.SANDBOX
  )

  data = client.lab_tests.import_order(
      user_id="63661a2b-2bb3-4125-bb1a-b590f64f057f",
      billing_type=Billing.CLIENT_BILL,
      order_set=OrderSetRequest(lab_test_ids=[]),
      collection_method=LabTestCollectionMethod.WALK_IN_TEST,
      physician=PhysicianCreateRequest(first_name="Jane", last_name="Doe", npi=""),
      patient_details=PatientDetails(
          first_name="John",
          last_name="Doe",
          dob=datetime.fromisoformat("2020-01-01"),
          gender=Gender.MALE,
          phone_number="+1123456789",
          email="email@email.com"
      ),
      patient_address=PatientAddressCompatible(
        receiver_name="John Doe",
        first_line="123 Main St.",
        second_line="Apt. 208",
        city="San Francisco",
        state="CA",
        zip="91189",
        country="US",
        phone_number="+1123456789"
      ),
      sample_id="1234567890",
  )
  ```

  ```javascript Node
  import { VitalClient, VitalEnvironment } from '@tryvital/vital-node';
  import { ImportOrderBody } from '@tryvital/vital-node/api/resources/labTests';
  import { Billing, Gender, LabTestCollectionMethod } from '@tryvital/vital-node/api';

  const client = new VitalClient({
      apiKey: '<my_api_key>',
      environment: VitalEnvironment.Sandbox,
  });

  const request: ImportOrderBody = {
      userId: "63661a2b-2bb3-4125-bb1a-b590f64f057f",
      billingType: Billing.ClientBill,
      orderSet: {
        lab_test_ids=[],
      },
      collectionMethod: LabTestCollectionMethod.WalkInTest,
      physician: {
        firstName: "Jane",
        lastName: "Doe",
        npi: "",
      },
      patientDetails: {
          firstName: "John",
          lastName: "Doe",
          dob: new Date("2020-01-01"),
          gender: Gender.Male,
          phoneNumber: "+1123456789",
          email: "email@email.com"
      },
      patientAddress: {
        receiverName: "John Doe",
        first_line: "123 Main St.",
        second_line: "Apt. 208",
        city: "San Francisco",
        state: "CA",
        zip: "91189",
        country: "US",
        phoneNumber: "+1123456789"
      },
      sampleId: "1234567890",
  }

  const data = await client.labTests.importOrder(request)
  ```

  ```java Java
  import com.vital.api.Vital;
  import com.vital.api.core.Environment;
  import com.vital.api.types.PatientAddressCompatible;
  import com.vital.api.types.PatientDetails;
  import com.vital.api.types.LabTestCollectionMethod;
  import com.vital.api.types.ImportOrderBody;
  import com.vital.api.types.PhysicianCreateRequest;
  import com.vital.api.types.OrderSetRequest;

  Vital vital = Vital.builder()
        .apiKey("YOUR_API_KEY")
        .environment(Environment.SANDBOX)
        .build();

  PatientDetails details = PatientDetails.builder()
        .firstName("John")
        .lastName("Doe")
        .dob(OffsetDateTime.parse("2020-01-01"))
        .gender(Gender.MALE)
        .phoneNumber("+1123456789")
        .email("email@email.com")
        .build();

  PatientAddressCompatible address = PatientAddressCompatible
        .builder()
        .firstLine("123 Main St.")
        .city("San Francisco")
        .state("CA")
        .zip("91189")
        .country("US")
        .phoneNumber("+1123456789")
        .build();

  OrderSetRequest orderSet = OrderSetRequest
        .builder()
        .labTestIds([])
        .build();

  PhysicianCreateRequest physician = PhysicianCreateRequest
        .builder()
        .firstName("Jane")
        .lastName("Doe")
        .npi("")
        .build();

  ImportOrderBody request = ImportOrderBody
        .builder()
        .userId("63661a2b-2bb3-4125-bb1a-b590f64f057f")
        .billingType(Billing.CLIENT_BILL)
        .orderSet(orderSet)
        .collectionMethod(LabTestCollectionMethod.WALK_IN_TEST)
        .physician(physician)
        .patientDetails(details)
        .patientAddress(address)
        .sampleId("1234567890)
        .build();

  var data = vital.labTests().importOrder(request);
  ```

  ```go Go
  import (
    "context"

    vital "github.com/tryVital/vital-go"
    vitalclient "github.com/tryVital/vital-go/client"
    "github.com/tryVital/vital-go/option"
  )

  client := vitalclient.NewClient(
    option.WithApiKey("<YOUR_API_KEY>"),
    option.WithBaseURL(vital.Environments.Sandbox),
  )

  details := &vital.PatientDetails{
     FirstName:   "John",
     LastName:    "Doe",
     Dob:         time.Date(2020, 1, 1, 0, 0, 0, 0, time.UTC),
     Gender:      vital.GenderMale,
     PhoneNumber: "+1123456789",
     Email:       "email@email.com",
  }

  address := &vital.PatientAddressCompatible{
     ReceiverName: vital.String("john Doe"),
     FirstLine:    "123 Main St.",
     SecondLine:   vital.String("Apt. 208"),
     City:         "San Francisco",
     State:        "CA",
     Zip:          "91189",
     Country:      "US",
     PhoneNumber:  vital.String("+1123456789"),
  }

  order_set = &vital.OrderSetRequest{
        LabTestIds: []string{}
  }

  physician = &vital.PhysicianCreateRequest{
        FirstName: vital.String("Jane"),
        LastName:  vital.String("Doe),
        Npi:       "",
  }

  request := &vital.ImportOrderBody{
     UserId:           "63661a2b-2bb3-4125-bb1a-b590f64f057f",
     Billing:          vital.BillingClientBill,
     OrderSet:         orderSet,
     CollectionMethod: vital.LabTestCollectionMethodWalkInTest,
     Physician:        physician,
     PatientDetails:   details,
     PatientAddress:   address,
     SampleId:         vital.String("123456789),
  }

  response, err := client.LabTests.ImportOrder(context.TODO(), request)
  if err != nil {
     return err
  }
  fmt.Printf("Received data %s\n", response)
  ```
</RequestExample>

<ResponseExample>
  ```json Response
  {
      "order": {
          "user_id": "7ea94b27-a536-461f-ac4b-1c26c854d180",
          "id": "d3ec7ac7-2584-4254-9709-fc61d80635c4",
          "team_id": "59d4dfa1-e7c8-4d96-af15-74ca5ac5d189",
          "patient_details": {
              "first_name": "John",
              "last_name": "Doe",
              "dob": "1990-01-01T00:00:00+00:00",
              "gender": "male",
              "phone_number": "+11231234123",
              "email": "john@example.com"
          },
          "patient_address": {
              "receiver_name": "John Doe",
              "first_line": "123 Main Street",
              "second_line": null,
              "city": "New York",
              "state": "NY",
              "zip": "12345",
              "country": "US",
              "phone_number": "+11231234123"
          },
          "lab_test": {
              "id": "d0b479ec-afcc-4763-985c-4e23f17149f5",
              "slug": "59d4dfa1-testosterone",
              "name": "Testosterone",
              "sample_type": "serum",
              "method": "at_home_phlebotomy",
              "price": 0.0,
              "is_active": true,
              "status": "active",
              "fasting": false,
              "lab": null,
              "markers": null,
              "is_delegated": false,
              "auto_generated": false
          },
          "details": {
              "type": "at_home_phlebotomy",
              "data": {
                  "id": "21cb5e3f-25e3-443d-9fee-272de1393310",
                  "appointment_id": null,
                  "created_at": "2025-03-20T13:07:32+00:00",
                  "updated_at": "2025-03-20T13:07:32+00:00"
              }
          },
          "sample_id": "1234567890",
          "notes": null,
          "created_at": "2025-03-20T13:07:32+00:00",
          "updated_at": "2025-03-20T13:07:32+00:00",
          "events": [
              {
                  "id": 74769,
                  "created_at": "2025-03-20T13:07:32+00:00",
                  "status": "received.at_home_phlebotomy.ordered"
              },
              {
                  "id": 74770,
                  "created_at": "2025-03-20T13:07:32+00:00",
                  "status": "received.at_home_phlebotomy.requisition_bypassed"
              }
          ],
          "status": "received",
          "physician": {
              "first_name": "Jane",
              "last_name": "Doe",
              "npi": "123"
          },
          "health_insurance_id": null,
          "requisition_form_url": null,
          "priority": false,
          "shipping_details": null,
          "activate_by": null,
          "passthrough": null,
          "billing_type": "client_bill",
          "icd_codes": null
      },
      "status": "success",
      "message": "Order created successfully"
  }
  ```
</ResponseExample>


# Search Diagnosis
Source: https://docs.junction.com/api-reference/lab-testing/insurance/search-diagnosis

GET /v3/insurance/search/diagnosis

<RequestExample>
  ```bash cURL
  curl --request GET \
       --url '{{BASE_URL}}/v3/insurance/search/diagnosis?diagnosis_query=glucose' \
       --header 'accept: application/json' \
       --header 'x-vital-api-key: {YOUR_KEY}'
  ```

  ```python Python
  from vital.client import Vital
  from vital.environment import VitalEnvironment

  client = Vital(
    api_key="YOUR_API_KEY",
    environment=VitalEnvironment.SANDBOX
  )

  data = client.insurance.search_diagnosis(diagnosis_query="<query>")
  ```

  ```javascript Node
  import { VitalClient, VitalEnvironment } from '@tryvital/vital-node';
  import { InsuranceSearchDiagnosisRequest } from '@tryvital/vital-node/api';

  const client = new VitalClient({
      apiKey: '<my_api_key>',
      environment: VitalEnvironment.Sandbox,
  });

  const request: InsuranceSearchDiagnosisRequest = {
      diagnosisQuery: "<query>"
  }

  const data = await client.insurance.searchDiagnosis(request)
  ```

  ```java Java
  import com.vital.api.Vital;
  import com.vital.api.core.Environment;
  import com.vital.api.resources.insurance.requests.InsuranceSearchDiagnosisRequest;

  Vital vital = Vital.builder()
          .apiKey("YOUR_API_KEY")
          .environment(Environment.SANDBOX)
          .build();

  InsuranceSearchDiagnosisRequest request = InsuranceSearchDiagnosisRequest
          .builder()
          .diagnosisQuery("<query>")
          .build();

  var data = vital.insurance().searchDiagnosis(request);
  ```

  ```go Go
  import (
    "context"

    vital "github.com/tryVital/vital-go"
    vitalclient "github.com/tryVital/vital-go/client"
    "github.com/tryVital/vital-go/option"
  )

  client := vitalclient.NewClient(
    option.WithApiKey("<YOUR_API_KEY>"),
    option.WithBaseURL(vital.Environments.Sandbox),
  )

  request := &vital.InsuranceSearchDiagnosisRequest{
      DiagnosisQuery: "<query>",
  }

  response, err := client.Insurance.SearchDiagnosis(context.TODO(), request)
  if err != nil {
      return err
  }
  fmt.Printf("Received data %s\n", response)
  ```
</RequestExample>

<ResponseExample>
  ```json Response
  [
      {
          "diagnosis_code": "D55.0",
          "description": "ANEMIA DUE TO G6PD DEFICIENCY",
      },
      {
          "diagnosis_code": "D75.A",
          "description": "GLUC-6-PHOS DHYDRGNS DEF W/O ANEMIA",
      },
      {
          "diagnosis_code": "E74.810",
          "description": "GLUC TRANSPORT PROTEIN TYPE 1 DEFIC",
      },
      {
          "diagnosis_code": "E74.818",
          "description": "OTHER DISORDERS GLUCOSE TRANSPORT",
      }
  ]
  ```
</ResponseExample>


# Search Insurance Payor Information
Source: https://docs.junction.com/api-reference/lab-testing/insurance/search-payor-get

GET /v3/insurance/search/payor

<RequestExample>
  ```bash cURL
  curl --request GET \
       --url '{{BASE_URL}}/v3/insurance/search/payor?insurance_name=AETNA' \
       --header 'accept: application/json' \
       --header 'x-vital-api-key: {YOUR_KEY}' 
  '
  ```
</RequestExample>

<ResponseExample>
  ```json Response
  [
    {
      "code": "AARPA",
      "name": "AARP",
      "aliases": [
        "AARP",
        "AARP"
      ],
      "org_address": {
        "first_line": "PO BOX 740819",
        "second_line": null,
        "country": "US",
        "zip": "30374",
        "city": "ATLANTA",
        "state": "GA"
      }
    },
  ]
  ```
</ResponseExample>


# Get Collection Instructions PDF for Lab Test
Source: https://docs.junction.com/api-reference/lab-testing/lab-test-collection-instructions-pdf

GET /v3/lab_test/{lab_test_id}/collection_instruction_pdf
GET collection instructions for a lab test

<Card horizontal icon="person-digging" color="#57164A">
  This feature is in **closed beta**.

  Interested in this feature? Get in touch with your Customer Success Manager.
</Card>

<RequestExample>
  ```bash cURL
  curl --request GET \
       --url '{{BASE_URL}}/v3/lab_test/<lab_test_id>/collection_instruction_pdf' \
       --header 'accept: application/pdf' \
       --header 'x-vital-api-key: {YOUR_KEY}'
       --output file.pdf
  ```
</RequestExample>


# Get Markers for Lab Test
Source: https://docs.junction.com/api-reference/lab-testing/lab-test-markers

GET /v3/lab_tests/{lab_test_id}/markers

<RequestExample>
  ```bash cURL
  curl --request GET \
       --url '{{BASE_URL}}/v3/lab_tests/{lab_test_id}/markers' \
       --header 'accept: application/json' \
       --header 'x-vital-api-key: {YOUR_KEY}'
  ```

  ```python Python
  from vital.client import Vital
  from vital.environment import VitalEnvironment

  client = Vital(
    api_key="YOUR_API_KEY",
    environment=VitalEnvironment.SANDBOX
  )

  data = client.lab_tests.get_markers_for_lab_test("<lab_test_id>");
  ```

  ```javascript Node
  import { VitalClient, VitalEnvironment } from '@tryvital/vital-node';

  const client = new VitalClient({
      apiKey: '<my_api_key>',
      environment: VitalEnvironment.Sandbox,
  });

  const data = await client.labTests.getMarkersForLabTest("<lab_test_id>");
  ```

  ```java Java
  import com.vital.api.Vital;
  import com.vital.api.core.Environment;

  Vital vital = Vital.builder()
          .apiKey("YOUR_API_KEY")
          .environment(Environment.SANDBOX)
          .build();

  var data = vital.labTests().getMarkersForLabTest("<lab_test_id>");
  ```

  ```go Go
  import (
    "context"

    vital "github.com/tryVital/vital-go"
    vitalclient "github.com/tryVital/vital-go/client"
    "github.com/tryVital/vital-go/option"
  )

  client := vitalclient.NewClient(
    option.WithApiKey("<YOUR_API_KEY>"),
    option.WithBaseURL(vital.Environments.Sandbox),
  )

  response, err := client.LabTests.GetMarkersForLabTest(context.TODO(), "<lab_test_id>")
  if err != nil {
      return err
  }
  fmt.Printf("Received data %s\n", response)
  ```
</RequestExample>

<ResponseExample>
  ```json Response
  {
    "markers": [
        {
            "id": 202,
            "name": "Acetylcholine Receptor (AChR) Antibodies, Complete Profile with Reflex to MuSK Antibodies",
            "slug": "acetylcholine-receptor-achr-antibodies-complete-profile-with-reflex-to-musk-antibodies",
            "description": "Acetylcholine Receptor (AChR) Antibodies, Complete Profile with Reflex to MuSK Antibodies",
            "lab_id": 6,
            "provider_id": "165605",
            "type": "biomarker",
            "unit": null,
            "price": "N/A",
            "expected_results": [
                {
                    "id": 2938,
                    "name": "AChR Blocking Abs, Serum",
                    "slug": "achr-blocking-abs-serum",
                    "lab_id": 6,
                    "provider_id": "085927",
                    "loinc": {
                        "id": 3514,
                        "name": "Acetylcholine receptor blocking Ab Qn (S)",
                        "slug": "acetylcholine-receptor-blocking-ab-qn-s",
                        "code": "11561-8",
                        "unit": "%{inhibition}"
                    }
                },
                {
                    "id": 2939,
                    "name": "AChR Binding Abs, Serum",
                    "slug": "achr-binding-abs-serum",
                    "lab_id": 6,
                    "provider_id": "085904",
                    "loinc": {
                        "id": 3174,
                        "name": "Acetylcholine receptor binding Ab (S) [Moles/Vol]",
                        "slug": "acetylcholine-receptor-binding-ab-s-moles-vol",
                        "code": "11034-6",
                        "unit": "nmol/L"
                    }
                },
                {
                    "id": 2940,
                    "name": "AChR-modulating Ab",
                    "slug": "achr-modulating-ab",
                    "lab_id": 6,
                    "provider_id": "505199",
                    "loinc": {
                        "id": 61121,
                        "name": "Acetylcholine receptor modulation Ab FC Ql (S)",
                        "slug": "acetylcholine-receptor-modulation-ab-fc-ql-s",
                        "code": "99062-2",
                        "unit": null
                    }
                }
            ]
        },
    ],
    "total": 2,
    "page": 1,
    "size": 2
  }
  ```
</ResponseExample>


# Get Labels PDF
Source: https://docs.junction.com/api-reference/lab-testing/labels-pdf

GET /v3/order/{order_id}/labels/pdf
This endpoint returns the printed labels for the order.

<RequestExample>
  ```bash cURL
  curl --request GET \
       --url '{{BASE_URL}}/v3/order/<order_id>/labels/pdf' \
       --header 'accept: application/pdf' \
       --header 'x-vital-api-key: {YOUR_KEY}'
       --output file.pdf
  ```
</RequestExample>


# Get All Available Labs
Source: https://docs.junction.com/api-reference/lab-testing/labs

GET /v3/lab_tests/labs
GET all the labs.

<RequestExample>
  ```bash cURL
  curl --request GET \
       --url '{{BASE_URL}}/v3/lab_tests/labs' \
       --header 'accept: application/json' \
       --header 'x-vital-api-key: {YOUR_KEY}'
  ```

  ```python Python
  from vital.client import Vital
  from vital.environment import VitalEnvironment

  client = Vital(
    api_key="YOUR_API_KEY",
    environment=VitalEnvironment.SANDBOX
  )

  data = client.lab_tests.get_labs();
  ```

  ```javascript Node
  import { VitalClient, VitalEnvironment } from '@tryvital/vital-node';

  const client = new VitalClient({
      apiKey: '<my_api_key>',
      environment: VitalEnvironment.Sandbox,
  });

  const data = await client.labTests.getLabs();
  ```

  ```java Java
  import com.vital.api.Vital;
  import com.vital.api.core.Environment;

  Vital vital = Vital.builder()
          .apiKey("YOUR_API_KEY")
          .environment(Environment.SANDBOX)
          .build();

  var data = vital.labTests().getLabs();
  ```

  ```go Go
  import (
    "context"

    vital "github.com/tryVital/vital-go"
    vitalclient "github.com/tryVital/vital-go/client"
    "github.com/tryVital/vital-go/option"
  )

  client := vitalclient.NewClient(
    option.WithApiKey("<YOUR_API_KEY>"),
    option.WithBaseURL(vital.Environments.Sandbox),
  )

  response, err := client.LabTests.GetLabs(context.TODO())
  if err != nil {
      return err
  }
  fmt.Printf("Received data %s\n", response)
  ```
</RequestExample>

<ResponseExample>
  ```json Response
  [
    {
      "id": 1,
      "slug": "labcorp",
      "name": "LabCorp",
      "first_line_address": "123 Main St",
      "city": "San Francisco",
      "zipcode": "91789",
      "collection_methods": ["at_home_phlebotomy", "walk_in_test"],
      "sample_types": ["saliva", "serum"]
    }
  ]
  ```
</ResponseExample>


# Get Collection Instructions PDF for Order
Source: https://docs.junction.com/api-reference/lab-testing/order-collection-instructions-pdf

GET /v3/order/{order_id}/collection_instruction_pdf
GET collection instructions for an order

<Card horizontal icon="person-digging" color="#57164A">
  This feature is in **closed beta**.

  Interested in this feature? Get in touch with your Customer Success Manager.
</Card>

<RequestExample>
  ```bash cURL
  curl --request GET \
       --url '{{BASE_URL}}/v3/order/<order_id>/collection_instruction_pdf' \
       --header 'accept: application/pdf' \
       --header 'x-vital-api-key: {YOUR_KEY}'
       --output file.pdf
  ```
</RequestExample>


# Get Order Psc Info
Source: https://docs.junction.com/api-reference/lab-testing/order-psc-info

GET /v3/order/{order_id}/psc/info

<RequestExample>
  ```bash cURL
  curl --request GET \
       --url '{{BASE_URL}}/v3/order/{{ORDER_ID}}/psc/info' \
       --header 'accept: application/json' \
       --header 'x-vital-api-key: {YOUR_KEY}'
  ```

  ```python Python
  from vital.client import Vital
  from vital.environment import VitalEnvironment

  client = Vital(
    api_key="YOUR_API_KEY",
    environment=VitalEnvironment.SANDBOX
  )

  data = client.lab_tests.get_order_psc_info("order_id")
  ```

  ```javascript Node
  import { VitalClient, VitalEnvironment } from '@tryvital/vital-node';

  const client = new VitalClient({
      apiKey: '<my_api_key>',
      environment: VitalEnvironment.Sandbox,
  });

  const data = await client.labTests.getOrderPscInfo("order_id");
  ```

  ```java Java
  import com.vital.api.Vital;
  import com.vital.api.core.Environment;

  Vital vital = Vital.builder()
          .apiKey("YOUR_API_KEY")
          .environment(Environment.SANDBOX)
          .build();

  var data = vital.labTests().getOrderPscInfo("order_id);
  ```

  ```go Go
  import (
    "context"

    vital "github.com/tryVital/vital-go"
    vitalclient "github.com/tryVital/vital-go/client"
    "github.com/tryVital/vital-go/option"
  )

  client := vitalclient.NewClient(
    option.WithApiKey("<YOUR_API_KEY>"),
    option.WithBaseURL(vital.Environments.Sandbox),
  )


  response, err := client.LabTests.GetOrderPscInfo(context.TODO(), "order_id)
  if err != nil {
    return err
  }
  fmt.Printf("Received data %s\n", response)
  ```
</RequestExample>

<ResponseExample>
  ```json Response
  {
    "lab_id": 27,
    "slug": "labcorp",
    "patient_service_centers": [
      {
        "metadata": {
          "name": "LABCORP",
          "state": "AZ",
          "city": "Phoenix",
          "zip_code": "85006",
          "first_line": "1300 N 12th St",
          "second_line": "Ste 300",
          "phone_number": "480-878-3988",
          "fax_number": "844-346-5903",
          "hours": null
        },
        "distance": "25",
        "capabilities": ["stat"]
      },
    ]
  }
  ```
</ResponseExample>


# Get Markers for Order Set
Source: https://docs.junction.com/api-reference/lab-testing/order-set-marker

POST /v3/lab_tests/list_order_set_markers

<RequestExample>
  ```bash cURL
  curl --request POST \
       --url '{{BASE_URL}}/v3/lab_tests/list_order_set_markers' \
       --header 'accept: application/json' \
       --header 'x-vital-api-key: {YOUR_KEY}'
       --d '
       {
          "lab_test_ids": ["id"],
          "add_on": {
              "provider_ids": ["123"]
          }
       }
       '
  ```

  ```python Python
  from vital.client import Vital
  from vital.environment import VitalEnvironment

  client = Vital(
    api_key="YOUR_API_KEY",
    environment=VitalEnvironment.SANDBOX
  )

  data = client.lab_tests.get_markers_for_order_set(OrderSetRequest(
      lab_test_ids=["id"],
      add_on=AddOnOrder(
          provider_ids=["123]
      )
  ));
  ```
</RequestExample>

<ResponseExample>
  ```json Response
  {
    "markers": [
        {
            "id": 202,
            "name": "Acetylcholine Receptor (AChR) Antibodies, Complete Profile with Reflex to MuSK Antibodies",
            "slug": "acetylcholine-receptor-achr-antibodies-complete-profile-with-reflex-to-musk-antibodies",
            "description": "Acetylcholine Receptor (AChR) Antibodies, Complete Profile with Reflex to MuSK Antibodies",
            "lab_id": 6,
            "provider_id": "165605",
            "type": "biomarker",
            "unit": null,
            "price": "N/A",
            "expected_results": [
                {
                    "id": 2938,
                    "name": "AChR Blocking Abs, Serum",
                    "slug": "achr-blocking-abs-serum",
                    "lab_id": 6,
                    "provider_id": "085927",
                    "loinc": {
                        "id": 3514,
                        "name": "Acetylcholine receptor blocking Ab Qn (S)",
                        "slug": "acetylcholine-receptor-blocking-ab-qn-s",
                        "code": "11561-8",
                        "unit": "%{inhibition}"
                    }
                },
                {
                    "id": 2939,
                    "name": "AChR Binding Abs, Serum",
                    "slug": "achr-binding-abs-serum",
                    "lab_id": 6,
                    "provider_id": "085904",
                    "loinc": {
                        "id": 3174,
                        "name": "Acetylcholine receptor binding Ab (S) [Moles/Vol]",
                        "slug": "acetylcholine-receptor-binding-ab-s-moles-vol",
                        "code": "11034-6",
                        "unit": "nmol/L"
                    }
                },
                {
                    "id": 2940,
                    "name": "AChR-modulating Ab",
                    "slug": "achr-modulating-ab",
                    "lab_id": 6,
                    "provider_id": "505199",
                    "loinc": {
                        "id": 61121,
                        "name": "Acetylcholine receptor modulation Ab FC Ql (S)",
                        "slug": "acetylcholine-receptor-modulation-ab-fc-ql-s",
                        "code": "99062-2",
                        "unit": null
                    }
                }
            ]
        },
    ],
    "total": 2,
    "page": 1,
    "size": 2
  }
  ```
</ResponseExample>


# Update a Test
Source: https://docs.junction.com/api-reference/lab-testing/patch-lab-test

PATCH /v3/lab_tests/{lab_test_id}

<RequestExample>
  ```python Python
  from vital.client import Vital
  from vital.environment import VitalEnvironment


  client = Vital(
    api_key="YOUR_API_KEY",
    environment=VitalEnvironment.SANDBOX
  )

  data = client.lab_tests.update_lab_test(
      lab_test_id="<lab_test_id>",
      name="<name>",
      active=<True>,
  )
  ```

  ```javascript Node
  import { VitalClient, VitalEnvironment } from '@tryvital/vital-node';
  import {  UpdateLabTestRequest } from '@tryvital/vital-node/api';

  const client = new VitalClient({
      apiKey: '<my_api_key>',
      environment: VitalEnvironment.Sandbox,
  });

  const request: UpdateLabTestRequest = {
      name: '<name>',
      active: <true>,
  }

  const data = await client.labTests.updateLabTest(labTestId, request);
  ```

  ```java Java
  import com.vital.api.Vital;
  import com.vital.api.core.Environment;
  import com.vital.api.resources.labtests.requests.UpdateLabTestRequest;

  Vital vital = Vital.builder()
          .apiKey("YOUR_API_KEY")
          .environment(Environment.SANDBOX)
          .build();

  UpdateLabTestRequest request = UpdateLabTestRequest
          .builder()
          .name("<name>")
          .active(<true>)
          .build();

  var data = vital.labTests().updateLabTest(labTestId, request);
  ```

  ```go Go
  import (
    "context"

    vital "github.com/tryVital/vital-go"
    vitalclient "github.com/tryVital/vital-go/client"
    "github.com/tryVital/vital-go/option"
  )

  client := vitalclient.NewClient(
    option.WithApiKey("<YOUR_API_KEY>"),
    option.WithBaseURL(vital.Environments.Sandbox),
  )

  request := &vital.UpdateLabTestRequest{
    Name:        "<name>",
    Active:     <true>,
  }

  response, err := client.LabTests.UpdateLabTest(context.TODO(), labTestId, request)
  if err != nil {
    return err
  }
  fmt.Printf("Received data %s\n", response)
  ```
</RequestExample>

<ResponseExample>
  ```json Response
  {
    "id": "5af405fc-fafb-49e8-b0bf-fe9d91df6a7d",
    "slug": "a94e3005-new-test",
    "name": "New test",
    "sample_type": "serum",
    "method": "at_home_phlebotomy",
    "price": 0.0,
    "is_active": true,
    "status": "active",
    "fasting": false,
    "lab": {
      "id": 26,
      "slug": "quest",
      "name": "Quest",
      "first_line_address": "100 Tri State International #100",
      "city": "Lincolnshire",
      "zipcode": "60069",
      "collection_methods": ["at_home_phlebotomy", "walk_in_test"],
      "sample_types": ["serum", "saliva", "urine"]
    },
    "markers": [
      {
        "id": 6859,
        "name": "17-Hydroxyprogesterone",
        "slug": "17-hydroxyprogesterone",
        "description": "17-Hydroxyprogesterone",
        "lab_id": 26,
        "provider_id": "17180",
        "type": "biomarker",
        "unit": null,
        "price": "N/A",
        "aoe": null,
        "a_la_carte_enabled": true
      },
      {
        "id": 8213,
        "name": "17-Hydroxypregnenolone",
        "slug": "17-hydroxypregnenolone",
        "description": "17-Hydroxypregnenolone",
        "lab_id": 26,
        "provider_id": "8352",
        "type": "biomarker",
        "unit": null,
        "price": "N/A",
        "aoe": null,
        "a_la_carte_enabled": true
      }
    ],
    "is_delegated": false,
    "auto_generated": false
  }
  ```
</ResponseExample>


# Create a Test
Source: https://docs.junction.com/api-reference/lab-testing/post-test

POST /v3/lab_tests

<RequestExample>
  ```python Python
  from vital.client import Vital
  from vital.environment import VitalEnvironment
  from vital.types.lab_test_collection_method import LabTestCollectionMethod
  from vital.types.lab_test_sample_type import LabTestSampleType
  from vital.types.us_address import UsAddress


  client = Vital(
    api_key="YOUR_API_KEY",
    environment=VitalEnvironment.SANDBOX
  )

  data = client.lab_tests.create(
      provider_ids=["000110"],
      name="<name>",
      method=LabTestCollectionMethod.TESTKIT,
      description="<description>"
  )
  ```

  ```javascript Node
  import { VitalClient, VitalEnvironment } from '@tryvital/vital-node';
  import {
    CreateLabTestRequest,
    LabTestCollectionMethod,
    LabTestSampleType,
  } from '@tryvital/vital-node/api';

  const client = new VitalClient({
    apiKey: '<my_api_key>',
    environment: VitalEnvironment.Sandbox,
  });

  const request: CreateLabTestRequest = {
    providerIds: ['000110'],
    name: '<name>',
    method: LabTestCollectionMethod.Testkit,
    description: '<description>',
  };

  const data = await client.labTests.create(request);
  ```

  ```java Java
  import com.vital.api.Vital;
  import com.vital.api.core.Environment;
  import com.vital.api.resources.labtests.requests.CreateLabTestRequest;
  import com.vital.api.types.LabTestCollectionMethod;
  import com.vital.api.types.LabTestSampleType;

  Vital vital = Vital.builder()
          .apiKey("YOUR_API_KEY")
          .environment(Environment.SANDBOX)
          .build();

  CreateLabTestRequest request = CreateLabTestRequest
          .builder()
          .name("<name>")
          .method(LabTestCollectionMethod.TESTKIT)
          .description("<description")
          .providerIds(List.of("001100"))
          .build();

  var data = vital.labTests().create(request);
  ```

  ```go Go
  import (
    "context"

    vital "github.com/tryVital/vital-go"
    vitalclient "github.com/tryVital/vital-go/client"
    "github.com/tryVital/vital-go/option"
  )

  client := vitalclient.NewClient(
    option.WithApiKey("<YOUR_API_KEY>"),
    option.WithBaseURL(vital.Environments.Sandbox),
  )

  request := &vital.CreateLabTestRequest{
    ProviderIds:   []int{"001100"},
    Name:        "<name>",
    Method:      vital.LabTestCollectionMethodTestkit,
    Description: "<description>",
  }

  response, err := client.LabTests.Create(context.TODO(), request)
  if err != nil {
    return err
  }
  fmt.Printf("Received data %s\n", response)
  ```
</RequestExample>

<ResponseExample>
  ```json Response
  {
    "id": "2e82a1d4-e2e6-421c-9c54-2210d667ce48",
    "slug": "a94e3005-labcorp-panel",
    "name": "Labcorp panel",
    "sample_type": "serum",
    "method": "at_home_phlebotomy",
    "price": 0.0,
    "is_active": true,
    "status": "active",
    "fasting": false,
    "lab": {
      "id": 27,
      "slug": "labcorp",
      "name": "Labcorp",
      "first_line_address": "labcorp address",
      "city": "Lincolnshire",
      "zipcode": "60069",
      "collection_methods": ["at_home_phlebotomy", "walk_in_test"],
      "sample_types": ["serum", "saliva", "urine"]
    },
    "markers": [
      {
        "id": 195,
        "name": "Abnormal Bleeding Profile",
        "slug": "abnormal-bleeding-profile",
        "description": "Abnormal Bleeding Profile",
        "lab_id": 27,
        "provider_id": "116004",
        "type": "biomarker",
        "unit": null,
        "price": "N/A",
        "aoe": null,
        "a_la_carte_enabled": true
      }
    ],
    "is_delegated": false,
    "auto_generated": false
  }
  ```
</ResponseExample>


# Get Psc Info
Source: https://docs.junction.com/api-reference/lab-testing/psc-info

GET /v3/order/psc/info

<RequestExample>
  ```bash cURL
  curl --request GET \
       --url '{{BASE_URL}}/v3/order/psc/info?zip_code=85004&lab_id=27' \
       --header 'accept: application/json' \
       --header 'x-vital-api-key: {YOUR_KEY}'
  ```

  ```python Python
  from vital.client import Vital
  from vital.environment import VitalEnvironment

  client = Vital(
    api_key="YOUR_API_KEY",
    environment=VitalEnvironment.SANDBOX
  )

  data = client.lab_tests.get_psc_info(zip_code="85004", lab_id=27)
  ```

  ```javascript Node
  import { VitalClient, VitalEnvironment } from '@tryvital/vital-node';
  import { LabTestsGetPscInfoRequest } from '@tryvital/vital-node/api/resources/labTests';

  const client = new VitalClient({
      apiKey: '<my_api_key>',
      environment: VitalEnvironment.Sandbox,
  });

  const request: LabTestsGetPscInfoRequest = {
      zipCode: "85004",
      labId: 27,
  }

  const data = await client.labTests.getPscInfo(request);
  ```

  ```java Java
  import com.vital.api.Vital;
  import com.vital.api.core.Environment;
  import com.vital.api.resources.labtests.requests.LabTestsGetPscInfoRequest;

  Vital vital = Vital.builder()
          .apiKey("YOUR_API_KEY")
          .environment(Environment.SANDBOX)
          .build();

  LabTestsGetPscInfoRequest request = LabTestsGetPscInfoRequest.builder()
          .zipCode("85004")
          .labId(27)
          .build();

  var data = vital.labTests().getPscInfo(request);
  ```

  ```go Go
  import (
    "context"

    vital "github.com/tryVital/vital-go"
    vitalclient "github.com/tryVital/vital-go/client"
    "github.com/tryVital/vital-go/option"
  )

  client := vitalclient.NewClient(
    option.WithApiKey("<YOUR_API_KEY>"),
    option.WithBaseURL(vital.Environments.Sandbox),
  )

  request := &vital.LabTestsGetPscInfoRequest{
    ZipCode: "85004",
    LabId: 27,
  }

  response, err := client.LabTests.GetPscInfo(context.TODO(), request)
  if err != nil {
    return err
  }
  fmt.Printf("Received data %s\n", response)
  ```
</RequestExample>

<ResponseExample>
  ```json Response
  {
    "lab_id": 27,
    "slug": "labcorp",
    "patient_service_centers": [
      {
        "metadata": {
          "name": "LABCORP",
          "state": "AZ",
          "city": "Phoenix",
          "zip_code": "85006",
          "first_line": "1300 N 12th St",
          "second_line": "Ste 300",
          "phone_number": "480-878-3988",
          "fax_number": "844-346-5903",
          "hours": null
        },
        "distance": "25",
        "capabilities": ["stat"]
      },
    ]
  }
  ```
</ResponseExample>


# PSC Appointment Availability
Source: https://docs.junction.com/api-reference/lab-testing/psc-schedulling/appointment-psc-availability

POST /v3/order/psc/appointment/availability

<RequestExample>
  ```bash cURL
  curl --request POST \
       --url '{{BASE_URL}}/v3/order/psc/appointment/availability' \
       --header 'accept: application/json' \
       --header 'x-vital-api-key: {YOUR_KEY}' \
       --data '
  {
      "lab": "quest",
      "zip_code": "85004",
      "radius": "25",
  }
  '
  ```
</RequestExample>

<ResponseExample>
  ```json Response
  {
      "slots": [
          {
              "location": {
                  "location": {
                      "lng": -112.0568538,
                      "lat": 33.4631386
                  },
                  "address": {
                      "first_line": "1300 N 12th St",
                      "second_line": "Ste 300",
                      "city": "Phoenix",
                      "state": "AZ",
                      "zip_code": "85006",
                  },
                  "code": "23070",
                  "name": "QUEST",
                  "iana_timezone": "America/Los_Angeles"
              },
              "date":"2023-05-09",
              "slots": [
                  {
                      "booking_key": "foo123",
                      "start": "2023-05-09T17:00:00+00:00",
                      "end": "2023-05-09T19:00:00+00:00",
                      "expires_at": "2023-05-09T12:39:57.827000+00:00",
                      "price": 0.0,
                      "is_priority": true,
                      "num_appointments_available": 1
                  },
                  ...
              ],
          },
          {
              "location": {
                  "location": {
                      "lng": -112.0568538,
                      "lat": 33.4631386
                  },
                  "address": {
                      "first_line": "1300 N 12th St",
                      "second_line": "Ste 300",
                      "city": "Phoenix",
                      "state": "AZ",
                      "zip_code": "85006",
                  },
                  "code": "23070",
                  "name": "QUEST"
              },
              "date":"2023-05-10",
              "slots": [
                  {
                      "booking_key": "bar456",
                      "start": "2023-05-10T12:00:00+00:00",
                      "end": "2023-05-10T14:00:00+00:00",
                      "expires_at": "2023-05-09T12:39:57.852000+00:00",
                      "price": 0.0,
                      "is_priority": true,
                      "num_appointments_available": 1
                  },
                  ...
              ],
          },
      ],
      "timezone": null
  }
  ```
</ResponseExample>


# Book PSC Appointment
Source: https://docs.junction.com/api-reference/lab-testing/psc-schedulling/appointment-psc-booking

POST /v3/order/{order_id}/psc/appointment/book

<RequestExample>
  ```bash cURL
  curl --request POST \
       --url '{{BASE_URL}}/v3/order/413d7205-f8a9-42ed-aa4a-edb99e481ca0/psc/appointment/book' \
       --header 'accept: application/json' \
       --header 'x-vital-api-key: {YOUR_KEY}' \
       --data '
  {
      "booking_key": "foo123"
  }
  '
  ```

  ```python Python
  from vital.client import Vital
  from vital.environment import VitalEnvironment

  client = Vital(
    api_key="YOUR_API_KEY",
    environment=VitalEnvironment.SANDBOX
  )

  data = client.lab_tests.book_psc_appointment(order_id="<order_id>", booking_key="<booking_key>")
  ```

  ```javascript Node
  import { VitalClient, VitalEnvironment } from '@tryvital/vital-node';
  import { AppointmentBookingRequest } from '@tryvital/vital-node/api';

  const client = new VitalClient({
      apiKey: '<my_api_key>',
      environment: VitalEnvironment.Sandbox,
  });

  const request: AppointmentBookingRequest = {
      bookingKey: "<booking_key>",
  }
  const data = await client.labTests.bookPscAppointment("<order_id>", request);
  ```

  ```java Java
  import com.vital.api.Vital;
  import com.vital.api.core.Environment;
  import com.vital.api.resources.labtests.requests.AppointmentBookingRequest;

  Vital vital = Vital.builder()
          .apiKey("YOUR_API_KEY")
          .environment(Environment.SANDBOX)
          .build();

  AppointmentBookingRequest request = AppointmentBookingRequest
          .builder()
          .bookingKey("<booking_key>")
          .build();

  var data = vital.labTests().bookPscAppointment("<order_id>", request);
  ```

  ```go Go
  import (
    "context"

    vital "github.com/tryVital/vital-go"
    vitalclient "github.com/tryVital/vital-go/client"
    "github.com/tryVital/vital-go/option"
  )

  client := vitalclient.NewClient(
    option.WithApiKey("<YOUR_API_KEY>"),
    option.WithBaseURL(vital.Environments.Sandbox),
  )

  request := &vital.AppointmentBookingRequest{
      BookingKey: "<booking_key>",
  }

  response, err := client.LabTests.BookPscAppointment(context.TODO(), "<order_id>", request)
  if err != nil {
      return err
  }
  fmt.Printf("Received data %s\n", response)
  ```
</RequestExample>

<ResponseExample>
  ```json Response
  {
      "id": "413d7205-f8a9-42ed-aa4a-edb99e481ca0",
      "user_id": "202b2c2f-fb4c-44dc-a4f8-621186fde227",
      "address": {
          "first_line": "West Lincoln Street",
          "second_line": "",
          "city": "Phoenix",
          "state": "AZ",
          "zip_code": "85004",
          "unit": "14"
      },
      "location": {
          "lng": -112.0772235,
          "lat": 33.4421912
      },
      "start_at": "2023-05-15T16:00:00+00:00",
      "end_at": "2023-05-15T18:00:00+00:00",
      "iana_timezone": "America/Phoenix",
      "type": "patient_service_center",
      "provider": "quest",
      "status": "pending",
      "provider_id": "e89eb489-7382-4966-bb14-7ab4763eba6c",
      "can_reschedule":true
  }
  ```
</ResponseExample>


# PSC Appointment Cancellation Reasons
Source: https://docs.junction.com/api-reference/lab-testing/psc-schedulling/appointment-psc-cancellation-reasons

GET /v3/order/psc/appointment/cancellation-reasons

<RequestExample>
  ```bash cURL
  curl --request GET \
       --url '{{BASE_URL}}/v3/order/psc/appointment/cancellation-reasons' \
       --header 'accept: application/json' \
       --header 'x-vital-api-key: {YOUR_KEY}'
  '
  ```

  ```python Python
  from vital.client import Vital
  from vital.environment import VitalEnvironment

  client = Vital(
    api_key="YOUR_API_KEY",
    environment=VitalEnvironment.SANDBOX
  )

  data = client.lab_tests.get_psc_appointment_cancellation_reason();
  ```

  ```javascript Node
  import { VitalClient, VitalEnvironment } from '@tryvital/vital-node';

  const client = new VitalClient({
      apiKey: '<my_api_key>',
      environment: VitalEnvironment.Sandbox,
  });

  const data = await client.labTests.getPscAppointmentCancellationReason();
  ```

  ```java Java
  import com.vital.api.Vital;
  import com.vital.api.core.Environment;

  Vital vital = Vital.builder()
          .apiKey("YOUR_API_KEY")
          .environment(Environment.SANDBOX)
          .build();

  var data = vital.labTests().getPscAppointmentCancellationReason();
  ```

  ```go Go
  import (
    "context"

    vital "github.com/tryVital/vital-go"
    vitalclient "github.com/tryVital/vital-go/client"
    "github.com/tryVital/vital-go/option"
  )

  client := vitalclient.NewClient(
    option.WithApiKey("<YOUR_API_KEY>"),
    option.WithBaseURL(vital.Environments.Sandbox),
  )

  response, err := client.LabTests.GetPscAppointmentCancellationReason(context.TODO())
  if err != nil {
      return err
  }
  fmt.Printf("Received data %s\n", response)
  ```
</RequestExample>

<ResponseExample>
  ```json
  [
     {
        "id": "5c0257ef-6fea-4a22-b20a-3ddab573d5c9",
        "name": "Other",
        "is_refundable": true
     },
  ]
  ```
</ResponseExample>


# Cancel PSC Appointment
Source: https://docs.junction.com/api-reference/lab-testing/psc-schedulling/appointment-psc-cancelling

PATCH /v3/order/{order_id}/psc/appointment/cancel

<RequestExample>
  ```bash cURL
  curl --request PATCH \
       --url '{{BASE_URL}}/v3/order/413d7205-f8a9-42ed-aa4a-edb99e481ca0/psc/appointment/cancel' \
       --header 'accept: application/json' \
       --header 'x-vital-api-key: {YOUR_KEY}' \
       --data '
  {
      "cancellation_reason_id": "7dfd7da5-ed6e-40bb-a7e4-c8003f0c10a9"
  }
  '
  ```

  ```python Python
  from vital.client import Vital
  from vital.environment import VitalEnvironment

  client = Vital(
    api_key="YOUR_API_KEY",
    environment=VitalEnvironment.SANDBOX
  )

  data = client.lab_tests.get_psc_appointment_cancellation_reason();
  ```

  ```javascript Node
  import { VitalClient, VitalEnvironment } from '@tryvital/vital-node';
  import {  AppointmentCancelRequest } from '@tryvital/vital-node/api';

  const client = new VitalClient({
      apiKey: '<my_api_key>',
      environment: VitalEnvironment.Sandbox,
  });

  const request: AppointmentCancelRequest = {
      cancellationReasonId: "<reason_id>",
  }

  const data = await client.labTests.cancelPscAppointment("<order_id>", request);
  ```

  ```java Java
  import com.vital.api.Vital;
  import com.vital.api.core.Environment;
  import com.vital.api.resources.labtests.requests.AppointmentCancelRequest;

  Vital vital = Vital.builder()
          .apiKey("YOUR_API_KEY")
          .environment(Environment.SANDBOX)
          .build();

  AppointmentCancelRequest request = AppointmentCancelRequest
          .builder()
          .cancellationReasonId("<reason_id")
          .build();

  var data = vital.labTests().cancelPscAppointment("<order_id>", request);
  ```

  ```go Go
  import (
    "context"

    vital "github.com/tryVital/vital-go"
    vitalclient "github.com/tryVital/vital-go/client"
    "github.com/tryVital/vital-go/option"
  )

  client := vitalclient.NewClient(
    option.WithApiKey("<YOUR_API_KEY>"),
    option.WithBaseURL(vital.Environments.Sandbox),
  )

  request := &vital.AppointmentCancelRequest{
      CancellationReasonId: "<cancellation_reason_id>",
  }

  response, err := client.LabTests.CancelPscAppointment(context.TODO(), "<order_id>", request)
  if err != nil {
      return err
  }
  fmt.Printf("Received data %s\n", response)
  ```
</RequestExample>

<ResponseExample>
  ```json Response
  {
      "id": "413d7205-f8a9-42ed-aa4a-edb99e481ca0",
      "user_id": "202b2c2f-fb4c-44dc-a4f8-621186fde227",
      "address": {
          "first_line": "West Lincoln Street",
          "second_line": "",
          "city": "Phoenix",
          "state": "AZ",
          "zip_code": "85004",
          "unit": "14"
      },
      "location": {
          "lng": -112.0772235,
          "lat": 33.4421912
      },
      "start_at": "2023-05-17T20:00:00+00:00",
      "end_at": "2023-05-17T22:00:00+00:00",
      "iana_timezone": "America/Phoenix",
      "type": "patient_service_center",
      "provider": "quest",
      "status": "cancelled",
      "provider_id": "e89eb489-7382-4966-bb14-7ab4763eba6c",
      "can_reschedule": true
  }
  ```
</ResponseExample>


# Reschedule PSC Appointment
Source: https://docs.junction.com/api-reference/lab-testing/psc-schedulling/appointment-psc-rescheduling

PATCH /v3/order/{order_id}/psc/appointment/reschedule

<RequestExample>
  ```bash cURL
  curl --request PATCH \
       --url '{{BASE_URL}}/v3/order/413d7205-f8a9-42ed-aa4a-edb99e481ca0/psc/appointment/reschedule' \
       --header 'accept: application/json' \
       --header 'x-vital-api-key: {YOUR_KEY}' \
       --data '
  {
      "booking_key": "bar456"
  }
  '
  ```

  ```python Python
  from vital.client import Vital
  from vital.environment import VitalEnvironment

  client = Vital(
    api_key="YOUR_API_KEY",
    environment=VitalEnvironment.SANDBOX
  )

  data = client.lab_tests.reschedule_psc_appointment(order_id="<order_id>", booking_key="<booking_key>");
  ```

  ```javascript Node
  import { VitalClient, VitalEnvironment } from '@tryvital/vital-node';
  import {  AppointmentRescheduleRequest } from '@tryvital/vital-node/api';

  const client = new VitalClient({
      apiKey: '<my_api_key>',
      environment: VitalEnvironment.Sandbox,
  });

  const request: AppointmentRescheduleRequest = {
      bookingKey: "<reason_id>",
  }

  const data = await client.labTests.reschedulePscAppointment("<order_id>", request);
  ```

  ```java Java
  import com.vital.api.Vital;
  import com.vital.api.core.Environment;
  import com.vital.api.resources.labtests.requests.AppointmentRescheduleRequest;

  Vital vital = Vital.builder()
          .apiKey("YOUR_API_KEY")
          .environment(Environment.SANDBOX)
          .build();

  AppointmentRescheduleRequest request = AppointmentRescheduleRequest
          .builder()
          .bookingKey("<booking_key>")
          .build();

  var data = vital.labTests().reschedulePscAppointment("<order_id>", request);
  ```

  ```go Go
  import (
    "context"

    vital "github.com/tryVital/vital-go"
    vitalclient "github.com/tryVital/vital-go/client"
    "github.com/tryVital/vital-go/option"
  )

  client := vitalclient.NewClient(
    option.WithApiKey("<YOUR_API_KEY>"),
    option.WithBaseURL(vital.Environments.Sandbox),
  )

  request := &vital.AppointmentRescheduleRequest{
      BookingKey: "<booking_key>",
  }

  response, err := client.LabTests.ReschedulePscAppointment(context.TODO(), "<order_id>", request)
  if err != nil {
      return err
  }
  fmt.Printf("Received data %s\n", response)
  ```
</RequestExample>

<ResponseExample>
  ```json Response
  {
      "id": "413d7205-f8a9-42ed-aa4a-edb99e481ca0",
      "user_id": "202b2c2f-fb4c-44dc-a4f8-621186fde227",
      "address": {
          "first_line": "West Lincoln Street",
          "second_line": "",
          "city": "Phoenix",
          "state": "AZ",
          "zip_code": "85004",
          "unit":"14"
      },
      "location": {
          "lng": -112.0772235,
          "lat": 33.4421912
      },
      "start_at": "2023-05-17T20:00:00+00:00",
      "end_at": "2023-05-17T22:00:00+00:00",
      "iana_timezone": "America/Phoenix",
      "type": "patient_service_center",
      "provider": "quest",
      "status": "confirmed",
      "provider_id": "e89eb489-7382-4966-bb14-7ab4763eba6c",
      "can_reschedule": true
  }
  ```
</ResponseExample>


# Get PSC Appointment
Source: https://docs.junction.com/api-reference/lab-testing/psc-schedulling/get-psc-appointment

GET /v3/order/{order_id}/psc/appointment
Get the appointment associated with an order.

<RequestExample>
  ```bash cURL
  curl --request GET \
       --url '{{BASE_URL}}/v3/order/413d7205-f8a9-42ed-aa4a-edb99e481ca0/psc/appointment' \
       --header 'accept: application/json' \
       --header 'x-vital-api-key: {YOUR_KEY}'
  ```

  ```python Python
  from vital.client import Vital
  from vital.environment import VitalEnvironment

  client = Vital(
    api_key="YOUR_API_KEY",
    environment=VitalEnvironment.SANDBOX
  )

  data = client.lab_tests.get_psc_appointment(order_id="<order_id>")
  ```

  ```javascript Node
  import { VitalClient, VitalEnvironment } from '@tryvital/vital-node';

  const client = new VitalClient({
      apiKey: '<my_api_key>',
      environment: VitalEnvironment.Sandbox,
  });

  const data = await client.labTests.getpscAppointment("<order_id>");
  ```

  ```java Java
  import com.vital.api.Vital;
  import com.vital.api.core.Environment;

  Vital vital = Vital.builder()
          .apiKey("YOUR_API_KEY")
          .environment(Environment.SANDBOX)
          .build();

  var data = vital.labTests().getpscAppointment("<order_id>");
  ```

  ```go Go
  import (
    "context"

    vital "github.com/tryVital/vital-go"
    vitalclient "github.com/tryVital/vital-go/client"
    "github.com/tryVital/vital-go/option"
  )

  client := vitalclient.NewClient(
    option.WithApiKey("<YOUR_API_KEY>"),
    option.WithBaseURL(vital.Environments.Sandbox),
  )

  response, err := client.LabTests.GetpscAppointment(context.TODO(), "<order_id>")
  if err != nil {
      return err
  }
  fmt.Printf("Received data %s\n", response)
  ```
</RequestExample>

<ResponseExample>
  ```json Response
  {
      "id": "413d7205-f8a9-42ed-aa4a-edb99e481ca0",
      "user_id": "202b2c2f-fb4c-44dc-a4f8-621186fde227",
      "address": {
          "first_line": "West Lincoln Street",
          "second_line": "",
          "city": "Phoenix",
          "state": "AZ",
          "zip_code": "85004",
          "unit": "14"
      },
      "location": {
          "lng": -112.0772235,
          "lat": 33.4421912
      },
      "start_at": "2023-05-17T20:00:00+00:00",
      "end_at": "2023-05-17T22:00:00+00:00",
      "iana_timezone": "America/Phoenix",
      "type": "patient_service_center",
      "provider": "quest",
      "status": "confirmed",
      "provider_id": "e89eb489-7382-4966-bb14-7ab4763eba6c",
      "can_reschedule": true
  }
  ```
</ResponseExample>


# Register Testkit Order
Source: https://docs.junction.com/api-reference/lab-testing/register-order

POST /v3/order/testkit/register

<RequestExample>
  ```python Python
  from datetime import datetime
  from vital.client import Vital
  from vital.environment import VitalEnvironment
  from vital.types.gender import Gender
  from vital.types.patient_address_compatible import PatientAddressCompatible
  from vital.types.patient_details import PatientDetails


  client = Vital(
    api_key="YOUR_API_KEY",
    environment=VitalEnvironment.SANDBOX
  )

  patient_details = PatientDetails(
      first_name="John",
      last_name="Doe",
      dob=datetime.fromisoformat("1990-01-01"),
      gender=Gender.MALE,
      email="email@email.com",
      phone_number="123-456-7890",
  )

  patient_address = PatientAddressCompatible(
      receiver_name="John Doe",
      first_line="Main St",
      second_line="123",
      city="San Francisco",
      state="CA",
      zip="94111",
      country="US",
      phone_number=""
  )


  data = client.testkit.register(user_id="<user_id>", sample_id="<sample_id>", patient_details=patient_details, patient_address=patient_address)
  ```

  ```javascript Node
  import { VitalClient, VitalEnvironment } from '@tryvital/vital-node';
  import { Gender } from '@tryvital/vital-node/api';
  import { RegisterTestkitRequest} from '@tryvital/vital-node/api/resources/testkit';

  const client = new VitalClient({
      apiKey: '<my_api_key>',
      environment: VitalEnvironment.Sandbox,
  });

  const request: RegisterTestkitRequest = {
      userId: "<user_id>",
      sampleId: "<sample_id>",
      patientDetails: {
          firstName: "<first_name>",
          lastName: "<last_name>",
          dob: new Date("1990-01-01"),
          gender: Gender.Female,
          phoneNumber: "<phone_number>",
          email: "<email>",
      },
      patientAddress: {
          receiverName: "<receiver_name>",
          FirstLine: "<street>",
          city: "<city>",
          state: "<state>",
          zip: "<zip>",
          country: "<country>",
          phoneNumber: "<phone_number>",
      },
  };

  const data = await client.testkit.register(request);
  ```

  ```java Java
  import com.vital.api.Vital;
  import com.vital.api.core.Environment;
  import com.vital.api.resources.testkit.requests.RegisterTestkitRequest;
  import com.vital.api.types.Gender;
  import com.vital.api.types.PatientAddressCompatible;
  import com.vital.api.types.PatientDetails;
  import java.time.OffsetDateTime;

  Vital vital = Vital.builder()
          .apiKey("YOUR_API_KEY")
          .environment(Environment.SANDBOX)
          .build();

  PatientDetails patientDetails = PatientDetails
          .builder()
          .firstName("<first_name>")
          .lastName("<last_name>")
          .dob(OffsetDateTime.parse("1990-01-01"))
          .gender(Gender.MALE)
          .phoneNumber("<phone_number>")
          .email("<email>")
          .build();

  PatientAddressCompatible patientAddress = PatientAddressCompatible
          .builder()
          .firstLine("<street>")
          .city("<city>")
          .state("<state>")
          .zip("<zip>")
          .country("<country>")
          .build();

  RegisterTestkitRequest request = RegisterTestkitRequest
          .builder()
          .userId("<user_id>")
          .sampleId("<sample_id>")
          .patientDetails(patientDetails)
          .patientAddress(patientAddress)
          .build();

  var data = vital.testkit().register(request);
  ```

  ```go Go
  import (
    "context"

    vital "github.com/tryVital/vital-go"
    vitalclient "github.com/tryVital/vital-go/client"
    "github.com/tryVital/vital-go/option"
  )

  request := &vital.RegisterTestkitRequest{
    UserId:   "<user_id>",
    SampleId: "<sample_id>",
    PatientDetails: &vital.PatientDetails{
      FirstName:   "<first_name>",
      LastName:    "<last_name>",
      Email:       "<email>",
      PhoneNumber: "<phone>",
      Dob:         time.Date(1990, 1, 1, 0, 0, 0, 0, time.UTC),
      Gender:      vital.GenderMale,
    },
    PatientAddress: &vital.PatientAddressCompatible{
      ReceiverName: vital.String("<receiver_name>"),
      FirstLine:    "<street>",
      City:         "<city>",
      State:        "<state>",
      Zip:          "<zip_code>",
      Country:      "<country>",
    },
  }

  response, err := client.Testkit.Register(context.TODO(), request)
  if err != nil {
    return err
  }
  fmt.Printf("Received data %s\n", response)
  ```

  ```bash cURL
  curl --request POST \
       --url https://api.tryvital.io/v3/order/testkit/register \
       --header 'Accept: application/json'
       --header 'x-vital-api-key: <API_KEY>' \
       --data '
  {
      "user_id":"63661a2b-2bb3-4125-bb1a-b590f64f057f",
      "sample_id":"123123123",
      "patient_details":{
          "first_name": "John",
          "last_name": "Doe",
          "dob": "2020-01-01",
          "gender": "male",
          "phone_number": "+1123456789",
          "email": "email@email.com"
      },
      "patient_address":{
        "receiver_name": "john Doe",
        "street": "123 Main St.",
        "street_number": "Apt. 208",
        "city": "San Francisco",
        "state": "CA",
        "zip": "91189",
        "country": "US"
      },
      "consents":[
        {"consentType": "terms-of-use"},
        {"consentType": "telehealth-informed-consent"},
        {"consentType": "notice-of-privacy-practices"},
      ],
      "physician":{
        "first_name": "Doctor",
        "last_name": "Doc",
        "npi": "123123123",
      }
  }
  '
  ```
</RequestExample>

<ResponseExample>
  ```json Response
  {
    "order": {
      "id": "96edc6ef-3b2c-412b-b9e5-96f361f93aec",
      "team_id": "b080b20c-e162-4cf1-9c7d-8faee72ee08e",
      "user_id": "9f1e094e-1641-466b-b668-d4d3300e569f",
      "patient_details": {
        "first_name": "John",
        "last_name": "Doe",
        "phone_number": "+11234567890",
        "email": "doe@email.com"
        "dob": "2020-01-01",
        "gender": "male"
      },
      "patient_address": {
        "receiver_name": "John Doe",
        "first_line": "123 Main St.",
        "second_line": "Apt. 208",
        "city": "San Francisco",
        "state": "CA",
        "zip": "91189",
        "country": "United States",
        "phone_number": "+11234567890"
      },
      "shipping_details": {
        "receiver_name": "John Doe",
        "first_line": "123 Main St.",
        "second_line": "Apt. 208",
        "city": "San Francisco",
        "state": "CA",
        "zip": "91189",
        "country": "United States",
        "phone_number": "+11234567890"
      },
      "details": {
        "type": "testkit",
        "data": {
          "id": "a655f0e4-6405-4a1d-80b7-66f06c2108a7",
          "shipment": {
            "id": "d55210cc-3d9f-4115-8262-5013f700c7be",
            "outbound_tracking_number": "<outbound_tracking_number>",
            "outbound_tracking_url": "<outbound_tracking_url>",
            "inbound_tracking_number": "<inbound_tracking_number>",
            "inbound_tracking_url": "<inbound_tracking_url>",
            "outbound_courier": "usps",
            "inbound_courier": "usps",
            "notes": "<notes>",
            "created_at": "2020-01-01T00:00:00.000Z",
            "updated_at": "2020-01-01T00:00:00.000Z"
          },
          "created_at": "2020-01-01T00:00:00Z",
          "updated_at": "2020-01-01T00:00:00Z"
        }
      },
      "lab_test": {
        "name": "Lipids Panel",
        "description": "Cholesterol test",
        "method": "testkit"
      },
      "sample_id": "123456789",
      "health_insurace_id": "7695cc28-f9e5-400d-95d2-ec7d9ec580df",
      "notes": "This is a note",
      "created_at": "2020-01-01T00:00:00Z",
      "updated_at": "2020-01-01T00:00:00Z",
      "status": "received",
      "events": [
        {
          "id": 1,
          "created_at": "2022-01-01T00:00:00Z",
          "status": "received.testkit.ordered"
        },
        {
          "id": 2,
          "created_at": "2022-01-02T00:00:00Z",
          "status": "received.testkit.awaiting_registration"
        },
        {
          "id": 3,
          "created_at": "2022-01-02T00:00:00Z",
          "status": "received.testkit.requisition_created"
        },
        {
          "id": 4,
          "created_at": "2022-01-03T00:00:00Z",
          "status": "received.testkit.testkit_registered"
        }
      ]
    },
    "status": "string",
    "message": "string"
  }
  ```
</ResponseExample>


# Get Requisition Form PDF
Source: https://docs.junction.com/api-reference/lab-testing/requisition-pdf

GET /v3/order/{order_id}/requisition/pdf
GET requisition pdf for an order

<RequestExample>
  ```bash cURL
  curl --request GET \
       --url '{{BASE_URL}}/v3/order/<order_id>/requisition/pdf' \
       --header 'accept: application/pdf' \
       --header 'x-vital-api-key: {YOUR_KEY}'
       --output file.pdf
  ```

  ```python Python
  from vital import Client

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

  data = client.LabTests.get_order_requisition_pdf(order_id='<order_id>');
  ```

  ```javascript Node
  import { VitalClient, VitalEnvironment } from '@tryvital/vital-node';

  const client = new VitalClient({
      apiKey: '<my_api_key>',
      environment: VitalEnvironment.Sandbox,
  });

  const data = await client.labTests.getOrderRequistionPdf("<order_id>");
  ```

  ```java Java
  import com.vital.api.Vital;
  import com.vital.api.core.Environment;

  Vital vital = Vital.builder()
          .apiKey("YOUR_API_KEY")
          .environment(Environment.SANDBOX)
          .build();

  var data = vital.labTests().getOrderRequistionPdf("<order_id>");
  ```

  ```go Go
  import (
    "context"

    vital "github.com/tryVital/vital-go"
    vitalclient "github.com/tryVital/vital-go/client"
    "github.com/tryVital/vital-go/option"
  )

  client := vitalclient.NewClient(
    option.WithApiKey("<YOUR_API_KEY>"),
    option.WithBaseURL(vital.Environments.Sandbox),
  )

  response, err := client.LabTests.GetOrderRequistionPdf(context.TODO(), "<order_id>")
  if err != nil {
    return err
  }
  fmt.Printf("Received data %s\n", response)
  ```
</RequestExample>


# Get Results
Source: https://docs.junction.com/api-reference/lab-testing/results/get-results

GET /v3/order/{order_id}/result
Return both metadata and raw json test data

<RequestExample>
  ```bash cURL
  curl --request GET \
       --url '{{BASE_URL}}/v3/order/<order_id>/result' \
       --header 'accept: application/json' \
       --header 'x-vital-api-key: {YOUR_KEY}'
  ```

  ```python Python
  from vital.client import Vital
  from vital.environment import VitalEnvironment

  client = Vital(
    api_key="YOUR_API_KEY",
    environment=VitalEnvironment.SANDBOX
  )

  data = client.lab_tests.get_result_raw(order_id="<order_id>")
  ```

  ```javascript Node
  import { VitalClient, VitalEnvironment } from '@tryvital/vital-node';

  const client = new VitalClient({
      apiKey: '<my_api_key>',
      environment: VitalEnvironment.Sandbox,
  });

  const data = await client.labTests.getResultRaw("<order_id>");
  ```

  ```java Java
  import com.vital.api.Vital;
  import com.vital.api.core.Environment;

  Vital vital = Vital.builder()
          .apiKey("YOUR_API_KEY")
          .environment(Environment.SANDBOX)
          .build();

  var data = vital.labTests().getResultRaw("<order_id>");
  ```

  ```go Go
  import (
    "context"

    vital "github.com/tryVital/vital-go"
    vitalclient "github.com/tryVital/vital-go/client"
    "github.com/tryVital/vital-go/option"
  )

  client := vitalclient.NewClient(
    option.WithApiKey("<YOUR_API_KEY>"),
    option.WithBaseURL(vital.Environments.Sandbox),
  )

  response, err := client.LabTests.GetResultRaw(context.TODO(), "<order_id>")
  if err != nil {
      return err
  }
  fmt.Printf("Received data %s\n", response)
  ```
</RequestExample>

<ResponseExample>
  ```json Response
  {
    "metadata": {
      "age": 19,
      "dob": "18/08/1993",
      "clia_number": "12331231",
      "patient": "Bob Smith",
      "provider": "Dr. Jack Smith",
      "laboratory": "LabCorp",
      "date_reported": "2020-01-01",
      "date_collected": "2022-02-02",
      "specimen_number": "123131",
      "date_received": "2022-01-01",
      "status": "final",
      "interpretation": "abnormal"
    },
    "results": [
      {
        "name": "Sex Horm Binding Glob, Serum",
        "slug": "sex-horm-binding-glob-serum",
        "value": 30.4,
        "result": "30.4",
        "type": "numeric",
        "unit": "nmol/L",
        "timestamp": "2024-10-31T09:08:00+00:00",
        "notes": "Final",
        "min_range_value": 24.6,
        "max_range_value": 122,
        "is_above_max_range": false,
        "is_below_min_range": false,
        "interpretation": "normal",
        "loinc": "13967-5",
        "loinc_slug": "sex-hormone-binding-globulin-moles-vol",
        "provider_id": "082016",
        "source_markers": [
          {
            "marker_id": 229,
            "name": "Testosterone Free, Profile I",
            "slug": "testosterone-free-profile-i",
            "provider_id": "140226"
          }
        ]
      }
    ]
  }
  ```
</ResponseExample>


# Get Results Metadata
Source: https://docs.junction.com/api-reference/lab-testing/results/get-results-metadata

GET /v3/order/{order_id}/result/metadata
Return metadata related to order results, such as lab metadata,
provider and sample dates.

<RequestExample>
  ```bash cURL
  curl --request GET \
       --url '{{BASE_URL}}/v3/order/<order_id>/result/metadata' \
       --header 'accept: application/json' \
       --header 'x-vital-api-key: {YOUR_KEY}'
  ```

  ```python Python
  from vital.client import Vital
  from vital.environment import VitalEnvironment

  client = Vital(
    api_key="YOUR_API_KEY",
    environment=VitalEnvironment.SANDBOX
  )

  data = client.lab_tests.get_result_metadata(order_id="<order_id>")
  ```

  ```javascript Node
  import { VitalClient, VitalEnvironment } from '@tryvital/vital-node';

  const client = new VitalClient({
      apiKey: '<my_api_key>',
      environment: VitalEnvironment.Sandbox,
  });

  const data = await client.labTests.getResultMetadata("<order_id>");
  ```

  ```java Java
  import com.vital.api.Vital;
  import com.vital.api.core.Environment;

  Vital vital = Vital.builder()
          .apiKey("YOUR_API_KEY")
          .environment(Environment.SANDBOX)
          .build();

  var data = vital.labTests().getResultMetadata("<order_id>");
  ```

  ```go Go
  import (
    "context"

    vital "github.com/tryVital/vital-go"
    vitalclient "github.com/tryVital/vital-go/client"
    "github.com/tryVital/vital-go/option"
  )

  client := vitalclient.NewClient(
    option.WithApiKey("<YOUR_API_KEY>"),
    option.WithBaseURL(vital.Environments.Sandbox),
  )

  response, err := client.LabTests.GetResultMetadata(context.TODO(), "<order_id>")
  if err != nil {
      return err
  }
  fmt.Printf("Received data %s\n", response)
  ```
</RequestExample>

<ResponseExample>
  ```json Response
  {
    "age": 19,
    "dob": "18/08/1993",
    "clia_number": "12331231",
    "patient": "Bob Smith",
    "provider": "Dr. Jack Smith",
    "laboratory": "Quest Diagnostics",
    "date_reported": "2020-01-01",
    "date_collected": "2022-02-02",
    "specimen_number": "123131",
    "date_received": "2022-01-01",
    "status": "final",
    "interpretation": "normal"
  }
  ```
</ResponseExample>


# Get Results PDF
Source: https://docs.junction.com/api-reference/lab-testing/results/get-results-pdf

GET /v3/order/{order_id}/result/pdf
This endpoint returns the lab results for the order.

<RequestExample>
  ```bash cURL
  curl --request GET \
       --url '{{BASE_URL}}/v3/order/<order_id>/result/pdf' \
       --header 'accept: application/json' \
       --header 'x-vital-api-key: {YOUR_KEY}'
  ```

  ```python Python
  from vital.client import Vital
  from vital.environment import VitalEnvironment

  client = Vital(
    api_key="YOUR_API_KEY",
    environment=VitalEnvironment.SANDBOX
  )

  data = client.lab_tests.get_result_pdf(order_id="<order_id>")
  ```

  ```javascript Node
  import { VitalClient, VitalEnvironment } from '@tryvital/vital-node';

  const client = new VitalClient({
      apiKey: '<my_api_key>',
      environment: VitalEnvironment.Sandbox,
  });

  const data = await client.labTests.getResultPdf("<order_id>");
  ```

  ```java Java
  import com.vital.api.Vital;
  import com.vital.api.core.Environment;

  Vital vital = Vital.builder()
          .apiKey("YOUR_API_KEY")
          .environment(Environment.SANDBOX)
          .build();

  var data = vital.labTests().getResultPdf("<order_id>");
  ```

  ```go Go
  import (
    "context"

    vital "github.com/tryVital/vital-go"
    vitalclient "github.com/tryVital/vital-go/client"
    "github.com/tryVital/vital-go/option"
  )

  client := vitalclient.NewClient(
    option.WithApiKey("<YOUR_API_KEY>"),
    option.WithBaseURL(vital.Environments.Sandbox),
  )

  response, err := client.LabTests.GetResultPdf(context.TODO(), "<order_id>")
  if err != nil {
      return err
  }
  fmt.Printf("Received data %s\n", response)
  ```
</RequestExample>

<ResponseExample>
  ```json Response
  "Returns PDF of test data - <specimen_number>.pdf"
  ```
</ResponseExample>


# Simulate Order
Source: https://docs.junction.com/api-reference/lab-testing/simulate-order

POST /v3/order/{order_id}/test
Simulate order lifecycle - Sandbox Only

<RequestExample>
  ```bash cURL
  curl --request POST \
       --url '{{BASE_URL}}/v3/order/<order_id>/test' \
       --header 'x-vital-api-key: {YOUR_KEY}'
  ```
</RequestExample>


# Get Available Tests
Source: https://docs.junction.com/api-reference/lab-testing/tests

GET /v3/lab_tests
GET all the lab tests the team has access to.

> **Deprecated:** This endpoint is deprecated. Please use the paginated version `/v3/lab_test` instead.

<RequestExample>
  ```python Python
  from vital.client import Vital
  from vital.environment import VitalEnvironment

  client = Vital(
    api_key="YOUR_API_KEY",
    environment=VitalEnvironment.SANDBOX
  )

  data = client.lab_tests.get();
  ```

  ```javascript Node
  import { VitalClient, VitalEnvironment } from '@tryvital/vital-node';

  const client = new VitalClient({
      apiKey: '<my_api_key>',
      environment: VitalEnvironment.Sandbox,
  });

  const data = await client.labTests.get();
  ```

  ```java Java
  import com.vital.api.Vital;
  import com.vital.api.core.Environment;

  Vital vital = Vital.builder()
          .apiKey("YOUR_API_KEY")
          .environment(Environment.SANDBOX)
          .build();

  var data = vital.labTests().get();
  ```

  ```go Go
  import (
    "context"

    vital "github.com/tryVital/vital-go"
    vitalclient "github.com/tryVital/vital-go/client"
    "github.com/tryVital/vital-go/option"
  )

  client := vitalclient.NewClient(
    option.WithApiKey("<YOUR_API_KEY>"),
    option.WithBaseURL(vital.Environments.Sandbox),
  )

  response, err := client.LabTests.Get(context.TODO())
  if err != nil {
      return err
  }
  fmt.Printf("Received data %s\n", response)
  ```
</RequestExample>

<ResponseExample>
  ```json Response
  [
    {
      "lab_test": {
        "name": "Lipids Panel",
        "description": "Cholesterol test",
        "sample_type": "dried blood spot",
        "method": "testkit",
        "price": 10,
        "is_active": true,
        "lab": {
          "slug": "USSL",
          "name": "US Specialty Lab",
          "first_line_address": "123 Main St",
          "city": "New York",
          "zipcode": "10001"
        },
        "markers": [
          {
            "name": "Thyroid Stimulating Hormone",
            "slug": "tsh",
            "description": ""
          }
        ]
      }
    }
  ]
  ```
</ResponseExample>


# Get Available Tests
Source: https://docs.junction.com/api-reference/lab-testing/tests-paginated

GET /v3/lab_test
GET lab tests the team has access to as a paginated list.

<RequestExample>
  ```python Python
  from vital.client import Vital
  from vital.environment import VitalEnvironment

  client = Vital(
    api_key="YOUR_API_KEY",
    environment=VitalEnvironment.SANDBOX
  )

  data = client.lab_tests.get_paginated();
  ```

  ```javascript Node
  import { VitalClient, VitalEnvironment } from '@tryvital/vital-node';

  const client = new VitalClient({
      apiKey: '<my_api_key>',
      environment: VitalEnvironment.Sandbox,
  });

  const data = await client.labTests.getPaginated();
  ```

  ```java Java
  import com.vital.api.Vital;
  import com.vital.api.core.Environment;

  Vital vital = Vital.builder()
          .apiKey("YOUR_API_KEY")
          .environment(Environment.SANDBOX)
          .build();

  var data = vital.labTests().getPaginated();
  ```

  ```go Go
  import (
    "context"

    vital "github.com/tryVital/vital-go"
    vitalclient "github.com/tryVital/vital-go/client"
  )

  client := vitalclient.NewClient(
    vitalclient.WithApiKey("<YOUR_API_KEY>"),
    vitalclient.WithBaseURL(vital.Environments.Sandbox),
  )

  response, err := client.LabTests.GetPaginated(context.TODO())
  if err != nil {
      return err
  }
  fmt.Printf("Received data %s\n", response)
  ```
</RequestExample>

<ResponseExample>
  ```json Response
  {
    "data": [
      {
        "lab_test": {
          "name": "Lipids Panel",
          "description": "Cholesterol test",
          "sample_type": "dried blood spot",
          "method": "testkit",
          "price": 10,
          "is_active": true,
          "lab": {
            "slug": "USSL",
            "name": "US Specialty Lab",
            "first_line_address": "123 Main St",
            "city": "New York",
            "zipcode": "10001"
          },
          "markers": [
            {
              "name": "Thyroid Stimulating Hormone",
              "slug": "tsh",
              "description": ""
            }
          ]
        }
      }
    ],
    "next_cursor": null
  }
  ```
</ResponseExample>


# Update Order Draw Completed
Source: https://docs.junction.com/api-reference/lab-testing/update-order-draw-completed

PATCH /v3/order/{order_id}/draw_completed
PATCH update on site collection order when draw is completed

<Card horizontal icon="person-digging" color="#57164A">
  This feature is in **closed beta**.

  Interested in this feature? Get in touch with your Customer Success Manager.
</Card>

Update an on-site collection order when the draw has been completed.

<RequestExample>
  ```python Python
  from vital.client import Vital
  from vital.environment import VitalEnvironment
  from vital.types.gender import Gender
  from vital.types.patient_address_compatible import PatientAddressCompatible
  from vital.types.patient_details import PatientDetails
  from datetime import datetime

  client = Vital(
    api_key="YOUR_API_KEY",
    environment=VitalEnvironment.SANDBOX
  )

  data = client.lab_tests.update_on_site_collection_order_draw_completed(
      order_id="order_id",
  )
  ```

  ```javascript Node
  import { VitalClient, VitalEnvironment } from '@tryvital/vital-node';

  const client = new VitalClient({
      apiKey: '<my_api_key>',
      environment: VitalEnvironment.Sandbox,
  });

  const data = await client.labTests.updateOnSiteCollectionOrderDrawCompleted("order_id")
  ```
</RequestExample>

<ResponseExample>
  ```json Response
  {
     "order": {
        "id": "ea7eae96-2c25-404f-b043-bfc08584610d",
        "team_id": "c26a9cc7-cdff-4f23-a5f6-74d40088c16a",
        "user_id": "63661a2b-2bb3-4125-bb1a-b590f64f057f",
        "patient_details": {
           "dob": "2020-01-01",
           "gender": "male"
        },
        "patient_address": {
           "receiver_name": "John Doe",
           "first_line": "123 Main St.",
           "second_line": "Apt. 208",
           "city": "San Francisco",
           "state": "CA",
           "zip": "91189",
           "country": "United States",
           "phone_number": "+1123456789"
        },
        "priority": false,
        "health_insurance_id": "33ec11aa-d8bf-4f46-950d-c9171be3c22f",
        "details": {
           "type": "testkit",
           "data": {
           "id": "a655f0e4-6405-4a1d-80b7-66f06c2108a7",
           "shipment": {
              "id": "d55210cc-3d9f-4115-8262-5013f700c7be",
              "outbound_tracking_number": "<outbound_tracking_number>",
              "outbound_tracking_url": "<outbound_tracking_url>",
              "inbound_tracking_number": "<inbound_tracking_number>",
              "inbound_tracking_url": "<inbound_tracking_url>",
              "outbound_courier": "usps",
              "inbound_courier": "usps",
              "notes": "<notes>",
              "created_at": "2020-01-01T00:00:00.000Z",
              "updated_at": "2020-01-01T00:00:00.000Z"
           },
           "created_at": "2020-01-01T00:00:00Z",
           "updated_at": "2020-01-01T00:00:00Z"
           }
        },
        "lab_test": {
           "name": "Lipids Panel",
           "description": "Cholesterol test",
           "method": "testkit"
        },
        "sample_id": "123456789",
        "notes": "This is a note",
        "created_at": "2020-01-01T00:00:00Z",
        "updated_at": "2020-01-01T00:00:00Z",
        "status": "collecting_sample",
        "events": [
           {
           "id": 1,
           "created_at": "2022-01-01T00:00:00Z",
           "status": "received.on_site_collection.ordered"
           },
           {
           "id": 2,
           "created_at": "2022-01-02T00:00:00Z",
           "status": "received.on_site_collection.requisition_created"
           },
           {
           "id": 3,
           "created_at": "2022-01-03T00:00:00Z",
           "status": "sample_with_lab.on_site_collection.draw_completed"
           }
        ]
     },
     "status": "string",
     "message": "string"
  }
  ```
</ResponseExample>


# Bulk Export
Source: https://docs.junction.com/api-reference/link/bulk-export

POST /v2/link/bulk_export

<Note>
  If you are planning to migrate connections, please [chat with us through support channels](/home/getting-support).
  Link Migration endpoints are disabled by default.
</Note>

<Warning>
  You should [pause the connections](/api-reference/link/bulk-pause) before bulk exporting them. Pausing stops
  Vital systems from refreshing the connections, ensuring the exported data are most up-to-date.
</Warning>


# Bulk Import
Source: https://docs.junction.com/api-reference/link/bulk-import

POST /v2/link/bulk_import

<Note>
  If you are planning to migrate connections, please [chat with us through support channels](/home/getting-support).
  Link Migration endpoints are disabled by default.
</Note>

Import existing provider connections to your [Bring Your Own OAuth](/wearables/connecting-providers/bring-your-own-oauth/overview) application credentials.

Before migrating any connection through this endpoint, you must first
[configure your BYOO app credential](/wearables/connecting-providers/bring-your-own-oauth/overview#setting-up-your-oauth-credentials) for the data provider
on your Vital Team.

Note that these connections cannot be migrated:

1. Any connection that is bound to an OAuth application credential not in your possession

2. Any connection that is not bound to the OAuth application credential set on your Vital Team.

### Asynchronous execution

The Bulk Import endpoint enqueues all connections you submitted to a persistent background operation. It then responds
*202 Created* immediately afterwards.

You can inspect the status of the resulting background operation through the [List Bulk Ops](/api-reference/link/list-bulk-ops) endpoint.

Optionally, you may opt into the `wait_for_completion` mode, which would respond 200 OK only if the operation does complete within 20 seconds.
Otherwise, the endpoint responds 202 Created.

<Note>
  You can submit any number of — or even all — connections through the Bulk Import API within a short period of time. Enqueuing is fast and
  does not disrupt the progress of the background operation.
</Note>


# Bulk Pause
Source: https://docs.junction.com/api-reference/link/bulk-pause

POST /v2/link/bulk_pause

<Note>
  If you are planning to migrate connections, please [chat with us through support channels](/home/getting-support).
  Link Migration endpoints are disabled by default.
</Note>


# Bulk Trigger Historical Pull
Source: https://docs.junction.com/api-reference/link/bulk-trigger-historical-pull

POST /v2/link/bulk_trigger_historical_pull

<Note>
  If you are planning to migrate connections, please [chat with us through support channels](/home/getting-support).
  Link Migration endpoints are disabled by default.
</Note>

### Asynchronous execution

The Bulk Trigger Historical Pull endpoint enqueues all trigger requests you submitted to a persistent background operation. It then responds
*202 Created* immediately afterwards.

You can inspect the status of the resulting background operation through the [List Bulk Ops](/api-reference/link/list-bulk-ops) endpoint.

Optionally, you may opt into the `wait_for_completion` mode, which would respond 200 OK only if the operation does complete within 20 seconds.
Otherwise, the endpoint responds 202 Created.

<Note>
  You can trigger historical pull on any number of — or even all — connections through the Bulk Trigger Historical Pull API within a short period
  of time. Enqueuing is fast and does not disrupt the progress of the background operation.
</Note>

#### Managing provider API rate limits

Junction transparently batches and throttles the trigger requests. This is to avoid exhausting the provider API rate limits of your Bring Your Own OAuth
custom credentials.

You can submit as many trigger requests as needed.

| Provider            | Historical Pull triggering Rate                                                                                                                                                           |
| ------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Garmin              | 2 connections every 1 minute                                                                                                                                                              |
| Fitbit, Polar       | 250 connections at a time; no time-based throttling                                                                                                                                       |
| Strava              | 1 connections every 15 minutes                                                                                                                                                            |
| Oura                | 150 connections every 5 minutes                                                                                                                                                           |
| Withings            | 8 connections every 1 minute, with the assumption of your app using [Withings Enterprise Plan](https://developer.withings.com/developer-guide/v3/withings-solutions/withings-api-plans/). |
| All other providers | 8 connections every 1 minute                                                                                                                                                              |

#### Historical Pull Range

Bulk Trigger Historical Pull respects any restricting [User Ingestion Bounds](/wearables/providers/data-ingestion-bounds) and/or any
[Team Data Pull Preferences](/wearables/providers/introduction#customizing-historical-data-pull-range) you have specified.

If you have specified a large number of days to pull, you should be aware that:

1. The background operation will take longer time to run to completion.
2. It may still cause temporary disruption to data polling and webhook processing, even after the triggering having been throttled.


# Complete Password Provider MFA
Source: https://docs.junction.com/api-reference/link/complete-password-provider-mfa

POST /v2/link/provider/password/{provider}/complete_mfa
This connects auth providers that are password based.

<RequestExample>
  ```bash cURL
  curl --request POST \
       --url {{BASE_URL}}/v2/link/provider/password/{provider}/complete_mfa \
       --header 'Accept: application/json' \
       --header 'Content-Type: application/json' \
       --header 'x-vital-link-token: <VITAL-LINK-TOKEN>' \
       --data '
  {
       "mfa_code": "012345"
  }
  '
  ```

  ```javascript Node
  import { VitalClient, VitalEnvironment } from '@tryvital/vital-node';
  import { CompletePasswordProviderMfaBody, PasswordProviders } from '@tryvital/vital-node/api';

  const request: CompletePasswordProviderMfaBody = {
      mfaCode: '<mfaCode>',
  }
  const data = await client.link.completePasswordProviderMfa(PasswordProviders.<provider>, request)
  ```

  ```python Python
  from vital.client import Vital
  from vital.environment import VitalEnvironment
  from vital.types.password_providers import PasswordProviders

  client = Vital(
    api_key="YOUR_API_KEY",
    environment=VitalEnvironment.SANDBOX
  )

  data = client.link.complete_password_provider_mfa(
    PasswordProviders.<provider>, 
    mfa_code="<mfaCode>", 
  )
  ```

  ```java Java
  import com.vital.api.Vital;
  import com.vital.api.core.Environment;
  import com.vital.api.resources.link.requests.CompletePasswordProviderMfaBody;
  import com.vital.api.types.PasswordProviders;

  Vital vital = Vital.builder()
          .apiKey("YOUR_API_KEY")
          .environment(Environment.SANDBOX)
          .build();

  IndividualProviderData request = CompletePasswordProviderMfaBody
          .builder()
          .mfaCode("<mfaCode>")
          .build();

  var data = vital.link().completePasswordProviderMfa(PasswordProviders.<provider>, request);
  ```

  ```go Go
  import (
    "context"

    vital "github.com/tryVital/vital-go"
    vitalclient "github.com/tryVital/vital-go/client"
    "github.com/tryVital/vital-go/option"
  )

  client := vitalclient.NewClient(
    option.WithApiKey("<YOUR_API_KEY>"),
    option.WithBaseURL(vital.Environments.Sandbox),
  )

  request := &vital.CompletePasswordProviderMfaBody{
    MfaCode: "<mfaCode>",
  }

  response, err := client.Link.CompletePasswordProviderMfa(
    context.TODO(), 
    vital.PasswordProviders<provider>, 
    request
  )
  if err != nil {
    return err
  }
  fmt.Printf("Received data %s\n", response)
  ```
</RequestExample>


# Create Code
Source: https://docs.junction.com/api-reference/link/create-code

POST /v2/link/code/create
Generate a token to invite a user of Vital mobile app to your team

Used for Vital iOS Apps to share Apple HealthKit with you. Please refer [here](/wearables/vital-app/introduction) for more information.

<RequestExample>
  ```bash cURL
  curl --request POST \
       --url {{BASE_URL}}/v2/link/code/create\?user_id\=1875c190-0cd6-46c1-8670-5b56a7794b78 \
       --header 'Accept: application/json' \
       --header 'Content-Type: application/json' \
       --header 'x-vital-api-key: <API_KEY>'
  ```

  ```javascript Node
  import { VitalClient, VitalEnvironment } from '@tryvital/vital-node';
  import { LinkCodeCreateRequest } from '@tryvital/vital-node/api';


  const client = new VitalClient({
      apiKey: '<my_api_key>',
      environment: VitalEnvironment.Sandbox,
  });

  const request: LinkCodeCreateRequest = {
      userId: '<my_user_id>',
  }

  const data = await client.link.codeCreate(request);
  ```

  ```python Python
  from vital.client import Vital
  from vital.environment import VitalEnvironment

  client = Vital(
    api_key="YOUR_API_KEY",
    environment=VitalEnvironment.SANDBOX
  )

  data = client.link.code_create(user_id='<my_user_id>')
  ```

  ```java Java
  import com.vital.api.Vital;
  import com.vital.api.core.Environment;
  import com.vital.api.resources.link.requests.LinkCodeCreateRequest;

  Vital vital = Vital.builder()
          .apiKey("YOUR_API_KEY")
          .environment(Environment.SANDBOX)
          .build();

  LinkCodeCreateRequest request = LinkCodeCreateRequest
          .builder()
          .userId("<my_user_id>")
          .build();

  var data = vital.link().codeCreate(request);
  ```

  ```go Go
  import (
    "context"

    vital "github.com/tryVital/vital-go"
    vitalclient "github.com/tryVital/vital-go/client"
    "github.com/tryVital/vital-go/option"
  )

  client := vitalclient.NewClient(
    option.WithApiKey("<YOUR_API_KEY>"),
    option.WithBaseURL(vital.Environments.Sandbox),
  )
  request := &vital.LinkCodeCreateRequest{
    UserId: "<my_user_id>",
  }

  response, err := client.Link.CodeCreate(context.TODO(), request)
  if err != nil {
    return err
  }
  fmt.Printf("Received data %s\n", response)

  ```
</RequestExample>


# Generate a link token
Source: https://docs.junction.com/api-reference/link/generate-link-token

POST /v2/link/token
Endpoint to generate a user link token, to be used throughout the vital
link process. The vital link token is a one time use token, that
expires after 10 minutes. If you would like vital-link widget to launch
with a specific provider, pass in a provider in the body. If you would
like to redirect to a custom url after successful or error connection,
pass in your own custom redirect_url parameter.

<RequestExample>
  ```bash cURL
  curl --request POST \
       --url {{BASE_URL}}/v2/link/token \
       --header 'Accept: application/json' \
       --header 'Content-Type: application/json' \
       --header 'x-vital-api-key: <API_KEY>' \
       --data '
  {
       "user_id": "1875c190-0cd6-46c1-8670-5b56a7794b78"
  }
  '
  ```

  ```javascript Node
  import { VitalClient, VitalEnvironment } from '@tryvital/vital-node';
  import { LinkTokenExchange } from '@tryvital/vital-node/api';


  const client = new VitalClient({
      apiKey: '<my_api_key>',
      environment: VitalEnvironment.Sandbox,
  });

  const request: LinkTokenExchange = {
      userId: "<user_id>",
      provider: "oura",
  }
  const data = await client.link.token(request)
  ```

  ```python Python
  from vital.client import Vital
  from vital.environment import VitalEnvironment
  from vital.types.providers import Providers

  client = Vital(
    api_key="YOUR_API_KEY",
    environment=VitalEnvironment.SANDBOX
  )

  data = client.link.token(user_id="<user_id>", provider=Providers.OURA)
  ```

  ```java Java
  import com.vital.api.Vital;
  import com.vital.api.core.Environment;
  import com.vital.api.resources.link.requests.LinkTokenExchange;
  import com.vital.api.types.Providers;

  Vital vital = Vital.builder()
       .apiKey("YOUR_API_KEY")
       .environment(Environment.SANDBOX)
       .build();

  LinkTokenExchange request = LinkTokenExchange
       .builder()
       .userId("<user_id>")
       .provider(Providers.OURA)
       .build();

  var data = vital.link().token(request);
  ```

  ```go Go
  import (
    "context"

    vital "github.com/tryVital/vital-go"
    vitalclient "github.com/tryVital/vital-go/client"
    "github.com/tryVital/vital-go/option"
  )

  client := vitalclient.NewClient(
    option.WithApiKey("<YOUR_API_KEY>"),
    option.WithBaseURL(vital.Environments.Sandbox),
  )

  provider := vital.ProvidersOura
  request := &vital.LinkTokenExchange{
       UserId:   "<user_id>",
       Provider: &provider,
  }

  response, err := client.Link.Token(context.TODO(), request)
  if err != nil {
    return err
  }
  fmt.Printf("Received data %s\n", response)
  ```
</RequestExample>


# Link Demo provider
Source: https://docs.junction.com/api-reference/link/link-demo-provider

POST /v2/link/connect/demo
POST Connect the given Vital user to a demo provider.

<RequestExample>
  ```bash cURL
  curl --request POST \
       --url {{BASE_URL}}/v2/link/connect/demo \
       --header 'Accept: application/json' \
       --header 'Content-Type: application/json' \
       --header 'x-vital-link-token: <VITAL-LINK-TOKEN>' \
       --data '
  {
      "user_id": "1875c190-0cd6-46c1-8670-5b56a7794b78"
      "provider": "fitbit"
  }
  '
  ```

  ```javascript Node
  import { VitalClient, VitalEnvironment } from '@tryvital/vital-node';
  import { DemoConnectionCreationPayload, DemoProviders } from '@tryvital/vital-node/api';


  const client = new VitalClient({
      apiKey: '<my_api_key>',
      environment: VitalEnvironment.Sandbox,
  });

  const request: DemoConnectionCreationPayload = {
      userId: "<user_id>",
      provider: DemoProviders.<provider>,
  }
  const data = await client.link.connectDemoProvider(request);
  ```

  ```python Python
  from vital.client import Vital
  from vital.environment import VitalEnvironment

  client = Vital(
    api_key="YOUR_API_KEY",
    environment=VitalEnvironment.SANDBOX
  )

  data = client.link.connect_demo_provider(user_id="<user_id>", provider=DemoProviders.<provider>)
  ```

  ```java Java
  import com.vital.api.Vital;
  import com.vital.api.core.Environment;
  import com.vital.api.resources.link.requests.DemoConnectionCreationPayload;
  import com.vital.api.types.DemoProviders;

  Vital vital = Vital.builder()
          .apiKey("YOUR_API_KEY")
          .environment(Environment.SANDBOX)
          .build();

  DemoConnectionCreationPayload request = DemoConnectionCreationPayload
          .builder()
          .userId("<user_id>")
          .provider(DemoProviders.<provider>)
          .build();

  var data = vital.link().connectDemoProvider(request);
  ```

  ```go Go
  import (
    "context"

    vital "github.com/tryVital/vital-go"
    vitalclient "github.com/tryVital/vital-go/client"
    "github.com/tryVital/vital-go/option"
  )

  client := vitalclient.NewClient(
    option.WithApiKey("<YOUR_API_KEY>"),
    option.WithBaseURL(vital.Environments.Sandbox),
  )
  request := &vital.DemoConnectionCreationPayload{
    UserId:   "<user_id>",
    Provider: vital.DemoProviders<provider_name>,
  }

  response, err := client.Link.ConnectDemoProvider(context.TODO(), request)
  if err != nil {
    return err
  }
  fmt.Printf("Received data %s\n", response)
  ```
</RequestExample>


# Link Email provider
Source: https://docs.junction.com/api-reference/link/link-email-provider

POST /v2/link/provider/email/{provider}
This connects auth providers that are email based.

<RequestExample>
  ```bash cURL
  curl --request POST \
       --url {{BASE_URL}}/v2/link/provider/email/{provider} \
       --header 'Accept: application/json' \
       --header 'Content-Type: application/json' \
       --header 'x-vital-link-token: <VITAL-LINK-TOKEN>' \
       --data '
  {
       "email": "test@email.com"
       "region": "us"
  }
  '
  ```

  ```javascript Node
  import { VitalClient, VitalEnvironment } from '@tryvital/vital-node';
  import { EmailProviderAuthLink, LinkTokenExchange } from '@tryvital/vital-node/api';


  const client = new VitalClient({
      apiKey: '<my_api_key>',
      environment: VitalEnvironment.Sandbox,
  });

  const request: LinkTokenExchange = {
      userId: "<user_id>",
  }
  const tokenResponse = await client.link.token(request)

  const linkRequest: EmailProviderAuthLink = {
      vitalLinkToken: tokenResponse.linkToken,
      email: "<email>",
      region: Region.<region>
  }

  const connectEmailResponse = await client.link.connectEmailAuthProvider(
      "freestyle_libre",
      linkRequest
  )
  ```

  ```python Python
  from vital.client import Vital
  from vital.environment import VitalEnvironment

  client = Vital(
    api_key="YOUR_API_KEY",
    environment=VitalEnvironment.SANDBOX
  )

  token_response = client.link.token(user_id="<user_id>")

  linkResponse = client.link.connect_email_auth_provider(
    provider="freestyle_libre", 
    email="<email>", 
    vital_link_token=token_response.link_token
  )
  ```

  ```java Java
  import com.vital.api.Vital;
  import com.vital.api.core.Environment;
  import com.vital.api.resources.link.requests.EmailProviderAuthLink;

  Vital vital = Vital.builder()
          .apiKey("YOUR_API_KEY")
          .environment(Environment.SANDBOX)
          .build();

  LinkTokenExchange request = LinkTokenExchange
          .builder()
          .userId("<user_id>")
          .build();

  var tokenResponse = vital.link().token(request);

  EmailProviderAuthLink request = EmailProviderAuthLink
          .builder()
          .vitalLinkToken(tokenResponse.getLinkToken())
          .email("<email>")
          .build();

  var data = vital.link().connectEmailAuthProvider("<provider", request);
  ```

  ```go Go
  import (
    "context"

    vital "github.com/tryVital/vital-go"
    vitalclient "github.com/tryVital/vital-go/client"
    "github.com/tryVital/vital-go/option"
  )

  client := vitalclient.NewClient(
    option.WithApiKey("<YOUR_API_KEY>"),
    option.WithBaseURL(vital.Environments.Sandbox),
  )

  provider := vital.ProvidersOura
  request := &vital.LinkTokenExchange{
    UserId:   "<user_id>",
    Provider: &provider,
  }

  response, err := client.Link.Token(context.TODO(), request)

  if err != nil {
    return err
  }

  emailAuthRequest := &vital.EmailProviderAuthLink{
    VitalLinkToken: response.LinkToken,
    Email:          "<email>",
  }

  emailAuth, err := client.Link.ConnectEmailAuthProvider(context.TODO(), "freestyle_libre", emailAuthRequest)
  if err != nil {
    return err
  }
  fmt.Printf("Received data %s\n", emailAuth)
  ```
</RequestExample>


# Link OAuth provider
Source: https://docs.junction.com/api-reference/link/link-oauth-provider

GET /v2/link/provider/oauth/{oauth_provider}
This endpoint generates an OAuth link for oauth provider

<RequestExample>
  ```bash cURL
  curl --request GET \
       --url {{BASE_URL}}/v2/link/provider/oauth/{oauth_provider} \
       --header 'Accept: application/json'
       --header 'Content-Type: application/json' \
       --header 'x-vital-link-token: <VITAL-LINK-TOKEN>'
  ```

  ```javascript Node
  import { VitalClient, VitalEnvironment } from '@tryvital/vital-node';
  import { LinkTokenExchange, LinkGenerateOauthLinkRequest, OAuthProviders } from '@tryvital/vital-node/api';


  const client = new VitalClient({
      apiKey: '<my_api_key>',
      environment: VitalEnvironment.Sandbox,
  });

  const request: LinkTokenExchange = {
      userId: "<user_id>",
  }
  const tokenResponse = await client.link.token(request)

  const linkRequest: LinkGenerateOauthLinkRequest = {
      vitalLinkToken: tokenResponse.linkToken,
  }

  const auth = await client.link.generateOauthLink(
      OAuthProviders.<provider>,
      linkRequest
  )
  ```

  ```python Python
  from vital.client import Vital
  from vital.environment import VitalEnvironment
  from vital.types.o_auth_providers import OAuthProviders

  client = Vital(
    api_key="YOUR_API_KEY",
    environment=VitalEnvironment.SANDBOX
  )

  token_response = client.link.token(user_id="<user_id>")

  oauth = client.link.generate_oauth_link(
    oauth_provider=OAuthProviders.<provider>,
    vital_link_token=token_response.link_token,
  )
  ```

  ```java Java
  import com.vital.api.Vital;
  import com.vital.api.core.Environment;
  import com.vital.api.resources.link.requests.LinkGenerateOauthLinkRequest;
  import com.vital.api.resources.link.requests.LinkTokenExchange;
  import com.vital.api.types.OAuthProviders;

  Vital vital = Vital.builder()
          .apiKey("YOUR_API_KEY")
          .environment(Environment.SANDBOX)
          .build();

  LinkTokenExchange request = LinkTokenExchange
          .builder()
          .userId("<user_id>")
          .build();

  var tokenResponse = vital.link().token(request);

  LinkGenerateOauthLinkRequest link_request = LinkGenerateOauthLinkRequest
          .builder()
          .vitalLinkToken(tokenResponse.getLinkToken())
          .build();

  var oauth = vital.link().generateOauthLink(OAuthProviders.OURA, link_request);
  ```

  ```go Go
  import (
    "context"

    vital "github.com/tryVital/vital-go"
    vitalclient "github.com/tryVital/vital-go/client"
    "github.com/tryVital/vital-go/option"
  )

  client := vitalclient.NewClient(
    option.WithApiKey("<YOUR_API_KEY>"),
    option.WithBaseURL(vital.Environments.Sandbox),
  )
  provider := vital.ProvidersOura
  request := &vital.LinkTokenExchange{
    UserId:   "<user_id>",
    Provider: &provider,
  }

  response, err := client.Link.Token(context.TODO(), request)

  if err != nil {
    return err
  }

  generateLinkRequest := &vital.LinkGenerateOauthLinkRequest{
    VitalLinkToken: response.LinkToken,
  }

  oauth, err := client.Link.GenerateOauthLink(context.TODO(), vital.OAuthProvidersOura, generateLinkRequest)

  if err != nil {
    return err
  }
  fmt.Printf("Received data %s\n", oauth)
  ```
</RequestExample>


# Link Password provider
Source: https://docs.junction.com/api-reference/link/link-password-provider

POST /v2/link/provider/password/{provider}
This connects auth providers that are password based.

<RequestExample>
  ```bash cURL
  curl --request POST \
       --url {{BASE_URL}}/v2/link/provider/password/{provider} \
       --header 'Accept: application/json' \
       --header 'Content-Type: application/json' \
       --header 'x-vital-link-token: <VITAL-LINK-TOKEN>' \
       --data '
  {
       "username": "test",
       "password": "test"
  }
  '
  ```

  ```javascript Node
  import { VitalClient, VitalEnvironment } from '@tryvital/vital-node';
  import { IndividualProviderData, PasswordProviders } from '@tryvital/vital-node/api';

  const request: IndividualProviderData = {
      username: '<username>',
      password: '<password>',
  }
  const data = await client.link.connectPasswordProvider(PasswordProviders.<provider>, request)
  ```

  ```python Python
  from vital.client import Vital
  from vital.environment import VitalEnvironment
  from vital.types.password_providers import PasswordProviders

  client = Vital(
    api_key="YOUR_API_KEY",
    environment=VitalEnvironment.SANDBOX
  )

  data = client.link.connect_password_provider(
    PasswordProviders.<provider>, 
    username="<username>", 
    password="<password>"
  )
  ```

  ```java Java
  import com.vital.api.Vital;
  import com.vital.api.core.Environment;
  import com.vital.api.resources.link.requests.IndividualProviderData;
  import com.vital.api.types.PasswordProviders;

  Vital vital = Vital.builder()
          .apiKey("YOUR_API_KEY")
          .environment(Environment.SANDBOX)
          .build();

  IndividualProviderData request = IndividualProviderData
          .builder()
          .username("<username>")
          .password("<password>")
          .build();

  var data = vital.link().connectPasswordProvider(PasswordProviders.<provider>, request);
  ```

  ```go Go
  import (
    "context"

    vital "github.com/tryVital/vital-go"
    vitalclient "github.com/tryVital/vital-go/client"
    "github.com/tryVital/vital-go/option"
  )

  client := vitalclient.NewClient(
    option.WithApiKey("<YOUR_API_KEY>"),
    option.WithBaseURL(vital.Environments.Sandbox),
  )

  request := &vital.IndividualProviderData{
    Username: "<username>",
    Password: "<password>",
  }

  response, err := client.Link.ConnectPasswordProvider(
    context.TODO(), 
    vital.PasswordProviders<provider>, 
    request
  )
  if err != nil {
    return err
  }
  fmt.Printf("Received data %s\n", response)
  ```
</RequestExample>


# List Bulk Ops
Source: https://docs.junction.com/api-reference/link/list-bulk-ops

GET /v2/link/bulk_op

<Note>
  If you are planning to migrate connections, please [chat with us through support channels](/home/getting-support).
  Link Migration endpoints are disabled by default.
</Note>


# Create or Resend Invite
Source: https://docs.junction.com/api-reference/org-management/invite/create-or-resend-invite

post /v1/org/{org_id}/invite

<Info>
  [Junction Management API](/api-details/junction-management-api) is available for [the Scale plan](https://tryvital.io/pricing).
</Info>

<Tip>
  The base URL of this endpoint is `https://api.tryvital.io/management/`.

  The endpoint accepts only [Management Key](/api-details/junction-management-api#authentication) (`X-Management-Key`).
  Team API Key is not accepted.
</Tip>

<RequestExample>
  ```bash cURL
  curl --request POST \
    --url https://api.tryvital.io/management/v1/org/{org_id}/invite \
    --header 'Content-Type: application/json' \
    --header 'X-Vital-Org-Key: <api-key>' \
    --data '{
    "email": "<string>"
  }'
  ```
</RequestExample>


# List Invites
Source: https://docs.junction.com/api-reference/org-management/invite/list-invites

get /v1/org/{org_id}/invite

<Info>
  [Junction Management API](/api-details/junction-management-api) is available for [the Scale plan](https://tryvital.io/pricing).
</Info>

<Tip>
  The base URL of this endpoint is `https://api.tryvital.io/management/`.

  The endpoint accepts only [Management Key](/api-details/junction-management-api#authentication) (`X-Management-Key`).
  Team API Key is not accepted.
</Tip>

<RequestExample>
  ```bash cURL
  curl --request GET \
    --url https://api.tryvital.io/management/v1/org/{org_id}/invite \
    --header 'X-Vital-Org-Key: <api-key>'
  ```
</RequestExample>


# Revoke Invite
Source: https://docs.junction.com/api-reference/org-management/invite/revoke-invite

delete /v1/org/{org_id}/invite/{invite_id}

<Info>
  [Junction Management API](/api-details/junction-management-api) is available for [the Scale plan](https://tryvital.io/pricing).
</Info>

<Tip>
  The base URL of this endpoint is `https://api.tryvital.io/management/`.

  The endpoint accepts only [Management Key](/api-details/junction-management-api#authentication) (`X-Management-Key`).
  Team API Key is not accepted.
</Tip>

<RequestExample>
  ```bash cURL
  curl --request DELETE \
    --url https://api.tryvital.io/management/v1/org/{org_id}/invite/{invite_id} \
    --header 'X-Vital-Org-Key: <api-key>'
  ```
</RequestExample>


# Create Management Key
Source: https://docs.junction.com/api-reference/org-management/management-keys/create-management-key

post /v1/org/{org_id}/management_key

<Info>
  [Junction Management API](/api-details/junction-management-api) is available for [the Scale plan](https://tryvital.io/pricing).
</Info>

<Tip>
  The base URL of this endpoint is `https://api.tryvital.io/management/`.

  The endpoint accepts only [Management Key](/api-details/junction-management-api#authentication) (`X-Management-Key`).
  Team API Key is not accepted.
</Tip>

<RequestExample>
  ```bash cURL
  curl --request POST \
    --url https://api.tryvital.io/management/v1/org/{org_id}/management_key \
    --header 'Content-Type: application/json' \
    --header 'X-Vital-Org-Key: <api-key>' \
    --data '{
    "label": "<string>",
    "team_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
  }'
  ```
</RequestExample>


# Delete Management Key
Source: https://docs.junction.com/api-reference/org-management/management-keys/delete-management-key

delete /v1/org/{org_id}/management_key/{key_id}

<Info>
  [Junction Management API](/api-details/junction-management-api) is available for [the Scale plan](https://tryvital.io/pricing).
</Info>

<Tip>
  The base URL of this endpoint is `https://api.tryvital.io/management/`.

  The endpoint accepts only [Management Key](/api-details/junction-management-api#authentication) (`X-Management-Key`).
  Team API Key is not accepted.
</Tip>

<RequestExample>
  ```bash cURL
  curl --request DELETE \
    --url https://api.tryvital.io/management/v1/org/{org_id}/management_key \
    --header 'X-Vital-Org-Key: <api-key>'
  ```
</RequestExample>


# List Management Keys
Source: https://docs.junction.com/api-reference/org-management/management-keys/list-management-keys

get /v1/org/{org_id}/management_key

<Info>
  [Junction Management API](/api-details/junction-management-api) is available for [the Scale plan](https://tryvital.io/pricing).
</Info>

<Tip>
  The base URL of this endpoint is `https://api.tryvital.io/management/`.

  The endpoint accepts only [Management Key](/api-details/junction-management-api#authentication) (`X-Management-Key`).
  Team API Key is not accepted.
</Tip>

<RequestExample>
  ```bash cURL
  curl --request GET \
    --url https://api.tryvital.io/management/v1/org/{org_id}/management_key \
    --header 'X-Vital-Org-Key: <api-key>'
  ```
</RequestExample>


# List Members
Source: https://docs.junction.com/api-reference/org-management/member/list-members

get /v1/org/{org_id}/member

<Info>
  [Junction Management API](/api-details/junction-management-api) is available for [the Scale plan](https://tryvital.io/pricing).
</Info>

<Tip>
  The base URL of this endpoint is `https://api.tryvital.io/management/`.

  The endpoint accepts only [Management Key](/api-details/junction-management-api#authentication) (`X-Management-Key`).
  Team API Key is not accepted.
</Tip>

<RequestExample>
  ```bash cURL
  curl --request GET \
    --url https://api.tryvital.io/management/v1/org/{org_id}/member \
    --header 'X-Vital-Org-Key: <api-key>'
  ```
</RequestExample>


# Delete Member
Source: https://docs.junction.com/api-reference/org-management/member/remove-member

delete /v1/org/{org_id}/member/{member_id}

<Info>
  [Junction Management API](/api-details/junction-management-api) is available for [the Scale plan](https://tryvital.io/pricing).
</Info>

<Tip>
  The base URL of this endpoint is `https://api.tryvital.io/management/`.

  The endpoint accepts only [Management Key](/api-details/junction-management-api#authentication) (`X-Management-Key`).
  Team API Key is not accepted.
</Tip>

<RequestExample>
  ```bash cURL
  curl --request DELETE \
    --url https://api.tryvital.io/management/v1/org/{org_id}/member/{member_id} \
    --header 'X-Vital-Org-Key: <api-key>'
  ```
</RequestExample>


# Get Org
Source: https://docs.junction.com/api-reference/org-management/org/get-org

get /v1/org/{org_id}

<Info>
  [Junction Management API](/api-details/junction-management-api) is available for [the Scale plan](https://tryvital.io/pricing).
</Info>

<Tip>
  The base URL of this endpoint is `https://api.tryvital.io/management/`.

  The endpoint accepts only [Management Key](/api-details/junction-management-api#authentication) (`X-Management-Key`).
  Team API Key is not accepted.
</Tip>

<RequestExample>
  ```bash cURL
  curl --request GET \
    --url https://api.tryvital.io/management/v1/org/{org_id} \
    --header 'X-Vital-Org-Key: <api-key>'
  ```
</RequestExample>


# Update Org
Source: https://docs.junction.com/api-reference/org-management/org/update-org

patch /v1/org/{org_id}

<Info>
  [Junction Management API](/api-details/junction-management-api) is available for [the Scale plan](https://tryvital.io/pricing).
</Info>

<Tip>
  The base URL of this endpoint is `https://api.tryvital.io/management/`.

  The endpoint accepts only [Management Key](/api-details/junction-management-api#authentication) (`X-Management-Key`).
  Team API Key is not accepted.
</Tip>

<RequestExample>
  ```bash cURL
  curl --request PATCH \
    --url https://api.tryvital.io/management/v1/org/{org_id} \
    --header 'X-Vital-Org-Key: <api-key>'
  ```
</RequestExample>


# Create Team API Key
Source: https://docs.junction.com/api-reference/org-management/team-api-keys/create-team-api-key

post /v1/org/{org_id}/team_api_keys/{env}/{region}

<Info>
  [Junction Management API](/api-details/junction-management-api) is available for [the Scale plan](https://tryvital.io/pricing).
</Info>

<Tip>
  The base URL of this endpoint is `https://api.tryvital.io/management/`.

  The endpoint accepts only [Management Key](/api-details/junction-management-api#authentication) (`X-Management-Key`).
  Team API Key is not accepted.
</Tip>

<RequestExample>
  ```bash cURL
  curl --request POST \
    --url https://api.tryvital.io/management/v1/org/{org_id}/team_api_keys/{env}/{region} \
    --header 'Content-Type: application/json' \
    --header 'X-Vital-Org-Key: <api-key>' \
    --data '{
    "label": "<string>",
    "team_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
  }'
  ```
</RequestExample>


# Delete Team API Keys
Source: https://docs.junction.com/api-reference/org-management/team-api-keys/delete-team-api-keys

delete /v1/org/{org_id}/team_api_keys/{env}/{region}

<Info>
  [Junction Management API](/api-details/junction-management-api) is available for [the Scale plan](https://tryvital.io/pricing).
</Info>

<Tip>
  The base URL of this endpoint is `https://api.tryvital.io/management/`.

  The endpoint accepts only [Management Key](/api-details/junction-management-api#authentication) (`X-Management-Key`).
  Team API Key is not accepted.
</Tip>

<RequestExample>
  ```bash cURL
  curl --request DELETE \
    --url https://api.tryvital.io/management/v1/org/{org_id}/team_api_keys/{env}/{region} \
    --header 'X-Vital-Org-Key: <api-key>'
  ```
</RequestExample>


# List Team API Keys
Source: https://docs.junction.com/api-reference/org-management/team-api-keys/list-team-api-keys

get /v1/org/{org_id}/team_api_keys/{env}/{region}

<Info>
  [Junction Management API](/api-details/junction-management-api) is available for [the Scale plan](https://tryvital.io/pricing).
</Info>

<Tip>
  The base URL of this endpoint is `https://api.tryvital.io/management/`.

  The endpoint accepts only [Management Key](/api-details/junction-management-api#authentication) (`X-Management-Key`).
  Team API Key is not accepted.
</Tip>

<RequestExample>
  ```bash cURL
  curl --request GET \
    --url https://api.tryvital.io/management/v1/org/{org_id}/team_api_keys/{env}/{region} \
    --header 'X-Vital-Org-Key: <api-key>'
  ```
</RequestExample>


# Delete Team Custom Credentials
Source: https://docs.junction.com/api-reference/org-management/team-custom-credentials/delete-team-custom-credentials

delete /v1/org/{org_id}/team_custom_credentials/{env}/{region}

<Info>
  [Junction Management API](/api-details/junction-management-api) is available for [the Scale plan](https://tryvital.io/pricing).
</Info>

<Tip>
  The base URL of this endpoint is `https://api.tryvital.io/management/`.

  The endpoint accepts only [Management Key](/api-details/junction-management-api#authentication) (`X-Management-Key`).
  Team API Key is not accepted.
</Tip>

<RequestExample>
  ```bash cURL
  curl --request DELETE \
    --url https://api.tryvital.io/management/v1/org/{org_id}/team_custom_credentials/{env}/{region} \
    --header 'X-Vital-Org-Key: <api-key>'
  ```
</RequestExample>


# Get Team Custom Credentials
Source: https://docs.junction.com/api-reference/org-management/team-custom-credentials/get-team-custom-credentials

get /v1/org/{org_id}/team_custom_credentials/{env}/{region}

<Info>
  [Junction Management API](/api-details/junction-management-api) is available for [the Scale plan](https://tryvital.io/pricing).
</Info>

<Tip>
  The base URL of this endpoint is `https://api.tryvital.io/management/`.

  The endpoint accepts only [Management Key](/api-details/junction-management-api#authentication) (`X-Management-Key`).
  Team API Key is not accepted.
</Tip>

<RequestExample>
  ```bash cURL
  curl --request GET \
    --url https://api.tryvital.io/management/v1/org/{org_id}/team_custom_credentials/{env}/{region} \
    --header 'X-Vital-Org-Key: <api-key>'
  ```
</RequestExample>


# Prepare Team Custom Credentials
Source: https://docs.junction.com/api-reference/org-management/team-custom-credentials/prepare-team-custom-credentials

POST /v1/org/{org_id}/prepare_team_custom_credentials/{env}/{region}

<Info>
  [Junction Management API](/api-details/junction-management-api) is available for [the Scale plan](https://tryvital.io/pricing).
</Info>

<Tip>
  The base URL of this endpoint is `https://api.tryvital.io/management/`.

  The endpoint accepts only [Management Key](/api-details/junction-management-api#authentication) (`X-Management-Key`).
  Team API Key is not accepted.
</Tip>

<RequestExample>
  ```bash cURL
  curl --request GET \
    --url https://api.tryvital.io/management/v1/org/{org_id}/prepare_team_custom_credentials/{env}/{region} \
    --header 'X-Vital-Org-Key: <api-key>'
  ```
</RequestExample>


# Set Team Custom Credentials
Source: https://docs.junction.com/api-reference/org-management/team-custom-credentials/upsert-team-custom-credentials

post /v1/org/{org_id}/team_custom_credentials/{env}/{region}

<Info>
  [Junction Management API](/api-details/junction-management-api) is available for [the Scale plan](https://tryvital.io/pricing).
</Info>

<Tip>
  The base URL of this endpoint is `https://api.tryvital.io/management/`.

  The endpoint accepts only [Management Key](/api-details/junction-management-api#authentication) (`X-Management-Key`).
  Team API Key is not accepted.
</Tip>

### OAuth Providers

<Info>
  Bring Your Own OAuth (BYOO) is available for [the Grow and Scale plans](https://tryvital.io/pricing).
  WHOOP BYOO is available for [the Launch, Grow and Scale plans](https://tryvital.io/pricing). See [our WHOOP Guide](/wearables/guides/whoop) for more information.
</Info>

While most credentials are active immediately once set through this endpoint, some credentials may not.
Check out the [Bring Your Own OAuth](/wearables/connecting-providers/bring_your_own_oauth#through-the-org-management-api) documentation
for more information.

<RequestExample>
  ```bash cURL
  curl --request POST \
    --url https://api.tryvital.io/management/v1/org/{org_id}/team_custom_credentials/{env}/{region} \
    --header 'Content-Type: application/json' \
    --header 'X-Vital-Org-Key: <api-key>' \
    --data '{
    "team_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "provider": "oura",
    "client_id": "<string>",
    "client_secret": "<string>",
    "details": {
      "fitbit": {
        "is_hr_enabled": true,
        "workout_verify_token": "<string>",
        "sleep_verify_token": "<string>",
        "body_verify_token": "<string>"
      }
    }
  }'
  ```
</RequestExample>


# Delete Team Data Pull Preferences
Source: https://docs.junction.com/api-reference/org-management/team-data-pull-preferences/delete-team-data-pull-preferences

delete /v1/org/{org_id}/team_data_pull_preferences/{env}/{region}

<Info>
  [Junction Management API](/api-details/junction-management-api) is available for [the Scale plan](https://tryvital.io/pricing).
</Info>

<Tip>
  The base URL of this endpoint is `https://api.tryvital.io/management/`.

  The endpoint accepts only [Management Key](/api-details/junction-management-api#authentication) (`X-Management-Key`).
  Team API Key is not accepted.
</Tip>

<Info>
  Deleting preferences for a provider will revert to the default settings.
</Info>

<RequestExample>
  ```bash cURL
  curl --request DELETE \
    --url https://api.tryvital.io/management/v1/org/{org_id}/team_data_pull_preferences/{env}/{region} \
    --header 'X-Vital-Org-Key: <api-key>'
  ```
</RequestExample>


# Get Team Data Pull Preferences
Source: https://docs.junction.com/api-reference/org-management/team-data-pull-preferences/get-team-data-pull-preferences

get /v1/org/{org_id}/team_data_pull_preferences/{env}/{region}

<RequestExample>
  ```bash cURL
  curl --request GET \
    --url https://api.tryvital.io/management/v1/org/{org_id}/team_data_pull_preferences/{env}/{region} \
    --header 'X-Vital-Org-Key: <api-key>'
  ```
</RequestExample>

<Info>
  The endpoint will return the default vital settings if no custom preferences are set.
</Info>

<Info>
  [Junction Management API](/api-details/junction-management-api) is available for [the Scale plan](https://tryvital.io/pricing).
</Info>

<Tip>
  The base URL of this endpoint is `https://api.tryvital.io/management/`.

  The endpoint accepts only [Management Key](/api-details/junction-management-api#authentication) (`X-Management-Key`).
  Team API Key is not accepted.
</Tip>


# Post Team Data Pull Preferences
Source: https://docs.junction.com/api-reference/org-management/team-data-pull-preferences/upsert-team-data-pull-preferences

post /v1/org/{org_id}/team_data_pull_preferences/{env}/{region}

<Info>
  [Junction Management API](/api-details/junction-management-api) is available for [the Scale plan](https://tryvital.io/pricing).
</Info>

<Tip>
  The base URL of this endpoint is `https://api.tryvital.io/management/`.

  The endpoint accepts only [Management Key](/api-details/junction-management-api#authentication) (`X-Management-Key`).
  Team API Key is not accepted.
</Tip>

<RequestExample>
  ```bash cURL
  curl --request POST \
    --url https://api.tryvital.io/management/v1/org/{org_id}/team_data_pull_preferences/{env}/{region} \
    --header 'X-Vital-Org-Key: <api-key>'
    --data '{
      "team_ids": [
          "<uuid>"
      ],
      "providers": {
          "oura": {
              "default": {
                  "historical_days_to_pull": 120
              },
              "resource_overrides": {
                  "sleep": {
                      "historical_days_to_pull": 180
                  }
              }
          }
      }
  }'
  ```
</RequestExample>

<Warning>
  By setting a higher value, you acknowledge your awareness of *the facts of API life* that:

  1. historical pulls may take longer to complete;
  2. historical pulls may run into provider rate limiting; and
  3. regular data polling may consequentially be delayed as a knock-on effect.
</Warning>

<Warning>
  Provider rate limiting typically happens at OAuth application level.

  Therefore, Vital recommends [Bring Your Own OAuth](/wearables/connecting-providers/bring_your_own_oauth)
  if you want to set an extended historical pull range. This creates a rate limit quota dedicated to
  your Vital Team, not being shared with other Vital customers.
</Warning>

<Info>
  The Team Data Pull Preferences you specified is *advisory*. There are scenarios in which Vital systems
  may not adhere strictly to your stated preferences.
</Info>

## Supported Providers

| Provider                                                                     | Default  | Configurable | Remarks                                                                                                                                                                                                                       |
| ---------------------------------------------------------------------------- | -------- | ------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [Abbott LibreView](https://www.libreview.com)                                | 90 days  | ❌            | -                                                                                                                                                                                                                             |
| [Fitbit](https://www.fitbit.com/global/uk/home)                              | 90 days  | ⚠️           | Activity and heartrate timeseries data are fixed to 14 days.                                                                                                                                                                  |
| [Garmin](https://www.garmin.com)                                             | 90 days  | ✅            | -                                                                                                                                                                                                                             |
| [Google Fit](https://www.google.com/fit/)                                    | 90 days  | ✅            | -                                                                                                                                                                                                                             |
| [Oura](https://ouraring.com)                                                 | 180 days | ✅            | -                                                                                                                                                                                                                             |
| [Peloton](https://www.onepeloton.com)                                        | 180 days | ✅            | -                                                                                                                                                                                                                             |
| [Strava](https://www.strava.com)                                             | 14 days  | ✅            | -                                                                                                                                                                                                                             |
| [Wahoo](https://wahoofitness.com)                                            | 180 days | ✅            | -                                                                                                                                                                                                                             |
| [WHOOP](https://www.whoop.com)                                               | 180 days | ✅            | -                                                                                                                                                                                                                             |
| [Zwift](https://zwift.com)                                                   | 270 days | ✅            | -                                                                                                                                                                                                                             |
| [Withings](https://www.withings.com)                                         | 90 days  | ✅            | -                                                                                                                                                                                                                             |
| [8Sleep](https://www.eightsleep.com)                                         | 90 days  | ✅            | -                                                                                                                                                                                                                             |
| [Apple HealthKit](https://www.apple.com/uk/ios/health/) (SDK)                | 30 days  | ✅            | -                                                                                                                                                                                                                             |
| [Android Health Connect](https://developer.android.com/health-connect) (SDK) | 30 days  | ❌            | Google restricts access to historical data to [30 days before the first successful permission request](https://developer.android.com/health-and-fitness/guides/health-connect/develop/frequently-asked-questions#time-range). |
| [Hammerhead](https://www.hammerhead.io)                                      | 30 days  | ✅            | -                                                                                                                                                                                                                             |
| [Dexcom](https://www.dexcom.com)                                             | 30 days  | ✅            | -                                                                                                                                                                                                                             |
| [Dexcom (G6 And Older)](https://www.dexcom.com)                              | 1 day    | ❌            | -                                                                                                                                                                                                                             |
| [MyFitnessPal](https://www.myfitnesspal.com)                                 | 14 days  | ✅            | -                                                                                                                                                                                                                             |
| [Polar](https://www.polar.com/accesslink-api/#polar-accesslink-api)          | 28 days  | ❌            | Polar only supports historical backfill for Sleep and Sleep Stream resources.                                                                                                                                                 |
| [Cronometer](https://www.cronometer.com)                                     | 28 days  | ✅            | -                                                                                                                                                                                                                             |

<Note>
  The configurable maximum is 365 days at this time.
</Note>


# Delete Team ETL Pipelines
Source: https://docs.junction.com/api-reference/org-management/team-etl-pipeline/delete-team-etl-pipelines

delete /v1/org/{org_id}/team_etl_pipelines/{env}/{region}

<Info>
  [Junction Management API](/api-details/junction-management-api) is available for [the Scale plan](https://tryvital.io/pricing).
</Info>

<Tip>
  The base URL of this endpoint is `https://api.tryvital.io/management/`.

  The endpoint accepts only [Management Key](/api-details/junction-management-api#authentication) (`X-Management-Key`).
  Team API Key is not accepted.
</Tip>

<RequestExample>
  ```bash cURL
  curl --request DELETE \
    --url https://api.tryvital.io/management/v1/org/{org_id}/team_etl_pipelines/{env}/{region} \
    --header 'X-Vital-Org-Key: <api-key>'
  ```
</RequestExample>


# Get Team ETL Pipelines
Source: https://docs.junction.com/api-reference/org-management/team-etl-pipeline/get-team-etl-pipelines

get /v1/org/{org_id}/team_etl_pipelines/{env}/{region}

<Info>
  [Junction Management API](/api-details/junction-management-api) is available for [the Scale plan](https://tryvital.io/pricing).
</Info>

<Tip>
  The base URL of this endpoint is `https://api.tryvital.io/management/`.

  The endpoint accepts only [Management Key](/api-details/junction-management-api#authentication) (`X-Management-Key`).
  Team API Key is not accepted.
</Tip>

<RequestExample>
  ```bash cURL
  curl --request GET \
    --url https://api.tryvital.io/management/v1/org/{org_id}/team_etl_pipelines/{env}/{region} \
    --header 'X-Vital-Org-Key: <api-key>'
  ```
</RequestExample>


# Set Team ETL Pipelines
Source: https://docs.junction.com/api-reference/org-management/team-etl-pipeline/upsert-team-etl-pipelines

post /v1/org/{org_id}/team_etl_pipelines/{env}/{region}

<Info>
  [Junction Management API](/api-details/junction-management-api) is available for [the Scale plan](https://tryvital.io/pricing).
</Info>

<Tip>
  The base URL of this endpoint is `https://api.tryvital.io/management/`.

  The endpoint accepts only [Management Key](/api-details/junction-management-api#authentication) (`X-Management-Key`).
  Team API Key is not accepted.
</Tip>

<RequestExample>
  ```bash cURL
  curl --request POST \
    --url https://api.tryvital.io/management/v1/org/{org_id}/team_etl_pipelines/{env}/{region} \
    --header 'Content-Type: application/json' \
    --header 'X-Vital-Org-Key: <api-key>' \
    --data '{
    "team_ids": [
      "3c90c3cc-0d44-4b50-8888-8dd25736052a"
    ],
    "push_historical_data": true,
    "provider_raw_data": true,
    "preferences": {
      "preferred": "cloud_pubsub",
      "enabled": [
        "cloud_pubsub"
      ]
    },
    "cloud_pubsub": {
      "project": "<string>",
      "topic": "<string>",
      "message_ordering": true
    },
    "rabbitmq": {
      "uri": "<string>",
      "exchange": "<string>"
    },
    "svix": {
      "regional": true
    },
    "event_type_prefixes": [
      "<string>"
    ]
  }'
  ```
</RequestExample>


# Get Team Scope Requirements
Source: https://docs.junction.com/api-reference/org-management/team-scope-requirements/get-team-scope-requirements

get /v1/org/{org_id}/team/{team_id}/scope_requirements

<Info>
  [Junction Management API](/api-details/junction-management-api) is available for [the Scale plan](https://tryvital.io/pricing).
</Info>

<Tip>
  The base URL of this endpoint is `https://api.tryvital.io/management/`.

  The endpoint accepts only [Management Key](/api-details/junction-management-api#authentication) (`X-Management-Key`).
  Team API Key is not accepted.
</Tip>

<RequestExample>
  ```bash cURL
  curl --request GET \
    --url https://api.tryvital.io/management/v1/org/{org_id}/team/{team_id}/scope_requirements \
    --header 'X-Vital-Org-Key: <api-key>'
  ```
</RequestExample>


# Set Team Scope Requirements
Source: https://docs.junction.com/api-reference/org-management/team-scope-requirements/upsert-team-scope-requirements

post /v1/org/{org_id}/team/{team_id}/scope_requirements

<Info>
  [Junction Management API](/api-details/junction-management-api) is available for [the Scale plan](https://tryvital.io/pricing).
</Info>

<Tip>
  The base URL of this endpoint is `https://api.tryvital.io/management/`.

  The endpoint accepts only [Management Key](/api-details/junction-management-api#authentication) (`X-Management-Key`).
  Team API Key is not accepted.
</Tip>

<RequestExample>
  ```bash cURL
  curl --request POST \
    --url https://api.tryvital.io/management/v1/org/{org_id}/team/{team_id}/scope_requirements \
    --header 'Content-Type: application/json' \
    --header 'X-Vital-Org-Key: <api-key>' \
    --data '{
     "fitbit": null,
     "oura": {
          "user_must_grant": ["daily"],
          "user_may_grant": ["workout"]
     }
  }'
  ```
</RequestExample>


# Create Webhook
Source: https://docs.junction.com/api-reference/org-management/team-webhook/create

post /v1/org/{org_id}/team/{team_id}/{environment}/webhook

<Info>
  [Junction Management API](/api-details/junction-management-api) is available for [the Scale plan](https://tryvital.io/pricing).
</Info>

<Tip>
  The base URL of this endpoint is `https://api.tryvital.io/management/`.

  The endpoint accepts only [Management Key](/api-details/junction-management-api#authentication) (`X-Management-Key`).
  Team API Key is not accepted.
</Tip>


# Delete Webhook
Source: https://docs.junction.com/api-reference/org-management/team-webhook/delete

delete /v1/org/{org_id}/team/{team_id}/{environment}/webhook/{webhook_id}

<Info>
  [Junction Management API](/api-details/junction-management-api) is available for [the Scale plan](https://tryvital.io/pricing).
</Info>

<Tip>
  The base URL of this endpoint is `https://api.tryvital.io/management/`.

  The endpoint accepts only [Management Key](/api-details/junction-management-api#authentication) (`X-Management-Key`).
  Team API Key is not accepted.
</Tip>


# Get Webhook
Source: https://docs.junction.com/api-reference/org-management/team-webhook/get

get /v1/org/{org_id}/team/{team_id}/{environment}/webhook/{webhook_id}

<Info>
  [Junction Management API](/api-details/junction-management-api) is available for [the Scale plan](https://tryvital.io/pricing).
</Info>

<Tip>
  The base URL of this endpoint is `https://api.tryvital.io/management/`.

  The endpoint accepts only [Management Key](/api-details/junction-management-api#authentication) (`X-Management-Key`).
  Team API Key is not accepted.
</Tip>


# Get Webhook Headers
Source: https://docs.junction.com/api-reference/org-management/team-webhook/get-headers

get /v1/org/{org_id}/team/{team_id}/{environment}/webhook/{webhook_id}/headers

<Info>
  [Junction Management API](/api-details/junction-management-api) is available for [the Scale plan](https://tryvital.io/pricing).
</Info>

<Tip>
  The base URL of this endpoint is `https://api.tryvital.io/management/`.

  The endpoint accepts only [Management Key](/api-details/junction-management-api#authentication) (`X-Management-Key`).
  Team API Key is not accepted.
</Tip>


# Get Webhook Secret
Source: https://docs.junction.com/api-reference/org-management/team-webhook/get-secret

get /v1/org/{org_id}/team/{team_id}/{environment}/webhook/{webhook_id}/secret

<Info>
  [Junction Management API](/api-details/junction-management-api) is available for [the Scale plan](https://tryvital.io/pricing).
</Info>

<Tip>
  The base URL of this endpoint is `https://api.tryvital.io/management/`.

  The endpoint accepts only [Management Key](/api-details/junction-management-api#authentication) (`X-Management-Key`).
  Team API Key is not accepted.
</Tip>


# List Webhooks
Source: https://docs.junction.com/api-reference/org-management/team-webhook/list

get /v1/org/{org_id}/team/{team_id}/{environment}/webhook

<Info>
  [Junction Management API](/api-details/junction-management-api) is available for [the Scale plan](https://tryvital.io/pricing).
</Info>

<Tip>
  The base URL of this endpoint is `https://api.tryvital.io/management/`.

  The endpoint accepts only [Management Key](/api-details/junction-management-api#authentication) (`X-Management-Key`).
  Team API Key is not accepted.
</Tip>


# Patch Webhook
Source: https://docs.junction.com/api-reference/org-management/team-webhook/patch

patch /v1/org/{org_id}/team/{team_id}/{environment}/webhook/{webhook_id}

<Info>
  [Junction Management API](/api-details/junction-management-api) is available for [the Scale plan](https://tryvital.io/pricing).
</Info>

<Tip>
  The base URL of this endpoint is `https://api.tryvital.io/management/`.

  The endpoint accepts only [Management Key](/api-details/junction-management-api#authentication) (`X-Management-Key`).
  Team API Key is not accepted.
</Tip>


# Rotate Webhook Secret
Source: https://docs.junction.com/api-reference/org-management/team-webhook/rotate-secret

post /v1/org/{org_id}/team/{team_id}/{environment}/webhook/{webhook_id}/secret/rotate

<Info>
  [Junction Management API](/api-details/junction-management-api) is available for [the Scale plan](https://tryvital.io/pricing).
</Info>

<Tip>
  The base URL of this endpoint is `https://api.tryvital.io/management/`.

  The endpoint accepts only [Management Key](/api-details/junction-management-api#authentication) (`X-Management-Key`).
  Team API Key is not accepted.
</Tip>


# Update Webhook Headers
Source: https://docs.junction.com/api-reference/org-management/team-webhook/update-headers

put /v1/org/{org_id}/team/{team_id}/{environment}/webhook/{webhook_id}/headers

<Info>
  [Junction Management API](/api-details/junction-management-api) is available for [the Scale plan](https://tryvital.io/pricing).
</Info>

<Tip>
  The base URL of this endpoint is `https://api.tryvital.io/management/`.

  The endpoint accepts only [Management Key](/api-details/junction-management-api#authentication) (`X-Management-Key`).
  Team API Key is not accepted.
</Tip>


# Create Team
Source: https://docs.junction.com/api-reference/org-management/team/create-team

post /v1/org/{org_id}/team

<Info>
  [Junction Management API](/api-details/junction-management-api) is available for [the Scale plan](https://tryvital.io/pricing).
</Info>

<Tip>
  The base URL of this endpoint is `https://api.tryvital.io/management/`.

  The endpoint accepts only [Management Key](/api-details/junction-management-api#authentication) (`X-Management-Key`).
  Team API Key is not accepted.
</Tip>

<RequestExample>
  ```bash cURL
  curl --request POST \
    --url https://api.tryvital.io/management/v1/org/{org_id}/team \
    --header 'Content-Type: application/json' \
    --header 'X-Vital-Org-Key: <api-key>' \
    --data '{
    "name": "<string>",
    "region": "us",
    "lab_tests_patient_sms_communication_enabled": true,
    "lab_tests_patient_email_communication_enabled": true,
    "event_type_prefixes": [
      "<string>"
    ]
  }'
  ```
</RequestExample>


# Delete Team
Source: https://docs.junction.com/api-reference/org-management/team/delete-team

delete /v1/org/{org_id}/team/{team_id}

<Info>
  [Junction Management API](/api-details/junction-management-api) is available for [the Scale plan](https://tryvital.io/pricing).
</Info>

<Tip>
  The base URL of this endpoint is `https://api.tryvital.io/management/`.

  The endpoint accepts only [Management Key](/api-details/junction-management-api#authentication) (`X-Management-Key`).
  Team API Key is not accepted.
</Tip>

<RequestExample>
  ```bash cURL
  curl --request DELETE \
    --url https://api.tryvital.io/management/v1/org/{org_id}/team/{team_id} \
    --header 'X-Vital-Org-Key: <api-key>'
  ```
</RequestExample>


# Get Team
Source: https://docs.junction.com/api-reference/org-management/team/get-team

get /v1/org/{org_id}/team/{team_id}

<Info>
  [Junction Management API](/api-details/junction-management-api) is available for [the Scale plan](https://tryvital.io/pricing).
</Info>

<Tip>
  The base URL of this endpoint is `https://api.tryvital.io/management/`.

  The endpoint accepts only [Management Key](/api-details/junction-management-api#authentication) (`X-Management-Key`).
  Team API Key is not accepted.
</Tip>

<RequestExample>
  ```bash cURL
  curl --request GET \
    --url https://api.tryvital.io/management/v1/org/{org_id}/team/{team_id} \
    --header 'X-Vital-Org-Key: <api-key>'
  ```
</RequestExample>


# List Teams
Source: https://docs.junction.com/api-reference/org-management/team/list-teams

get /v1/org/{org_id}/team

<Info>
  [Junction Management API](/api-details/junction-management-api) is available for [the Scale plan](https://tryvital.io/pricing).
</Info>

<Tip>
  The base URL of this endpoint is `https://api.tryvital.io/management/`.

  The endpoint accepts only [Management Key](/api-details/junction-management-api#authentication) (`X-Management-Key`).
  Team API Key is not accepted.
</Tip>

<RequestExample>
  ```bash cURL
  curl --request GET \
    --url https://api.tryvital.io/management/v1/org/{org_id}/team \
    --header 'X-Vital-Org-Key: <api-key>'
  ```
</RequestExample>


# Update Team
Source: https://docs.junction.com/api-reference/org-management/team/update-team

patch /v1/org/{org_id}/team/{team_id}

<Info>
  [Junction Management API](/api-details/junction-management-api) is available for [the Scale plan](https://tryvital.io/pricing).
</Info>

<Tip>
  The base URL of this endpoint is `https://api.tryvital.io/management/`.

  The endpoint accepts only [Management Key](/api-details/junction-management-api#authentication) (`X-Management-Key`).
  Team API Key is not accepted.
</Tip>

<RequestExample>
  ```bash cURL
  curl --request PATCH \
    --url https://api.tryvital.io/management/v1/org/{org_id}/team/{team_id} \
    --header 'Content-Type: application/json' \
    --header 'X-Vital-Org-Key: <api-key>' \
    --data '{
    "name": "<string>",
    "sandbox": {
      "lab_tests_patient_sms_communication_enabled": true,
      "lab_tests_patient_email_communication_enabled": true,
      "event_type_prefixes": [
        "<string>"
      ]
    },
    "production": {
      "lab_tests_patient_sms_communication_enabled": true,
      "lab_tests_patient_email_communication_enabled": true,
      "event_type_prefixes": [
        "<string>"
      ]
    }
  }'
  ```
</RequestExample>


# List of Providers
Source: https://docs.junction.com/api-reference/providers

GET /v2/providers
Get Provider list

<RequestExample>
  ```bash cURL
  curl --request GET \
       --url https://api.tryvital.io/v2/providers/ \
       --header 'Accept: application/json'
       --header 'x-vital-api-key: <API_KEY>' \
  '
  ```

  ```javascript Node
  import { VitalClient, VitalEnvironment } from '@tryvital/vital-node';

  const client = new VitalClient({
      apiKey: '<my_api_key>',
      environment: VitalEnvironment.Sandbox,
  });

  const data = await client.providers.getAll();
  ```

  ```python Python
  from vital.client import Vital
  from vital.environment import VitalEnvironment

  client = Vital(
    api_key="YOUR_API_KEY",
    environment=VitalEnvironment.SANDBOX
  )

  data = client.providers.get_all()
  ```

  ```java Java
  import com.vital.api.Vital;
  import com.vital.api.core.Environment;

  Vital vital = Vital.builder()
          .apiKey("YOUR_API_KEY")
          .environment(Environment.SANDBOX)
          .build();

  var data = vital.providers().getAll();
  ```

  ```go Go
  import (
    "context"

    vital "github.com/tryVital/vital-go"
    vitalclient "github.com/tryVital/vital-go/client"
    "github.com/tryVital/vital-go/option"
  )

  client := vitalclient.NewClient(
    option.WithApiKey("<YOUR_API_KEY>"),
    option.WithBaseURL(vital.Environments.Sandbox),
  )

  response, err := client.Providers.GetAll(context.TODO())
  if err != nil {
    return err
  }
  fmt.Printf("Received data %s\n", response)
  ```
</RequestExample>


# Create Insurance
Source: https://docs.junction.com/api-reference/user/create-insurance-beta

POST /v2/user/{user_id}/insurance

If insurance is covered by Medicare or Medicaid, we have closed beta support for inferring the plan to use based on a patient's address. This endpoint supports `payor_code`s with values of `MEDFED` (Medicare) and
`MAIDFED` (Medicaid) to do this.

For example, supplying a `payor_code` of `MEDFED` for a patient that lives in Arizona will create insurance data using Arizona's Medicare plan payor code.

<RequestExample>
  ```bash cURL
  curl --request POST \
       --url {{BASE_URL}}/v2/user/{user_id}/insurance \
       --header 'Accept: application/json' \
       --header 'x-vital-api-key: <API_KEY>' \
       --header 'Content-Type: application/json' \
       --data '
  {
    "payor_code": "UNITE",
    "member_id": "test",
    "group_id": "123",
    "relationship": "Self",
    "insured": {
      "first_name": "John",
      "last_name": "Doe", 
      "email": "john@email.com", 
      "phone_number":"+1123123123",
      "gender": "Male", 
      "dob": "1999-01-01", 
      "address": {
        "first_line": "Some Street", 
        "second_line": null,
        "zip_code": "85004",
        "state": "AZ",
        "city": "Phoenix",
      }
    }
  }
  '
  ```
</RequestExample>


# Create Sign-In Token
Source: https://docs.junction.com/api-reference/user/create-sign-in-token

POST /v2/user/{user_id}/sign_in_token

Create a [Vital Sign-In Token](/wearables/sdks/authentication#vital-sign-in-token) for your mobile apps to
sign in with [Vital Mobile SDKs](/wearables/sdks/authentication).

<Info>
  Avoid requesting Vital Sign-In Token every time your mobile app relaunches.
  Your mobile app only needs to sign-in once with the Vital Mobile SDK. A signed-in session is persistent on device.
</Info>

<RequestExample>
  ```cURL
  curl --request POST \
       --url {{BASE_URL}}/v2/user/{{USER_ID}}/sign_in_token \
       --header 'Accept: application/json' \
       --header 'x-vital-api-key: <API_KEY>' \
       --header 'Content-Type: application/json' \
  ```

  ```python Python
  import { VitalClient, VitalEnvironment } from '@tryvital/vital-node';

  const client = new VitalClient({
      apiKey: '<my_api_key>',
      environment: VitalEnvironment.Sandbox,
  });

  const data = await client.user.get_user_sign_in_token(
      '<user_id>'
  );
  ```

  ```javascript Node
  from vital.client import Vital
  from vital.environment import VitalEnvironment

  client = Vital(
    api_key="YOUR_API_KEY",
    environment=VitalEnvironment.SANDBOX
  )

  data = client.user.getUserSignInToken(
      user_id="<user_id>"
  );
  ```

  ```java Java
  import com.vital.api.Vital;
  import com.vital.api.core.Environment;

  Vital vital = Vital.builder()
          .apiKey("YOUR_API_KEY")
          .environment(Environment.SANDBOX)
          .build();

  var data = vital.user().getUserSignInToken("<user_id>");
  ```

  ```go Go
  import (
    "context"

    vital "github.com/tryVital/vital-go"
    vitalclient "github.com/tryVital/vital-go/client"
    "github.com/tryVital/vital-go/option"
  )

  client := vitalclient.NewClient(
    option.WithApiKey("<YOUR_API_KEY>"),
    option.WithBaseURL(vital.Environments.Sandbox),
  )

  response, err := client.User.GetUserSignInToken(context.TODO(), "<user_id>")
  if err != nil {
    return err
  }
  fmt.Printf("Received data %s\n", response)
  ```
</RequestExample>


# Create User
Source: https://docs.junction.com/api-reference/user/create-user

POST /v2/user
POST Create a Vital user given a client_user_id and returns the user_id.

<Note>
  When the supplied `client_user_id` conflicts with an existing user, the 400 Bad Request error response
  includes the Vital User ID (`user_id`) and the creation date (`created_on`) of the conflicting user.
</Note>

<RequestExample>
  ```bash cURL
  curl --request POST \
       --url {{BASE_URL}}/v2/user/ \
       --header 'Accept: application/json' \
       --header 'x-vital-api-key: <API_KEY>' \
       --header 'Content-Type: application/json' \
       --data '
  {
       "client_user_id": "your_unique_id"
  }
  '
  ```

  ```javascript Node
  import { VitalClient, VitalEnvironment } from '@tryvital/vital-node';

  const client = new VitalClient({
      apiKey: '<my_api_key>',
      environment: VitalEnvironment.Sandbox,
  });

  const data = await client.user.create(
      '<client_user_id>'
  );
  ```

  ```python Python
  from vital.client import Vital
  from vital.environment import VitalEnvironment

  client = Vital(
    api_key="YOUR_API_KEY",
    environment=VitalEnvironment.SANDBOX
  )

  data = client.user.create(
      client_user_id="<client_user_id>"
  )
  ```

  ```java Java
  import com.vital.api.Vital;
  import com.vital.api.core.Environment;

  Vital vital = Vital.builder()
          .apiKey("YOUR_API_KEY")
          .environment(Environment.SANDBOX)
          .build();

  var data = vital.user().create("<client_user_id>");
  ```

  ```go Go
  import (
    "context"

    vital "github.com/tryVital/vital-go"
    vitalclient "github.com/tryVital/vital-go/client"
    "github.com/tryVital/vital-go/option"
  )

  client := vitalclient.NewClient(
    option.WithApiKey("<YOUR_API_KEY>"),
    option.WithBaseURL(vital.Environments.Sandbox),
  )

  response, err := client.User.Create(context.TODO(), "<client_user_id>")
  if err != nil {
    return err
  }
  fmt.Printf("Received data %s\n", response)
  ```
</RequestExample>


# Delete User
Source: https://docs.junction.com/api-reference/user/delete-user

DELETE /v2/user/{user_id}

Deleting a user would also [deregister their all provider connections](/api-reference/user/deregister-a-provider) immediately.
Vital erases the user data after a 7-day grace period.

<Info>
  If you wish to undo a user deletion for any reason, you can undo the deletion through the
  [Undo User Deletion](/api-reference/user/undo-delete-user) API. Note that undoing would not
  restore any provider connections.
</Info>

<RequestExample>
  ```bash cURL
  curl --request DELETE \
       --url {{BASE_URL}}/v2/user/{user_id} \
       --header 'x-vital-api-key: <API_KEY>' \
       --header 'Accept: application/json'
  ```

  ```javascript Node
  import { VitalClient, VitalEnvironment } from '@tryvital/vital-node';

  const client = new VitalClient({
      apiKey: '<my_api_key>',
      environment: VitalEnvironment.Sandbox,
  });

  const data = await client.user.delete(
      '<user_id>'
  );
  ```

  ```python Python
  from vital.client import Vital
  from vital.environment import VitalEnvironment

  client = Vital(
    api_key="YOUR_API_KEY",
    environment=VitalEnvironment.SANDBOX
  )

  data = client.user.delete(
      user_id="<user_id>"
  )
  ```

  ```java Java
  import com.vital.api.Vital;
  import com.vital.api.core.Environment;

  Vital vital = Vital.builder()
          .apiKey("YOUR_API_KEY")
          .environment(Environment.SANDBOX)
          .build();

  var data = vital.user().delete("<user_id>");
  ```

  ```go Go
  import (
    "context"

    vital "github.com/tryVital/vital-go"
    vitalclient "github.com/tryVital/vital-go/client"
    "github.com/tryVital/vital-go/option"
  )

  client := vitalclient.NewClient(
    option.WithApiKey("<YOUR_API_KEY>"),
    option.WithBaseURL(vital.Environments.Sandbox),
  )

  response, err := client.User.Delete(context.TODO(), "<user_id>")
  if err != nil {
    return err
  }
  fmt.Printf("Received data %s\n", response)
  ```
</RequestExample>


# Deregister Connection
Source: https://docs.junction.com/api-reference/user/deregister-a-provider

DELETE /v2/user/{user_id}/{provider}

<Note>
  Deregistration has well-defined behaviour only on [cloud-based providers](/wearables/providers/introduction#cloud-based-providers).
</Note>

<Warning>
  While you can call this endpoint against these [SDK-based providers](/wearables/providers/introduction#sdk-based-providers),
  Vital Mobile SDK would automatically "reconnect" on the next data sync attempt.

  We do not have a "disconnect" mechanism for SDK-based providers at this time.

  You can pause [Health SDK data sync](/wearables/sdks/vital-health#pausing-data-synchronization) client-side, or
  [sign-out the user](/wearables/sdks/vital-core#reset-the-sdk-sign-out) from the SDK.
</Warning>

<RequestExample>
  ```bash cURL
  curl --request DELETE \
       --url {{BASE_URL}}/v2/user/{user_id}/{provider} \
       --header 'Accept: application/json' \
       --header 'x-vital-api-key: <API_KEY>'
  ```

  ```javascript Node
  import { VitalClient, VitalEnvironment } from '@tryvital/vital-node';

  const client = new VitalClient({
      apiKey: '<my_api_key>',
      environment: VitalEnvironment.Sandbox,
  });

  const data = await client.user.deregisterProvider(
      '<user_id>',
      '<provider>'
  );
  ```

  ```python Python
  from vital.client import Vital
  from vital.environment import VitalEnvironment

  client = Vital(
    api_key="YOUR_API_KEY",
    environment=VitalEnvironment.SANDBOX
  )

  data = client.user.deregister_provider(
      user_id="<user_id>",
      provider="<provider>"
  );
  ```

  ```java Java
  import com.vital.api.Vital;
  import com.vital.api.core.Environment;

  Vital vital = Vital.builder()
          .apiKey("YOUR_API_KEY")
          .environment(Environment.SANDBOX)
          .build();

  var data = vital.user().deregisterProvider(
    "<user_id>",
    "<provider>"
  );
  ```

  ```go Go
  import (
    "context"

    vital "github.com/tryVital/vital-go"
    vitalclient "github.com/tryVital/vital-go/client"
    "github.com/tryVital/vital-go/option"
  )

  client := vitalclient.NewClient(
    option.WithApiKey("<YOUR_API_KEY>"),
    option.WithBaseURL(vital.Environments.Sandbox),
  )

  response, err := client.User.DeregisterProvider(
    context.TODO(), 
    "<user_id>",
    "<provider_id>",
  )

  if err != nil {
    return err
  }
  fmt.Printf("Received data %s\n", response)
  ```
</RequestExample>


# Get User Demographcis
Source: https://docs.junction.com/api-reference/user/get-info-latest

GET /v2/user/{user_id}/info/latest

<Card horizontal icon="person-digging" color="#57164A">
  This feature is in **closed beta**.

  Interested in this feature? Get in touch with your Customer Success Manager.
</Card>

<RequestExample>
  ```bash cURL
  curl --request GET \
       --url {{BASE_URL}}/v2/user/{user_id}/info/latest \
       --header 'Accept: application/json' \
       --header 'x-vital-api-key: <API_KEY>' \
       --header 'Content-Type: application/json' \
  ```

  ```javascript Node
  import { VitalClient, VitalEnvironment } from '@tryvital/vital-node';

  const client = new VitalClient({
      apiKey: '<my_api_key>',
      environment: VitalEnvironment.Sandbox,
  });

  const data = await client.user.get_latest_user_info(
      '<user_id>'
  );
  ```

  ```python Python
  from vital.client import Vital
  from vital.environment import VitalEnvironment

  client = Vital(
    api_key="YOUR_API_KEY",
    environment=VitalEnvironment.SANDBOX
  )

  data = client.user.get_latest_user_info(
      user_id="<user_id>"
  )
  ```

  ```java Java
  import com.vital.api.Vital;
  import com.vital.api.core.Environment;

  Vital vital = Vital.builder()
          .apiKey("YOUR_API_KEY")
          .environment(Environment.SANDBOX)
          .build();

  var data = vital.user().getLatestUserInfo("<user_id>");
  ```

  ```go Go
  import (
    "context"

    vital "github.com/tryVital/vital-go"
    vitalclient "github.com/tryVital/vital-go/client"
    "github.com/tryVital/vital-go/option"
  )

  client := vitalclient.NewClient(
    option.WithApiKey("<YOUR_API_KEY>"),
    option.WithBaseURL(vital.Environments.Sandbox),
  )

  response, err := client.User.GetLatestUserInfo(context.TODO(), "<user_id>")
  if err != nil {
    return err
  }
  fmt.Printf("Received data %s\n", response)
  ```
</RequestExample>

<ResponseExample>
  ```json Response
  {
    "first_name": "John",
    "last_name": "Doe", 
    "email": "john@email.com", 
    "phone_number":"+1123123123",
    "gender": "Male", 
    "dob": "1999-01-01", 
    "address": {
  	  "first_line": "Some Street", 
  	  "second_line": null,
      "zip_code": "85004",
      "state": "AZ",
      "city": "Phoenix",
    }
  }
  ```
</ResponseExample>


# Get Latest Insurance
Source: https://docs.junction.com/api-reference/user/get-latest-insurance

GET /v2/user/{user_id}/insurance/latest

<Card horizontal icon="person-digging" color="#57164A">
  This feature is in **closed beta**.

  Interested in this feature? Get in touch with your Customer Success Manager.
</Card>

<RequestExample>
  ```bash cURL
  curl --request GET \
       --url {{BASE_URL}}/v2/user/{user_id}/insurance/latest \
       --header 'Accept: application/json' \
       --header 'x-vital-api-key: <API_KEY>' \
       --header 'Content-Type: application/json' \
  ```
</RequestExample>

<ResponseExample>
  ```json Response
  {
    "payor_code": "UNITE",
    "member_id": "test",
    "group_id": "123",
    "relationship": "Self",
    "insured": {
      "first_name": "John",
      "last_name": "Doe", 
      "email": "john@email.com", 
      "phone_number":"+1123123123",
      "gender": "Male", 
      "dob": "1999-01-01", 
      "address": {
        "first_line": "Some Street", 
        "second_line": null,
        "zip_code": "85004",
        "state": "AZ",
        "city": "Phoenix",
      }
    }
  }
  ```
</ResponseExample>


# Get User
Source: https://docs.junction.com/api-reference/user/get-user

GET /v2/user/{user_id}
GET User details given the user_id.

<RequestExample>
  ```bash cURL
  curl --request GET \
       --url {{BASE_URL}}/v2/user/{user_id} \
       --header 'x-vital-api-key: <API_KEY>' \
       --header 'Accept: application/json'
  ```

  ```javascript Node
  import { VitalClient, VitalEnvironment } from '@tryvital/vital-node';

  const client = new VitalClient({
      apiKey: '<my_api_key>',
      environment: VitalEnvironment.Sandbox,
  });

  const data = await client.user.get(
      '<user_id>'
  );
  ```

  ```python Python
  from vital.client import Vital
  from vital.environment import VitalEnvironment

  client = Vital(
    api_key="YOUR_API_KEY",
    environment=VitalEnvironment.SANDBOX
  )

  data = client.user.get(
      user_id="<user_id>"
  )
  ```

  ```java Java
  import com.vital.api.Vital;
  import com.vital.api.core.Environment;

  Vital vital = Vital.builder()
          .apiKey("YOUR_API_KEY")
          .environment(Environment.SANDBOX)
          .build();

  var data = vital.user().get("<user_id>");
  ```

  ```go Go
  import (
    "context"

    vital "github.com/tryVital/vital-go"
    vitalclient "github.com/tryVital/vital-go/client"
    "github.com/tryVital/vital-go/option"
  )

  client := vitalclient.NewClient(
    option.WithApiKey("<YOUR_API_KEY>"),
    option.WithBaseURL(vital.Environments.Sandbox),
  )

  response, err := client.User.Get(context.TODO(), "<user_id>")
  if err != nil {
    return err
  }
  fmt.Printf("Received data %s\n", response)
  ```
</RequestExample>


# Get Teams Users
Source: https://docs.junction.com/api-reference/user/get-users

GET /v2/user
GET All users for team.

<RequestExample>
  ```bash cURL
  curl --request GET \
       --url {{BASE_URL}}/v2/user/ \
       --header 'Accept: application/json' \
       --header 'x-vital-api-key: <API_KEY>'
  ```

  ```javascript Node
  import { VitalClient, VitalEnvironment } from '@tryvital/vital-node';

  const client = new VitalClient({
      apiKey: '<my_api_key>',
      environment: VitalEnvironment.Sandbox,
  });

  const data = await client.user.getAll();
  ```

  ```python Python
  from vital.client import Vital
  from vital.environment import VitalEnvironment

  client = Vital(
    api_key="YOUR_API_KEY",
    environment=VitalEnvironment.SANDBOX
  )

  data = client.user.get_all()
  ```

  ```java Java
  import com.vital.api.Vital;
  import com.vital.api.core.Environment;

  Vital vital = Vital.builder()
          .apiKey("YOUR_API_KEY")
          .environment(Environment.SANDBOX)
          .build();

  var data = vital.user().getAll();
  ```

  ```go Go
  import (
    "context"

    vital "github.com/tryVital/vital-go"
    vitalclient "github.com/tryVital/vital-go/client"
    "github.com/tryVital/vital-go/option"
  )

  client := vitalclient.NewClient(
    option.WithApiKey("<YOUR_API_KEY>"),
    option.WithBaseURL(vital.Environments.Sandbox),
  )

  response, err := client.User.GetAll(context.TODO(), nil)
  if err != nil {
    return err
  }
  fmt.Printf("Received data %s\n", response)
  ```
</RequestExample>


# Get User Connections
Source: https://docs.junction.com/api-reference/user/get-users-connected-providers

GET /v2/user/providers/{user_id}
GET Users connected providers

<RequestExample>
  ```bash cURL
  curl --request GET \
       --url {{BASE_URL}}/v2/user/providers/{user_id} \
       --header 'Accept: application/json' \
       --header 'x-vital-api-key: API_KEY'
  ```

  ```javascript Node
  import { VitalClient, VitalEnvironment } from '@tryvital/vital-node';

  const client = new VitalClient({
      apiKey: '<my_api_key>',
      environment: VitalEnvironment.Sandbox,
  });

  const data = await client.user.getConnectedProviders("<user_id>");
  ```

  ```python Python
  from vital.client import Vital
  from vital.environment import VitalEnvironment

  client = Vital(
    api_key="YOUR_API_KEY",
    environment=VitalEnvironment.SANDBOX
  )

  data = client.user.get_connected_providers("<user_id>")
  ```

  ```java Java
  import com.vital.api.Vital;
  import com.vital.api.core.Environment;

  Vital vital = Vital.builder()
          .apiKey("YOUR_API_KEY")
          .environment(Environment.SANDBOX)
          .build();

  var data = vital.user().getConnectedProviders("<user_id>");
  ```

  ```go Go
  import (
    "context"

    vital "github.com/tryVital/vital-go"
    vitalclient "github.com/tryVital/vital-go/client"
    "github.com/tryVital/vital-go/option"
  )

  client := vitalclient.NewClient(
    option.WithApiKey("<YOUR_API_KEY>"),
    option.WithBaseURL(vital.Environments.Sandbox),
  )

  response, err := client.User.GetConnectedProviders(context.TODO(), "<user_id>")
  if err != nil {
    return err
  }
  fmt.Printf("Received data %s\n", response)
  ```
</RequestExample>

<ResponseExample>
  ```json Response
  {
      "providers": [
          {
              "name": "Fitbit",
              "slug": "fitbit",
              "logo": "https://example.com/fitbit.png",
              "status": "connected",
              "created_on": "2010-01-23T12:34:56+00:00",
              "resource_availability": {
                  "body": {
                      "status": "available",
                      "scope_requirements": {
                          "user_granted": {
                              "required": [
                                  "weight"
                              ],
                              "optional": []
                          },
                          "user_denied": {
                              "required": [],
                              "optional": []
                          }
                      }
                  },
                  "sleep": {
                      "status": "unavailable",
                      "scope_requirements": {
                          "user_granted": {
                              "required": [],
                              "optional": []
                          },
                          "user_denied": {
                              "required": [
                                  "sleep"
                              ],
                              "optional": [
                                  "heartrate",
                                  "oxygen_saturation",
                                  "respiratory_rate"
                              ]
                          }
                      }
                  }
              },
              "error_details": null
          }
      ]
  }
  ```
</ResponseExample>


# Patch User
Source: https://docs.junction.com/api-reference/user/patch-user

PATCH /v2/user/{user_id}

<RequestExample>
  ```bash cURL
  curl --request POST \
       --url {{BASE_URL}}/v2/user/ \
       --header 'Accept: application/json' \
       --header 'x-vital-api-key: <API_KEY>' \
       --header 'Content-Type: application/json' \
       --data '
  {
       "fallback_time_zone": "Europe/London",
       "fallback_birth_date" "1980-03-13"
  }
  '
  ```

  ```javascript Node
  import { VitalClient, VitalEnvironment } from '@tryvital/vital-node';

  const client = new VitalClient({
      apiKey: '<my_api_key>',
      environment: VitalEnvironment.Sandbox,
  });

  const data = await client.user.patch(
      '<user_id>'
  );
  ```

  ```python Python
  from vital.client import Vital
  from vital.environment import VitalEnvironment

  client = Vital(
    api_key="YOUR_API_KEY",
    environment=VitalEnvironment.SANDBOX
  )

  data = client.user.patch(
      user_id="<user_id>"
  )
  ```

  ```java Java
  import com.vital.api.Vital;
  import com.vital.api.core.Environment;

  Vital vital = Vital.builder()
          .apiKey("YOUR_API_KEY")
          .environment(Environment.SANDBOX)
          .build();

  var data = vital.user().patch("<user_id>");
  ```

  ```go Go
  import (
    "context"

    vital "github.com/tryVital/vital-go"
    vitalclient "github.com/tryVital/vital-go/client"
    "github.com/tryVital/vital-go/option"
  )

  client := vitalclient.NewClient(
    option.WithApiKey("<YOUR_API_KEY>"),
    option.WithBaseURL(vital.Environments.Sandbox),
  )

  response, err := client.User.Patch(context.TODO(), "<user_id>")
  if err != nil {
    return err
  }
  fmt.Printf("Received data %s\n", response)
  ```
</RequestExample>


# Refresh User Data
Source: https://docs.junction.com/api-reference/user/refresh-user-data

POST /v2/user/refresh/{user_id}
Trigger a manual refresh for a specific user

<RequestExample>
  ```bash cURL
  curl --request POST \
       --url {{BASE_URL}}/v2/user/refresh/{user_id} \
       --header 'Accept: application/json' \
       --header 'x-vital-api-key: <API_KEY>'
  ```

  ```javascript Node
  import { VitalClient, VitalEnvironment } from '@tryvital/vital-node';

  const client = new VitalClient({
      apiKey: '<my_api_key>',
      environment: VitalEnvironment.Sandbox,
  });

  const data = await client.user.refresh(
      '<user_id>'
  );
  ```

  ```python Python
  from vital.client import Vital
  from vital.environment import VitalEnvironment

  client = Vital(
    api_key="YOUR_API_KEY",
    environment=VitalEnvironment.SANDBOX
  )

  data = client.user.refresh(
      user_id="<user_id>"
  )
  ```

  ```java Java
  import com.vital.api.Vital;
  import com.vital.api.core.Environment;

  Vital vital = Vital.builder()
          .apiKey("YOUR_API_KEY")
          .environment(Environment.SANDBOX)
          .build();

  var data = vital.user().refresh("<user_id>");
  ```

  ```go Go
  import (
    "context"

    vital "github.com/tryVital/vital-go"
    vitalclient "github.com/tryVital/vital-go/client"
    "github.com/tryVital/vital-go/option"
  )

  client := vitalclient.NewClient(
    option.WithApiKey("<YOUR_API_KEY>"),
    option.WithBaseURL(vital.Environments.Sandbox),
  )

  response, err := client.User.Refresh(context.TODO(), "<user_id>")
  if err != nil {
    return err
  }
  fmt.Printf("Received data %s\n", response)
  ```
</RequestExample>


# Get User by Client User ID
Source: https://docs.junction.com/api-reference/user/resolve-user

GET /v2/user/resolve/{client_user_id}
Get User by their `client_user_id`.

<RequestExample>
  ```bash cURL
  curl --request GET \
       --url {{BASE_URL}}/v2/user/resolve/{client_user_id} \
       --header 'x-vital-api-key: <API_KEY>' \
       --header 'Accept: application/json'
  ```

  ```javascript Node
  import { VitalClient, VitalEnvironment } from '@tryvital/vital-node';

  const client = new VitalClient({
      apiKey: '<my_api_key>',
      environment: VitalEnvironment.Sandbox,
  });

  const data = await client.user.getByClientUserId(
      '<client_user_id>'
  );
  ```

  ```python Python
  from vital.client import Vital
  from vital.environment import VitalEnvironment

  client = Vital(
    api_key="YOUR_API_KEY",
    environment=VitalEnvironment.SANDBOX
  )

  data = client.user.get_by_client_user_id(
      client_user_id="<client_user_id>"
  )
  ```

  ```java Java
  import com.vital.api.Vital;
  import com.vital.api.core.Environment;

  Vital vital = Vital.builder()
          .apiKey("YOUR_API_KEY")
          .environment(Environment.SANDBOX)
          .build();

  var data = vital.user().getByClientUserId("<client_user_id>");
  ```

  ```go Go
  import (
    "context"

    vital "github.com/tryVital/vital-go"
    vitalclient "github.com/tryVital/vital-go/client"
    "github.com/tryVital/vital-go/option"
  )

  client := vitalclient.NewClient(
    option.WithApiKey("<YOUR_API_KEY>"),
    option.WithBaseURL(vital.Environments.Sandbox),
  )

  response, err := client.User.GetByClientUserId(context.TODO(), "<client_user_id>")
  if err != nil {
    return err
  }
  fmt.Printf("Received data %s\n", response)
  ```
</RequestExample>


# Undo User Deletion
Source: https://docs.junction.com/api-reference/user/undo-delete-user

POST /v2/user/undo_delete

You can undo any [user deletion](/api-reference/user/delete-user) that is still in their 7-day
grace period.

<Note>
  Undoing a deletion does not restore any provider connections.
</Note>

<Warning>
  You cannot undo a deletion if you have already [created a new user](/api-reference/user/create-user) using
  the same `client_user_id`.
</Warning>

<RequestExample>
  ```bash cURL
  curl --request DELETE \
       --url {{BASE_URL}}/v2/user/undo_delete \
       --header 'x-vital-api-key: <API_KEY>' \
       --header 'Accept: application/json' \
       --header 'Content-Type: application/json' \
       --data '
  {
       "client_user_id": "8DS6YRVBCSQQ4S0",
  }
  '
  ```

  ```javascript Node
  import { VitalClient, VitalEnvironment } from '@tryvital/vital-node';

  const client = new VitalClient({
      apiKey: '<my_api_key>',
      environment: VitalEnvironment.Sandbox,
  });

  const data = await client.user.undoDelete({
      clientUserId: '8DS6YRVBCSQQ4S0',
  });
  ```

  ```python Python
  from vital.client import Vital
  from vital.environment import VitalEnvironment

  client = Vital(
    api_key="YOUR_API_KEY",
    environment=VitalEnvironment.SANDBOX
  )

  data = client.user.undo_delete(
      client_user_id="8DS6YRVBCSQQ4S0"
  )
  ```

  ```java Java
  import com.vital.api.Vital;
  import com.vital.api.core.Environment;
  import com.vital.api.resources.user.requests.UserUndoDeleteRequest;

  Vital vital = Vital.builder()
          .apiKey("YOUR_API_KEY")
          .environment(Environment.SANDBOX)
          .build();

  UserUndoDeleteRequest request = UserUndoDeleteRequest.builder()
          .clientUserId("8DS6YRVBCSQQ4S0")
          .build();

  var data = vital.user().undoDelete(request);
  ```

  ```go Go
  import (
    "context"

    vital "github.com/tryVital/vital-go"
    vitalclient "github.com/tryVital/vital-go/client"
    "github.com/tryVital/vital-go/option"
  )

  client := vitalclient.NewClient(
    option.WithApiKey("<YOUR_API_KEY>"),
    option.WithBaseURL(vital.Environments.Sandbox),
  )

  request = &vital.UserUndoDeleteRequest{
    ClientUserId: "8DS6YRVBCSQQ4S0",
  }
  response, err := client.User.UndoDelete(context.TODO(), request)
  if err != nil {
    return err
  }
  fmt.Printf("Received data %s\n", response)
  ```
</RequestExample>


# Create User Demographics
Source: https://docs.junction.com/api-reference/user/upsert-info

PATCH /v2/user/{user_id}/info

<Card horizontal icon="person-digging" color="#57164A">
  This feature is in **closed beta**.

  Interested in this feature? Get in touch with your Customer Success Manager.
</Card>

<RequestExample>
  ```bash cURL
  curl --request PATCH \
       --url {{BASE_URL}}/v2/user/{user_id}/info \
       --header 'Accept: application/json' \
       --header 'x-vital-api-key: <API_KEY>' \
       --header 'Content-Type: application/json' \
       --data '
  {
    "first_name": "John",
    "last_name": "Doe", 
    "email": "john@email.com", 
    "phone_number":"+1123123123",
    "gender": "Male", 
    "dob": "1999-01-01", 
    "address": {
  	  "first_line": "Some Street", 
  	  "second_line": null,
      "zip_code": "85004",
      "state": "AZ",
      "city": "Phoenix",
    }
  }
  '
  ```
</RequestExample>

<ResponseExample>
  ```json Response
  {
    "first_name": "John",
    "last_name": "Doe", 
    "email": "john@email.com", 
    "phone_number":"+1123123123",
    "gender": "Male", 
    "dob": "1999-01-01", 
    "address": {
  	  "first_line": "Some Street", 
  	  "second_line": null,
      "zip_code": "85004",
      "state": "AZ",
      "city": "Phoenix",
    }
  }
  ```
</ResponseExample>


# API
Source: https://docs.junction.com/changelog/core/api


### Lab Test Result Interpretation Filtering (June 2025)

You can now filter lab test orders by result interpretation using the new `interpretation` query parameter in the [GET /orders](/api-reference/lab/orders/get-orders) endpoint.

<Accordion icon="filter" iconType="duotone" title="Details" defaultOpen>
  The new filtering capability allows you to query orders based on their clinical interpretation:

  **Query Parameter:**

  * **`interpretation`** - Filter by result interpretation of the lab test
    * Type: `enum<string> | null`
    * Available options: `normal`, `abnormal`, `critical`
    * Note: This enum is non-exhaustive

  **Response Enhancement:**
  Order responses now include a new `interpretation` field providing the clinical assessment of the test results:

  * **`interpretation`** - Interpretation of the order result
    * Type: `enum<string> | null`
    * Available options: `normal`, `abnormal`, `critical`
    * Note: This enum is non-exhaustive

  This enhancement enables you to programmatically identify and prioritize critical lab results, improving clinical workflow efficiency and patient care monitoring.

  Check out the [GET /orders](/api-reference/lab/orders/get-orders) endpoint documentation.
</Accordion>

### Webhook Management Endpoints (May 2025)

You can now programmatically manage your webhooks via the [Webhooks API](/api-reference/org-management/team-webhook/list). The new endpoints allow you to:

* **CRUD** (create/read/update/delete) your webhooks
* Manage webhook **headers**
* Update webhook **secrets**

<Info>
  Org Management API is available for [the Scale plan](https://tryvital.io/pricing).
</Info>

### Team Management Keys (May 2025)

[Junction Management API](/api-details/junction-management-api) now supports Management Keys (previously *Org Keys*) that
are scoped to one or more Teams.

As a recap, there are now two types of Management Keys:

| Type                | Remarks                                                                                                                       |
| ------------------- | ----------------------------------------------------------------------------------------------------------------------------- |
| Org Management Key  | Full control of the organization — notably can create or delete Teams.                                                        |
| Team Management Key | Scoped control over one or more Teams. But it cannot access Org-level resources or actions, e.g., creating or deleting Teams. |

<Accordion title="Details" defaultOpen icon="key" iconType="duotone">
  All Management Keys — Org or Team — are accepted by the `X-Management-Key` header, as well as the deprecated `X-Vital-Org-Key` header.

  Selected customers can now manage Management Keys in the [Junction Dashboard](https://app.tryvital.io/) through:

  | Type                | Remarks                                                                    |
  | ------------------- | -------------------------------------------------------------------------- |
  | Org Management Key  | The **Org Config** page; accessible via the top-left corner Dropdown Menu. |
  | Team Management Key | The **Team Config** page.                                                  |

  Check out:

  * the [Create Management Key](/api-reference/org-management/management-keys/create-management-key) endpoint documentation;
  * the [List Management Keys](/api-reference/org-management/management-keys/list-management-keys) endpoint documentation; and
  * the [Delete Management Key](/api-reference/org-management/management-keys/delete-management-key) endpoint documentation.

  <Note>
    If you intend to create a Team Management Key that binds to 2 or more Teams, you must use the
    [Create Management Key](/api-reference/org-management/management-keys/create-management-key) API endpoint. Junction Dashboard does not
    support creating a key for more than one Team.
  </Note>

  <Note>
    Note that Management Keys cannot be used as Team API Keys to access the Junction API. However, you can
    [manage Team API Keys](/api-reference/org-management/team-api-keys/create-team-api-key) through a Management Key.
  </Note>

  <Info>
    [Junction Management API](/api-details/junction-management-api) is available for [the Scale plan](https://tryvital.io/pricing).
  </Info>
</Accordion>

### `X-Management-Key` header for Junction Management API (April 2025)

[Junction Management API](/api-details/junction-management-api) now accepts Management Keys (previously *Org Keys*)
in the `X-Management-Key` header, in addition to the `X-Vital-Org-Key` header.

We would continue to support the `X-Vital-Org-Key` header. Though we recommend moving over to `X-Management-Key` to avoid
confusion, especially if you do plan to adopt Team Management Keys.

<Info>
  [Junction Management API](/api-details/junction-management-api) is available for [the Scale plan](https://tryvital.io/pricing).
</Info>

### Enhanced Historical Data Pull Status Tracking (May 2025)

We've added a new "Retrying" state to the Historical Pull Status page and the historical introspection endpoint, helping you distinguish temporary issues from permanent failures.
Additionally, failed historical pulls now include extra error information, making troubleshooting easier and more efficient.

<Info>
  This applies to connections established after 9th May.
</Info>

### Prepare Team Custom Credentials endpoint (Aug 2024)

The new [Prepare Team Custom Credentials](/api-reference/org-management/team-custom-credentials/prepare-team-custom-credentials) endpoint
provides instructions for preparation of [Bring Your Own OAuth](/wearables/connecting-providers/bring_your_own_oauth) custom credentials.

You can use the information to configure things like OAuth callback URI and the Webhook URI (if applicable), before activating it on your
Vital Team through the [Set Team Custom Credential](/api-reference/org-management/team-custom-credentials/upsert-team-custom-credentials)
endpoint.

<Info>
  Org Management API is available for [the Scale plan](https://tryvital.io/pricing).
</Info>

### Azure Event Hub: Flexible routing (Aug 2024)

You can now configure your [Azure Event Hub destination in ETL Pipelines](/webhooks/etl-pipelines#azure-event-hub)
to route Vital data events to different Event Hubs based on their event type prefix.

Check out the [ETL Pipelines - Azure Event Hub](/webhooks/etl-pipelines#multiple-event-hubs) documentation.

<Info>
  ETL Pipelines are available for [the Scale plan](https://tryvital.io/pricing).
</Info>

### Azure Event Hubs as ETL Pipeline destination (Jun 2024)

You can now receive [events](/webhooks/introduction) from Vital directly with your Azure Event Hubs.

Check out the [ETL Pipelines](/webhooks/etl-pipelines#azure-event-hub) documentation.

<Info>
  ETL Pipelines are available for [the Scale plan](https://tryvital.io/pricing).
</Info>

### Manage Team Brand Information (Apr 2024)

You can now manage Brand Information of your Vital Teams through the Org Management API.

<Accordion title="Details" defaultOpen icon="billboard" iconType="duotone">
  Team Brand Information is used in:

  1. the Vital-hosted [Link widget](/wearables/connecting-providers/introduction);
  2. all user communications [Vital Lab Testing](/lab/overview/introduction) sent on your behalf; and
  3. the Vital-hosted Appointment Booking page for [Vital Lab Testing](/lab/overview/introduction).

  <Info>
    Org Management API is available for [the Scale plan](https://tryvital.io/pricing).
  </Info>

  Check out the [Update Team](/api-reference/org-management/team/update-team) and
  [Create Team](/api-reference/org-management/team/create-team) endpoint documentation.
</Accordion>

### Vital Orgs and Org Management API (Apr 2024)

We have introduced Vital Org, a new level that groups all your Vital Teams. Your Vital Teams have been
transparently grouped and migrated to the new structure.

<Accordion title="Details" defaultOpen icon="building" iconType="duotone">
  We introduced this to provide a unified billing and administrative experience for customers having these use cases:

  1. multi-region presence; or
  2. user organization with diverging team-level configurations.

  We introduced the Org Management API because customers have asked for the programmatic access to
  dyanmically create Vital Teams and manage different aspects of their Vital Teams.

  <Info>
    Org Management API is available for [the Scale plan](https://tryvital.io/pricing).
  </Info>

  Check out the [Org Management API](/api-reference/org-management) documentation.
</Accordion>

### New webhook event top-level fields (Mar 2024)

All events now include Team ID, User ID and Client User ID as top-level fields.

<Accordion title="Details" defaultOpen icon="message" iconType="duotone">
  We introduced this because this helps reduce a Vital User ID -> Client User ID database lookup on your end.

  Check out the [Webhook Event Structure](/webhooks/event-structure) documentation.

  #### Before

  ```json Basic event structure
  {
    "data": {
      # ... event specific data
    },
    "event_type": "daily.data.glucose.created",
  }
  ```

  #### After

  ```json Basic event structure
  {
    "data": {
      # ... event specific data
    },
    "event_type": "daily.data.glucose.created",
    "user_id": "4a29dbc7-6db3-4c83-bfac-70a20a4be1b2",
    "client_user_id": "01HW3FSNVCHC3B2QB5N0ZAAAVG",
    "team_id": "6b74423d-0504-4470-9afb-477252ccf67a"
  }
  ```
</Accordion>

### Improved error response for User creation conflicts (Mar 2024)

The [Create User](/api-reference/user/create-user) endpoint has improved handling of
conflicts in Client User ID.

<Accordion title="Details" defaultOpen icon="circle-exclamation" iconType="duotone">
  We introduced this because the user creation endpoint being idempotent can help
  simplify your application logic.

  When the supplied `client_user_id` conflicts with an existing user, the 400 Bad Request response
  now includes the Vital User ID (`user_id`) and the creation date (`created_on`) of the conflicting user.

  Check out the [Create User](/api-reference/user/create-user) endpoint documentation.
</Accordion>

### User Undo Deletion (Feb 2024)

You can now undo user deletion that is still in the 7-day grace period.

<Accordion title="Details" defaultOpen icon="trash-undo" iconType="duotone">
  Check out the [User Undo Deletion](/api-reference/user/undo-delete-user) endpoint documentation.
</Accordion>


# Dashboard
Source: https://docs.junction.com/changelog/core/dashboard


### Managing Org and Team Management Keys (June 2025)

You can now provision and manage Management Keys through the Junction Dashboard:

* Org Management Keys, through the new Org Config page.
* Team Management Keys, through the Team Config page of a specific team.

<AccordionGroup>
  <Accordion title="Team Management Keys" defaultOpen icon="key" iconType="duotone">
    You can manage Team Management Keys also through the Management API — check out the
    [Create Management Keys](/api-reference/org-management/management-keys/create-management-key) and
    [List Management Keys](/api-reference/org-management/management-keys/list-management-keys) endpoint documentation.

    You must be an Org Admin or using an Org Management Key to manage Team Management Keys.
  </Accordion>

  <Accordion title="Org Management Keys" defaultOpen icon="key" iconType="duotone">
    Only Org Admins can managed Org Management Keys, and it must be done through the Junction Dashboard.
  </Accordion>
</AccordionGroup>

### Managing Brand Information (June 2025)

We have updated the **Branding and Communcations** tab (previously *White-Labelling*) in the Team Config page. You can now
review and update your Team's brand information through this page.

<Accordion title="Details" defaultOpen icon="billboard" iconType="duotone">
  Team Brand Information is used in:

  1. All patient communication [Junction Lab Testing](/lab/overview/introduction) sent on your behalf;
  2. the Junction-hosted Appointment Booking page for [Junction Lab Testing](/lab/overview/introduction); and
  3. the Junction-hosted [Link Widget](/wearables/connecting-providers/introduction);

  You can also manage this information programmatically through the Management API — check out the
  [Update Team](/api-reference/org-management/team/update-team) and [Create Team](/api-reference/org-management/team/create-team)
  endpoint documentation.
</Accordion>

### Introducing Team Admin Roles (May 2025)

Introducing **Team Admin** roles for the Junction Dashboard users. Choose between organization-wide and team-specific admin privileges when adding members.

<Accordion title="Details" defaultOpen icon="magnifying-glass" iconType="duotone">
  ## What’s New

  * **Two Permission Levels** – When inviting new members to your organization, you can now choose between **Org Admin** and **Team Admin** roles.
  * **Team-Specific Access** – **Team Admins** can be granted access to specific teams by providing a list of team IDs during invitation or role modification.

  ## Role Capabilities

  ### Org Admin

  * Full access to all organization resources and teams
  * Can view and edit roles of all organization members
  * Complete access to billing information and organization settings

  ### Team Admin

  * Access limited to specifically assigned teams
  * Cannot view or edit roles of other organization members
  * No access to teams outside their allowed list
  * Cannot view or modify billing information or other organization-level settings
</Accordion>

### Improved Order Search experience (Aug 2024)

We have improved the search and filtering capabilities in the Orders page, helping you quickly locate specific orders and information.

<Accordion title="Details" defaultOpen icon="magnifying-glass" iconType="duotone">
  #### Basic filters

  Order searching now supports these filtering criteria:

  * Patient or Recipient (in the case of at-home kits) — First or Last name
  * Patient Email
  * Patient Date of Birth
    * in the YYYY-MM-DD format.
    * e.g., “1988” will filter for all patients born in 1988.
    * e.g., “1988-03” will filter for all patients born in March of 1988 and “1988-03-07” will filter for all patients born on March 7th, 1988.
  * User ID
  * Client User ID
  * Order ID
  * Order Status

  <Info>
    Only one Basic filter can be active at any given time. This is because Basic filters are
    mutually exclusive with each other.
  </Info>

  ### Date filters

  On top of the basic filters, you can now filter by date range based on either:

  * the Order Creation date
    * For scheduled tests, the order creation date is considered instead of the scheduled date.
  * the Order Last Updated date
    * This allows you to filter orders based on the date at which the order status was last updated.

  Dates are currently filtered with respect to the UTC timezone.

  ### Status filters

  Filter based on the most recent status of the order. Note that some statuses are unique to a collection modality such as Mobile Phlebotomy or Self-Collected Test Kits.

  <Info>
    You can apply multiple Status filters at the same time. These stack as a logical OR among themselves.
  </Info>

  ### Order Type filters

  Filter based on the order type: At-Home Phlebotomy, Walk-In Test, At-Home Test Kit.

  <Info>
    You can apply multiple Order Type filters at the same time. These stack as a logical OR among themselves.
  </Info>

  ### Activation Type filters

  Filter for:

  1. Scheduled Orders that would not begin execution until the specified target date; or
  2. Current Orders that have been executed and are being fulfilled.
</Accordion>

### Improved User Search and Introspection experience (Jun 2024)

The Users page in the Vital Dashboard is now a search-first experience with more filtering and sorting options
available. You can now also click on specific users to inspect device connection status and the patient details.

<Accordion title="Details" defaultOpen icon="magnifying-glass" iconType="duotone">
  Find your user by typing their Client User ID or Vital User ID into the search bar. For lab testing users: Name, Email and Phone Number are also supported.

  Click on a user to reveal the new User Details page:

  #### The General tab

  Shows an overview of all patient details and user settings associated with the Vital User ID.

  #### The Connections tab

  Provides device connection availability and data ingestion insights of the Vital User.

  You can also obtain this same information programmatically through the [Introspection API](/api-reference/introspection/user-resources).
</Accordion>


# API
Source: https://docs.junction.com/changelog/lab-testing/api


### Enhanced Lab Order Management with Result Interpretation Filtering (June 2025)

We've enhanced the Orders page with new filtering and visualization capabilities for lab test result interpretations, making it easier to identify and prioritize critical patient results.

<Accordion title="Details" defaultOpen icon="filter" iconType="duotone">
  ## What's New

  * **Interpretation Filter** – Filter orders by clinical result interpretation using the new "Interpretation" dropdown filter
  * **Critical Value Indicators** – The orders table now displays visual indicators for orders with critical results
  * **Enhanced Order Details** – Order detail views now include interpretation badges highlighting critical findings

  ## Filter Options

  The new Interpretation filter allows you to quickly locate orders based on their clinical assessment:

  * **Normal** – Orders with results within normal reference ranges
  * **Abnormal** – Orders with results outside normal ranges but not critically urgent
  * **Critical** – Orders with results requiring immediate clinical attention

  ## Visual Enhancements

  ### Orders Table

  * Critical value indicators help you quickly spot high-priority results that need immediate attention
  * Clear visual distinction between normal, abnormal, and critical interpretations

  ### Order Details View

  * Prominent badges display the interpretation status for easy identification
  * Critical results are highlighted with distinctive styling to ensure they don't go unnoticed

  <Info>
    You can combine the Interpretation filter with existing filters like Order Status, Date Range, and Order Type for more precise result filtering.
  </Info>

  This enhancement improves clinical workflow efficiency by enabling healthcare teams to quickly identify and prioritize orders requiring immediate attention.
</Accordion>

### Introducing Panel Renaming & Archiving (May 2025)

We’ve added more control to how you manage test panels.

<Accordion title="Details" icon="magnifying-glass" iconType="regular">
  Now you can skip the support email and work directly in the Test Catalog to:

  * Rename panel names
  * Archive outdated or unused panels to keep things clean
  * View archived panels using the "Status" filter and "unarchive" to make panels active again

  Existing orders tied to archived panels will remain active and processable.

  [Full product guide →](https://support.tryvital.com/articles/1278554980-managing-lab-panels)
</Accordion>

### Problem in Transit Order Statuses (Mar 2025)

Testkit orders now support two new statuses representing problems in transit. Refer to the [lab test lifecycle documentation](/lab/workflow/lab-test-lifecycle).

<Accordion icon="billboard" iconType="duotone" title="Details" defaultOpen>
  We’re introducing two new statuses for the `OrderLowLevelStatus` enum (`problem_in_transit_lab` and `problem_in_transit_customer`) and two for the `OrderStatus` enum (`collecting_sample.testkit.problem_in_transit_customer` and `collecting_sample.testkit.problem_in_transit_lab`)—and we may make further changes in the future. To ensure future compatibility, we ask that you avoid exhaustive matching on enum values. Code that assumes all current values are exhaustive could break or fail to compile with SDK upgrades.

  Here’s how to verify and ensure you benefit from future enhancements:

  1. Look for areas in your code where you take an action based on the values of a Junction-defined enum. For example, you might have Python code like this:

  ```python Python
  match status:
      case OrderStatus.TESTKIT_ORDERED:
          handle_ordered()
      case OrderStatus.TESTKIT_AWAITING_REGISTRATION:
          handle_awaiting_registration()
          # other cases...
  ```

  2. Check unknown values in your code paths are handled gracefully—for example, by using default cases. Logging unknown values can help you stay informed.

  ```python Python
  match status:
      # previous cases...
      case unknown_status:
          logger.warning(f"Unknown status received: {repr(unknown_status)}")
  ```

  3. Make sure you’re running the latest version of our SDK.

  4. You’re good to go. Once you’ve checked the code paths won’t break if Junction-defined enums start including new values, no further action is needed.
</Accordion>

### Source Marker Identification for Results (Nov 2024)

Results now feature the source, orderable marker from which they originated.
Refer to the [documentation](/lab/results/result-formats)

### PSC Appointment Scheduling API (Oct 2024)

Walk-in Phlebotomy orders now allow for appointment booking directly with Vital.
Refer to the [documentation](/lab/walk-in/order-lifecycle)

### Phlebotomy Availability API - Start Date Query (Sep 2024)

You can now supply a `start_date` to the [Appointment Availability API](/api-reference/lab-testing/at-home-phlebotomy/appointment-availability).
The API always responds with 14 days worth of slots.

### À La Carte Ordering (Sep 2024)

Vital now supports ordering à-la-carte, as well as a revamped ordering flow.

<Accordion icon="billboard" iconType="duotone" title="Details" defaultOpen>
  Check out the [Ordering](/lab/workflow/ordering) documentation.
</Accordion>

### Partial Results Webhook (Jul 2024)

Vital now supports sending webhooks for partial results, on a team-by-team configuration.

<Accordion icon="billboard" iconType="duotone" title="Details" defaultOpen>
  Check out the [Partial Results Notifications](/lab/workflow/partials) documentation.
</Accordion>

### Patient Service Center (PSC) Availability API (Jul 2024)

It is now possible to verify lab PSC availability in regards to a zip code, radius or order.

<Accordion icon="billboard" iconType="duotone" title="Details" defaultOpen>
  Check out the [Patient Service Center](/lab/walk-in/locations) documentation.
</Accordion>

### Create Lab Tests With Provider IDs  (Jun 2024)

It is now possible to create lab tests using the Laboratory's unique provider id.
This allows payloads to be shared across sandbox and production.

<Accordion icon="billboard" iconType="duotone" title="Details" defaultOpen>
  Check out the [Create a Lab Test](/lab/workflow/create-test) documentation.
</Accordion>

### Ask on Order Entry (AOE)  (Jun 2024)

You can now order panels with AOE requirements via the API.

<Accordion icon="billboard" iconType="duotone" title="Details" defaultOpen>
  Check out the [AOE](/lab/workflow/aoe) documentation.
</Accordion>


# Deprecations
Source: https://docs.junction.com/changelog/lab-testing/deprecations


### `lab_test_id` in the [POST /v3/order](/api-reference/lab-testing/create-order) endpoint.

`lab_test_id` is deprecated in favor of the `order_set` field. More information [here](/lab/workflow/ordering).

<Steps>
  <Step title="Remove lab_test_id usage" stepNumber="1" titleSize="p">
    In the `order` payload, remove the usage of `lab_test_id`

    ```json
    {
        "lab_test_id": "some_id" # Remove this
    }
    ```
  </Step>

  <Step title="Use the order_set field" stepNumber="2" titleSize="p">
    In the `order` payload, add the `order_set` object.

    ```json
    {
        "order_set": {
            "lab_test_ids": ["some_id"]
        }
    }
    ```
  </Step>
</Steps>

### `value` field in the `results` object

We are removing the `value` field from the [results object](/api-reference/results/get-results), as it does not accuratly capture all possible result values. In turn, we've introduced the `result` field.

<Card title="Recommended Action">
  Parse the `result` field in accordance to the `result_type` field. [More information here.](/lab/results/result-formats#resulttype)
</Card>

### `requisition_form_url` in the `order` object

This field is a signed GCP bucket URL, which is only active for 7 days. It will be removed in favor of the [download PDF](/api-reference/lab-testing/requisition-pdf) endpoint.

### `GET /v3/lab_tests` in favor of `GET /v3/lab_test`

The endpoint `GET /v3/lab_tests` is deprecated in favor of `GET /v3/lab_test`. The new endpoint will return a paginated list of lab tests and supports two new parameters: `lab_test_limit` and `next_cursor`.


# API
Source: https://docs.junction.com/changelog/wearables/api


### Device metadata and source device tracking (August 2025)

We have added device tracking with new API endpoints and enhanced data attribution.
Eligible data resources now include `source.device_id` when the originating device can be determined, enabling better tracking and device-specific analytics.

Check out the [Device ID attribution documentation](/wearables/providers/data-attributions#device-id) on what data resources are eligible for Device ID attributions in this initial release.

<Accordion icon="devices" iconType="duotone" title="Details" defaultOpen>
  The new [Get User Devices](/api-reference/data/device/get-devices) and [Get Device Details](/api-reference/data/device/get-device) endpoints allow you to retrieve detailed device information for connected users.

  We've also added [Provider Device Created](/event-catalog/provider.device.created) and [Provider Device Updated](/event-catalog/provider.device.updated) webhook events to notify you when device information becomes available or changes.
</Accordion>

### Detecting password expiration in password-based connections (July 2025)

The [Link Password Provider endpoint](/api-reference/link/link-password-provider), the [Get User Connections endpoint](/api-reference/user/get-users-connected-providers)
and the [Provider Connection Error events](/event-catalog/provider.connection.error) would now report password expiration using the `provider_password_expired` error type.

This mainly affects [Abbott LibreView patient-based connections](/wearables/guides/abbott-libreview#abbott-libreview-for-patient-based-connections).

### Introducing Universal Group By Support to Horizon AI Query (June 2025)

<Card horizontal icon="person-digging" color="#57164A">
  Horizon AI Query is in **closed beta**.

  Interested in the Horizon AI Query? Get in touch with your Customer Success Manager.
</Card>

Horizon AI Query can now group and aggregate the data by any [Table Column expression](/api-reference/horizon-ai/aggregation/query-dsl/column-expressions#table-column-expression)
and/or any [Source Column expression](/api-reference/horizon-ai/aggregation/query-dsl/column-expressions#source-column-expression).

This gives you more options on how the data should be dissected — not just by calendar units, but now also by Data Source fields and categorical values from the
data itself.

<Accordion icon="link" iconType="duotone" title="Details" defaultOpen>
  Check out the [Group By clause](/api-reference/horizon-ai/aggregation/query-dsl/group-by-clause) documentation.

  <Note>
    If both the *Provider* and *Source Type* Source Columns are present in the [Group By clause](/api-reference/horizon-ai/aggregation/query-dsl/group-by-clause),
    the implicit [Data Prioritization](/api-reference/horizon-ai/aggregation/data-prioritization) behaviour would be disabled.
  </Note>

  #### Example queries

  <CodeGroup>
    ```python Python DSL
    # Group Summary Data by Week, Provider and Source Type

    va.select(...).group_by(
       va.date_trunc(va.Sleep.index(), 1, "week"),
       va.Source.col("source_provider"),
       va.Source.col("source_type"),
    )

    # Group Timeseries Data by Day, Provider and Source Type

    va.select(...).group_by(
       va.date_trunc(va.Timeseries.index(), 1, "day"),
       va.Source.col("source_provider"),
       va.Source.col("source_type"),
    )

    # Group Electrocardiogram Voltage Data by Hour and Lead Type

    va.select(...).group_by(
       va.date_trunc(va.Timeseries.index(), 1, "hour"),
       va.Timeseries.col("electrocardiogram_voltage").field("type"),
    )

    # Group Sleep Breathing Disturbance by Hour and Elevated vs. Not Elevated

    va.select(...).group_by(
       va.date_trunc(va.Timeseries.index(), 1, "hour"),
       va.Timeseries.col("sleep_breathing_disturbance").field("type"),
    )
    ```

    ```json JSON DSL
    # Group Summary Data by Week, Provider and Source Type

    {
        "group_by": [
            {
                "date_trunc": {
                    "value": 1,
                    "unit": "week"
                },
                "arg": { "index": "sleep" }
            },
            { "source": "source_provider" },
            { "source": "source_type" }
        ]
    }

    # Group Timeseries Data by Day, Provider and Source Type

    {
        "group_by": [
            {
                "date_trunc": {
                    "value": 1,
                    "unit": "day"
                },
                "arg": { "index": "timeseries" }
            },
            { "source": "source_provider" },
            { "source": "source_type" }
        ]
    }

    # Group Electrocardiogram Voltage Data by Hour and Lead Type

    {
        "group_by": [
            {
                "date_trunc": {
                    "value": 1,
                    "unit": "hour"
                },
                "arg": { "index": "timeseries" }
            },
            {
                "timeseries": "electrocardiogram_voltage",
                "field": "type"
            },
        ]
    }

    # Group Sleep Breathing Disturbance by Hour and Elevated vs. Not Elevated

    {
        "group_by": [
            {
                "date_trunc": {
                    "value": 1,
                    "unit": "hour"
                },
                "arg": { "index": "timeseries" }
            },
            {
                "timeseries": "sleep_breathing_disturbance",
                "field": "type"
            },
        ]
    }
    ```
  </CodeGroup>
</Accordion>

### Introducing Timeseries Data Support to Continuous Query (June 2025)

<Card horizontal icon="person-digging" color="#57164A">
  Horizon AI Query is in **closed beta**.

  Interested in the Horizon AI Query? Get in touch with your Customer Success Manager.
</Card>

We have expanded Continuous Query to support **timeseries resources** in addition to the previously available summary resources.

With a few simple configuration steps, Continuous Query enables you to:

1. Extract aggregations of high‑volume timeseries data collected across all your active user device connections; and

2. Offload this concern to Junction, allowing you to simplify your data pipeline and focus on extracting actionable signals.

<Accordion icon="link" iconType="duotone" title="Details" defaultOpen>
  You can now select timeseries resources in a Query:

  * For each resource, you can select all of specific fields of interest.
  * You can select multiple timeseries resources simultaneously, even though they are of different types (discrete, interval of blood pressure).

  Check out the [Table Column expression](/api-reference/horizon-ai/aggregation/query-dsl/column-expressions) documentation.

  #### Examples of Timeseries Table Column expressions

  <CodeGroup>
    ```python Python DSL
    select(
        # Blood Pressure
        Timeseries.col("blood_pressure").field("systolic"),
        Timeseries.col("blood_pressure").field("diastolic"),
        Timeseries.col("blood_pressure").field("timezone_offset"),

        # Discrete Samples
        Timeseries.col("heartrate").field("value"),
        Timeseries.col("heartrate").field("timezone_offset"),

        # Interval Samples
        Timeseries.col("body_temperature_delta").field("value"),
        Timeseries.col("body_temperature_delta").field("duration"),
        Timeseries.col("body_temperature_delta").field("sensor_location"),
        Timeseries.col("body_temperature_delta").field("timezone_offset"),

        # Workout Interval Samples
        Timeseries.col("workout_distance").field("value"),
        Timeseries.col("workout_distance").field("duration"),
        Timeseries.col("workout_distance").field("sport"),
        Timeseries.col("workout_distance").field("workout_id"),
    )
    ```

    ```json JSON DSL:
    [
        # Blood Pressure
        {
          "timeseries": "blood_pressure",
          "field": "systolic"
        },
        {
          "timeseries": "blood_pressure",
          "field": "diastolic"
        },
        {
          "timeseries": "blood_pressure",
          "field": "timezone_offset"
        },
        # Discrete Samples
        {
          "timeseries": "heartrate",
          "field": "value"
        },
        {
          "timeseries": "heartrate",
          "field": "timezone_offset"
        },
        {
          "timeseries": "heartrate",
          "field": "type"
        },
        # Interval Samples
        {
          "timeseries": "body_temperature_delta",
          "field": "value"
        },
        {
          "timeseries": "body_temperature_delta",
          "field": "duration"
        },
        {
          "timeseries": "body_temperature_delta",
          "field": "sensor_location"
        },
        {
          "timeseries": "body_temperature_delta",
          "field": "timezone_offset"
        },
        # Workout Interval Samples
        {
          "timeseries": "workout_distance",
          "field": "value"
        },
        {
          "timeseries": "workout_distance",
          "field": "duration"
        },
        {
          "timeseries": "workout_distance",
          "field": "sport"
        },
        {
          "timeseries": "workout_distance",
          "field": "workout_id"
        },
    ]
    ```
  </CodeGroup>
</Accordion>

### External User ID of User Connections (April 2025)

We now expose the *External User ID* of User Connections in the [Provider Connection Created](/event-catalog/provider.connection.created) event
and [Get User Connections](/api-reference/user/get-users-connected-providers) endpoint.

The External User ID is the unique user identifier supplied by the provider, e.g., the Fitbit User ID for Fitbit connections.

| Connection type               | Content                                           |
| ----------------------------- | ------------------------------------------------- |
| OAuth Providers               | User unique identifier; provider-specific formats |
| Password Providers            | Username                                          |
| Email Providers               | Email                                             |
| Junction Mobile SDK Providers | null (not available at this time)                 |

<Accordion icon="link" iconType="duotone" title="Details" defaultOpen>
  Check out the [Provider Connection Created](/event-catalog/provider.connection.created) event and
  [Get User Connections](/api-reference/user/get-users-connected-providers) endpoint documentation.
</Accordion>

### Link API Improvements (Jan 2025)

We have increased Link Token expiry from 15 minutes to 60 minutes.

We have also added an `on_error=redirect` Link Token option which forces any error scenario to redirect to your specified `redirect_url`
URL, disabling any in-built error handling behaviour in the Link Widget.

<Accordion icon="link" iconType="duotone" title="Details" defaultOpen>
  Check out the [Link Error](/wearables/connecting-providers/errors) format and the [Generate a Link Token](/api-reference/link/generate-link-token) endpoint documentation.
</Accordion>

### Extendable Historical Date Ranges (Jul 2024)

We now offer the ability to set custom historical data ranges for wearables providers, with resource-level granularity.

<Accordion icon="lightbulb" iconType="duotone" title="Details" defaultOpen>
  You can now extend the historical pull range for a number of supported providers using the [Org Management API](/api-reference/org-management/team-data-pull-preferences/upsert-team-data-pull-preferences)

  <Info>
    Org Management API is available for [the Scale plan](https://tryvital.io/pricing).
  </Info>

  Check out the [Set Data Pull Preferences](/api-reference/org-management/team-data-pull-preferences/upsert-team-data-pull-preferences),
  [Get Data Pull Preferences](/api-reference/org-management/team-data-pull-preferences/get-team-scope-requirements), [Delete Data Pull Preferences](/api-reference/org-management/team-data-pull-preferences/delete-team-scope-requirements) endpoint documentation for more details.
</Accordion>

### Introspection: Historical Pull Timeline (May 2024)

The Historical Pull Introspection endpoint now reports the execution timeline of historical pulls.

<Accordion icon="lightbulb" iconType="duotone" title="Details" defaultOpen>
  The timeline tracks when the historical pull was scheduled, started, and eventually ended (success or failure). This
  improves the visibility around the latency of historical pulls, as well as providing more indicator of an incomplete
  execution.

  Check out the [Historical Pull Introspection](/api-reference/introspection/historical-pulls) endpoint documentation.
</Accordion>

### Team Scope Requirements (Apr 2024)

You can now tailor what scopes Vital would request from your Users using the [Org Management API](/api-reference/org-management/team-scope-requirements/upsert-team-scope-requirements).
This applies when your user connects to an [OAuth provider](/wearables/connecting-providers/auth_types) which supports scopes.

<Accordion icon="lightbulb" iconType="duotone" title="Details" defaultOpen>
  Vital ensures that any new provider connection can be established only when the user has granted all the scopes specified in the `user_must_grant` scope list.

  The scopes specified as `user_may_grant` would be requested alongside the `user_must_grant` scopes. However, unlike `user_must_grant`, they do not prevent the connection from being established.

  <Info>
    Org Management API is available for [the Scale plan](https://tryvital.io/pricing).
  </Info>

  Check out the [Set Team Scope Requirements](/api-reference/org-management/team-scope-requirements/upsert-team-scope-requirements) and
  [Get Team Scope Requirements](/api-reference/org-management/team-scope-requirements/get-team-scope-requirements) endpoint documentation on how to
  enable the setting.
</Accordion>

### Reject Duplicate Connections (Apr 2024)

You can now configure your Vital Team through the [Org Management API](/api-reference/org-management/team/update-team)
to reject duplicate wearable connections.

<Accordion icon="person-military-pointing" iconType="duotone" title="Details" defaultOpen>
  When the `reject_duplicate_connection` setting is enabled on the Team, Vital checks whether or
  not the provider-reported user ID is already connected to an existing User in your Team.

  If it does, the Link API would report the [`duplicate_connection` error](/wearables/connecting-providers/errors).

  <Info>
    Org Management API is available for [the Scale plan](https://tryvital.io/pricing).
  </Info>

  Check out the [Update Team](/api-reference/org-management/team/update-team) and
  [Create Team](/api-reference/org-management/team/create-team) endpoint documentation on how to
  enable the setting.

  Check out the [Link Errors](/wearables/connecting-providers/errors) documentation on how to
  catch the `duplicate_connection` error.
</Accordion>

### Link Error reporting (Apr 2024)

The Link API now reports errors in terms of a predefined set of [Error Types](/wearables/connecting-providers/errors)
on which your application logic can depend.

<Accordion icon="circle-exclamation" iconType="duotone" title="Details" defaultOpen>
  We introduce this because there has not been a dependable way for your application logic
  to understand why a connection attempt has failed, and in turn this prevents your application
  from providing actionable messages to your end users.

  Depending on how you initiate the Link flow, the Link Error would be reported either as a
  URL query parameter, or as part of the JSON response.

  Check out the [Link Errors](/wearables/connecting-providers/errors) documentation for the detailed guidance.
</Accordion>

### Understanding Resource Availability (Apr 2024)

When a user connection to a provider is established, the webhook event now includes a resource availability
report of the connection.

<Accordion icon="signal-bars" iconType="duotone" title="Details" defaultOpen>
  We introduce this because this helps you understand what resources would and would not be available on
  a new connection. We also provide insights into how partial consents from users during the OAuth authentication
  flow can influence the resource availability, so that you can take actions accordingly.

  This resource availability report is based on the permissions *(also known as API access scopes)* the user has
  granted during the authentication process.

  In some cases, a provider resource may be available, but some information could be absent due to
  some optional scopes having been denied by the user. The availability report includes a full breakdown
  of granted and denied scopes by their optionality.

  <Note>
    If the provider has no concept of API access scopes, we report all resources as available.
  </Note>

  You can also query this information at any time through the
  [Get User Connections](/api-reference/user/get-users-connected-providers) endpoint.

  Check out the [Provider Connection Created](/event-catalog/provider.connection.created)
  (`provider.connection.created`) event schema and the [Get User Connections](/api-reference/user/get-users-connected-providers) endpoint documentation.
</Accordion>

### Fallback Birth Date for Heart Rate Zones (Feb 2024)

You can now set a Fallback Birth Date on a user.

<Accordion icon="cake-candles" iconType="duotone" title="Details" defaultOpen>
  Vital can use this to compute a more accurate workout Heart Rate Zones, when the provider
  exposes neither heart rate zones nor user age to Vital.

  Check out the [Heart Rate Zones](/wearables/providers/heart-rate-zones#fallback-birth-date) documentation.
</Accordion>

### Grouped Timeseries (Feb 2024)

You can now get grouped timeseries data.

<Accordion icon="chart-scatter" iconType="duotone" title="Details" defaultOpen>
  This initial release groups data by [Source Type](/wearables/providers/data-attributions#source-type)
  from [supported providers](/wearables/providers/data-attributions#supported-providers).

  Check out the [Blood Oxygen](/api-reference/timeseries-grouped/blood-oxygen) endpoint documentation for an example.
</Accordion>

### Historical Pull Introspection (Dec 2023)

You can now introspect the status of all one-off user historical data pulls.

<Accordion icon="binoculars" iconType="duotone" title="Details" defaultOpen>
  It also provides the pulled date-time range, as well as a rough estimate of the amount of
  data ingested (in terms of "days with data").

  Check out the [Historical Pull Introspection](/api-reference/introspection/historical-pulls) endpoint documentation.
</Accordion>

### User Resources Introspection (Dec 2023)

You can now introspect user data ingestion statistics.

<Accordion icon="binoculars" iconType="duotone" title="Details" defaultOpen>
  For example, the endpoint provides:

  1. Oldest and newest data timestamp
  2. The number of objects sent in `*.created` events
  3. The status and time of the last ingestion attempt (polling or push)

  Check out the [User Resources Introspection](/api-reference/introspection/user-resources) endpoint documentation.
</Accordion>

### Vital Sign-In Token for Mobile SDKs (Nov 2023)

Vital Sign-In Token is a new, user-scoped Authentication scheme for Vital Mobile SDKs.

<Accordion icon="id-badge" iconType="duotone" title="Details" defaultOpen>
  It grants only user-scoped access to your mobile app sign-ins. This allows you to keep your Vital API Keys
  as server-side secrets.

  We encourage all customers using Vital API Keys in their production mobile apps to
  migrate to the Vital Sign-In Token scheme.

  Check out the [SDK Authentication](/wearables/sdks/authentication#vital-sign-in-token) guide on how to migrate to
  this scheme. Check out the [Create Sign-In Token](/api-reference/user/create-sign-in-token) endpoint documentation
  on how to generate tokens for your mobile app sign-ins.
</Accordion>


# Deprecations
Source: https://docs.junction.com/changelog/wearables/deprecations


### The `hypnogram` timeseries type

<Warning>The removal will happen on or after **31 January 2025**.</Warning>

We have introduced a new Sleep Cycle summary type (`sleep_cycle`) which captures the detailed hypnogram of a sleep session.
It replaces the existing `hypnogram` timeseries type. More details can be found here: [Sleep Cycle Summary](/api-reference/data/sleep-cycle/get-summary)

<Card title="Recommended Action" icon="lightbulb-exclamation-on">
  Start processing the new `historical.data.sleep_cycle.created`, `daily.data.sleep_cycle.created` and `daily.data.sleep_cycle.updated` events.
  Stop processing the `historical.timeseries.hypnogram.created`, `daily.timeseries.hypnogram.created` and `daily.timeseries.hypnogram.updated` events.
</Card>

### Redefining Source and Provider

<Warning>The stated removals in this section will happen on or after **31 July 2024**.</Warning>

Vital has redefined what *Source* and *Provider* means across our API and event schemas:

<Accordion title="The new definitions of Provider and Source">
  | Entity   | Definition                                                                      |
  | -------- | ------------------------------------------------------------------------------- |
  | Source   | The source context of a specific summary or a specific timeseries value group.  |
  | Provider | A wearable data provider (an app, a platform, a service, or Vital Mobile SDKs). |

  A *Source* context comprises of:

  * the Provider (slug only)
  * the [Source Type](/wearables/providers/data-attributions#source-type)
  * the [App ID](/wearables/providers/data-attributions#app-id) (*optional*)

  We have also plans for the *Source* context to include source device metadata where available.

  A *Provider* object is a short description of a wearable data provider. It comprises of the familiar
  `name`, `logo` and `slug` trio you have been receiving in many data events.
</Accordion>

To migrate to the new definitions, Vital is announcing the following deprecations:

<Steps>
  <Step title="All Data Dvents (daily.data.*)" stepNumber="1" titleSize="p">
    Inside the Source context located at `$.data.source`, the `name`, `logo`, and `slug` fields are
    now deprecated.

    Vital no longer embeds these *Provider* object fields in every data event, except for the provider
    slug.

    Using the [Steps data event](/event-catalog/daily.data.steps.created) as an illustration, originally
    the `source` field describes the wearable data provider:

    ```json daily.data.steps.created (Original)
    {
        "event_type": "daily.data.steps.created",
        "data": {
            "data": [...],
            "source": {
                "name": "Oura",
                "slug": "oura",
                "logo": "https://example.com/oura.svg"
            }
        },
        "user_id": "fb58770e-8b7b-4416-a5bd-8433786d10dc"
    }
    ```

    As part of this redefinition, the `source` field is redefined to mean the *Source* context of this steps timeseries
    value group. So Vital has introduced a few new *Source* context fields:

    ```json daily.data.steps.created (Current)
    {
        "event_type": "daily.data.steps.created",
        "data": {
            "data": [...],
            "source": {
                "provider": "oura",
                "type": "ring",
                "app_id": null,

                /** BEGIN: deprecated Provider fields **/
                "name": "Oura",
                "slug": "oura",
                "logo": "https://example.com/oura.svg"
                /** END: deprecated Provider fields **/
            }
        },
        "user_id": "fb58770e-8b7b-4416-a5bd-8433786d10dc"
    }
    ```

    Once the deprecation cycle ends, Vital will remove the deprecated fields:

    ```json daily.data.steps.created (Future)
    {
        "event_type": "daily.data.steps.created",
        "data": {
            "data": [...],
            "source": {
                "provider": "oura",
                "type": "ring",
                "app_id": null
            }
        },
        "user_id": "fb58770e-8b7b-4416-a5bd-8433786d10dc"
    }
    ```

    <Card title="Recommended Action" icon="lightbulb-exclamation-on">
      Stop parsing `name`, `logo` and `slug` when processing the `$.data.source` field in
      **all Data Events** (daily.data.\*).
    </Card>

    <Info>
      If you need the Provider information, you can obtain it through the [Get Providers](/api-reference/providers)
      endpoint.
    </Info>
  </Step>

  <Step title="Get Summary endpoints" stepNumber="2" titleSize="p">
    <Note>
      This applies to:

      * Get Activity: `GET /v2/summary/activity/*`
      * Get Body: `GET /v2/summary/body/*`
      * Get Meal: `GET /v2/summary/meal/*`
      * Get Profile: `GET /v2/summary/profile/*`
      * Get Sleep: `GET /v2/summary/sleep/*`
      * Get Workouts: `GET /v2/summary/workouts/*`
    </Note>

    Similar to changes to the Data Events, the `name`, `logo`, and `slug` sub-fields under the `source` field
    in each and every summary are now deprecated.

    Vital no longer embeds these *Provider* object fields in every summary, except for the provider
    slug.

    Using the [Get Profile endpoint](/api-reference/profile/get-summary) as an illustration, originally
    the `source` field describes the wearable data provider:

    ```json Profile (Original)
    {
        "id": "eadba0c7-4e81-4d17-962c-9ebe0629c08f",
        "date": "2022-08-04",
        "height": 183,
        "source": {
            "name": "Oura",
            "slug": "oura",
            "logo": "https://logo_url.com"
        },
        "user_id": "71937dd3-aebe-46b7-ab64-c287bd75b2a6"
    }
    ```

    As part of this redefinition, the `source` field is redefined to mean the *Source* context of this Profile
    summary. So Vital has introduced a few new *Source* context fields:

    ```json Profile (Current)
    {
        "id": "eadba0c7-4e81-4d17-962c-9ebe0629c08f",
        "date": "2022-08-04",
        "height": 183,
        "source": {
            "provider": "oura",
            "type": "app",
            "app_id": null,

            /** BEGIN: deprecated Provider fields **/
            "name": "Oura",
            "slug": "oura",
            "logo": "https://example.com/oura.svg"
            /** END: deprecated Provider fields **/
        },
        "user_id": "71937dd3-aebe-46b7-ab64-c287bd75b2a6"
    }
    ```

    Once the deprecation cycle ends, Vital will remove the deprecated fields:

    ```json Profile (Future)
    {
        "id": "eadba0c7-4e81-4d17-962c-9ebe0629c08f",
        "date": "2022-08-04",
        "height": 183,
        "source": {
            "provider": "oura",
            "type": "app",
            "app_id": null
        },
        "user_id": "71937dd3-aebe-46b7-ab64-c287bd75b2a6"
    }
    ```

    <Card title="Recommended Action" icon="lightbulb-exclamation-on">
      Stop parsing `name`, `logo` and `slug` fields in **all Get Summary endpoint** responses.
    </Card>

    <Info>
      If you need the Provider information, you can obtain it through the [Get Providers](/api-reference/providers)
      endpoint.
    </Info>
  </Step>

  <Step title="Provider Connection events" stepNumber="3" titleSize="p">
    <Note>
      This applies to:

      * Provider Connection Created: `provider.connection.created`.
    </Note>

    Vital has renamed the `source` field in this event to `provider`, aligning with the redefinition of *Source*
    and *Provider*.

    To illustrate the change, originally the `source` field describes the wearable data provider:

    ```json provider.connection.created (Original)
    {
        "event_type": "provider.connection.created",
        "data": {
            "source": {
                "name": "Oura",
                "slug": "oura",
                "logo": "https://logo_url.com"
            },
            "user_id": "71937dd3-aebe-46b7-ab64-c287bd75b2a6",
            "resource_availability": {...}
        }
    }
    ```

    As part of this redefinition, `source` is no longer applicable here. Vital has introduced an identical
    `provider` field as its replacement.

    ```json provider.connection.created (Current)
    {
        "event_type": "provider.connection.created",
        "data": {
            "provider": {
                "name": "Oura",
                "slug": "oura",
                "logo": "https://logo_url.com"
            },
            "user_id": "71937dd3-aebe-46b7-ab64-c287bd75b2a6",
            "resource_availability": {...},

            /** BEGIN: deprecated field **/
            "source": {
                "name": "Oura",
                "slug": "oura",
                "logo": "https://logo_url.com"
            }
            /** END: deprecated field **/
        }
    }
    ```

    Once the deprecation cycle ends, Vital will remove the deprecated `source` field:

    ```json provider.connection.created (Future)
    {
        "event_type": "provider.connection.created",
        "data": {
            "provider": {
                "name": "Oura",
                "slug": "oura",
                "logo": "https://logo_url.com"
            },
            "user_id": "71937dd3-aebe-46b7-ab64-c287bd75b2a6",
            "resource_availability": {...}
        }
    }
    ```

    <Card title="Recommended Action" icon="lightbulb-exclamation-on">
      Update your `provider.connection.created` event parsing logic to parse the `provider` field,
      and stop parsing the `source` field.
    </Card>
  </Step>
</Steps>

### The `is_final` flag in `historical.data.*.created` events

<Warning>The removal will happen on or after **31 June 2024**.</Warning>

We are removing the `is_final` flag from the Historical Pull Completed (`historical.data.*.created`) events.

For each resource, Vital now signals one Historical Pull Completed event, only after we have finished fetching
all data chunks. This means `is_final` no longer has a meaning, since the event itself is *final*.

<Card title="Recommended Action" icon="lightbulb-exclamation-on">
  Stop parsing `is_final` as a required field when processing `historical.data.*.created` events.
</Card>


# Provider and Resources
Source: https://docs.junction.com/changelog/wearables/providers


### Expanded Apple HealthKit data type coverage (April 2025)

Junction iOS SDK 1.6.0 has expanded the HealthKit data type coverage:

| Type                      | Remarks                                                                                                                                                                                          | `VitalResource`              |
| ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------- |
| Workout Stream timeseries | Workout Distance — including cycling, swimming, rowing, cross country skiing, downhill snow sports, paddle sports, skating sports, walking, running and wheelchair.<br />Workout Swimming Stroke | As part of `Workout`         |
| Timeseries                | Heart Rate Recovery One Minute                                                                                                                                                                   | `HeartRateRecoveryOneMinute` |

Workout Stream timeseries data always have [Workout ID](/wearables/providers/data-attributions#workout-id) and [Sport](/wearables/providers/data-attributions#sport) attributions.

<Accordion icon="heart" iconType="duotone" title="Details" defaultOpen>
  For more information, check out:

  #### Data Events

  * the [Workout Distance data events](/event-catalog/daily.data.workout_distance.created) in the Event Catalog;
  * the [Workout Swimming Stroke data events](/event-catalog/daily.data.workout_swimming_stroke.created) in the Event Catalog;
  * the [Heart Rate Recovery One Minute data events](/event-catalog/daily.data.heart_rate_recovery_one_minute.created) in the Event Catalog;

  #### Data access API

  * the [Get Workout Distance](/api-reference/data/timeseries/workout-distance) endpoint documentation;
  * the [Get Workout Swimming Stroke](/api-reference/data/timeseries/workout-swimming-stroke) endpoint documentation; and
  * the [Get Heart Rate Recovery One Minute](/api-reference/data/timeseries/heart-rate-recovery-one-minute) endpoint documentation.
</Accordion>

### Summary Ingestion Timestamps (April 2025)

Activity, Body, Sleep, Sleep Cycle, Workout, Meal and Menstrual Cycle now expose ingestion timestamps:

| Field        | Remarks                                                                     |
| ------------ | --------------------------------------------------------------------------- |
| `created_at` | The time at which Junction first ingested this summary.                     |
| `updated_at` | The time at which Junction ingested the most recent update to this summary. |

<Accordion icon="heart" iconType="duotone" title="Details" defaultOpen>
  For more information, check out:

  #### Data Events

  * the [Activity data events](/event-catalog/daily.data.activity.created) in the Event Catalog;
  * the [Body data events](/event-catalog/daily.data.body.created) in the Event Catalog;
  * the [Sleep data events](/event-catalog/daily.data.sleep.created) in the Event Catalog;
  * the [Sleep Cycle data events](/event-catalog/daily.data.sleep_cycle.created) in the Event Catalog;
  * the [Workout data events](/event-catalog/daily.data.workouts.created) in the Event Catalog;
  * the [Menstrual Cycle data events](/event-catalog/daily.data.menstrual_cycle.created) in the Event Catalog; and
  * the [Meal data events](/event-catalog/daily.data.meal.created) in the Event Catalog.

  #### Data access API

  * the [Get Activity](/api-reference/data/activity/get-summary) endpoint documentation;
  * the [Get Body](/api-reference/data/body/get-summary) endpoint documentation;
  * the [Get Sleep](/api-reference/data/sleep/get-summary) endpoint documentation;
  * the [Get Sleep Cycle](/api-reference/data/sleep-cycle/get-summary) endpoint documentation;
  * the [Get Workout](/api-reference/data/workouts/get-summary) endpoint documentation;
  * the [Get Menstrual Cycle](/api-reference/data/menstrual-cycle/get-summary) endpoint documentation; and
  * the [Get Meal](/api-reference/data/meal/get-summary) endpoint documentation.
</Accordion>

### Expanded Apple HealthKit data type coverage (March 2025)

Junction iOS SDK 1.5.0 has expanded the HealthKit data type coverage:

| Type                 | Remarks                                                                                                                                                                                                                                                                                                                                 |
| -------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Profile summary      | Wheelchair Mode usage                                                                                                                                                                                                                                                                                                                   |
| Activity summary     | Wheelchair Mode support (distance and push count)                                                                                                                                                                                                                                                                                       |
| Body summary         | Lean Body Mass, Body Mass Index, Waist Circumference                                                                                                                                                                                                                                                                                    |
| Timeseries resources | Lean Body Mass, Body Mass Index, Waist Circumference, Wheelchair Push, Distance (Wheelchair Mode support), Stand Hour, Stand Duration, Sleep Apnea Alert, Sleep Breathing Disturbance, FEV1, Forced Vital Capacity, Peak Expiratory Flow Rate, Inhaler Usage, Fall, UV Exposure, Daylight Exposure, Handwashing, Basal Body Temperature |

<Accordion icon="heart" iconType="duotone" title="Details" defaultOpen>
  For more information, check out:

  #### Data Events

  * the [Profile data events](/event-catalog/daily.data.profile.created) in the Event Catalog;
  * the [Activity data events](/event-catalog/daily.data.activity.created) in the Event Catalog;
  * the [Body data events](/event-catalog/daily.data.body.created) in the Event Catalog;
  * the [Lean Body Mass data events](/event-catalog/daily.data.lean_body_mass.created) in the Event Catalog;
  * the [Body Mass Index data events](/event-catalog/daily.data.body_mass_index.created) in the Event Catalog;
  * the [Waist Circumference data events](/event-catalog/daily.data.waist_circumference.created) in the Event Catalog;
  * the [Wheelchair Push data events](/event-catalog/daily.data.wheelchair_push.created) in the Event Catalog;
  * the [Distance data events](/event-catalog/daily.data.distance.created) in the Event Catalog;
  * the [Stand Hour data events](/event-catalog/daily.data.stand_hour.created) in the Event Catalog;
  * the [Stand Duration data events](/event-catalog/daily.data.stand_duration.created) in the Event Catalog;
  * the [Sleep Apnea Alert data events](/event-catalog/daily.data.sleep_apnea_alert.created) in the Event Catalog;
  * the [Sleep Breathing Disturbance data events](/event-catalog/daily.data.sleep_breathing_disturbance.created) in the Event Catalog;
  * the [FEV1 data events](/event-catalog/daily.data.forced_expiratory_volume_1.created) in the Event Catalog;
  * the [Forced Vital Capacity data events](/event-catalog/daily.data.forced_vital_capacity.created) in the Event Catalog;
  * the [Peak Expiratory Flow Rate data events](/event-catalog/daily.data.peak_expiratory_flow_rate.created) in the Event Catalog;
  * the [Inhaler Usage data events](/event-catalog/daily.data.inhaler_usage.created) in the Event Catalog;
  * the [Fall data events](/event-catalog/daily.data.fall.created) in the Event Catalog;
  * the [UV Exposure data events](/event-catalog/daily.data.uv_exposure.created) in the Event Catalog;
  * the [Daylight Exposure data events](/event-catalog/daily.data.daylight_exposure.created) in the Event Catalog;
  * the [Handwashing data events](/event-catalog/daily.data.handwashing.created) in the Event Catalog; and
  * the [Basal Body Temperature data events](/event-catalog/daily.data.basal_body_temperature.created) in the Event Catalog.

  #### Data access API

  * the [Get Profile](/api-reference/data/profile/get-summary) endpoint documentation;
  * the [Get Activity](/api-reference/data/activity/get-summary) endpoint documentation;
  * the [Get Body](/api-reference/data/body/get-summary) endpoint documentation;
  * the [Get Lean Body Mass](/api-reference/data/timeseries/lean-body-mass) endpoint documentation;
  * the [Get Body Mass Index](/api-reference/data/timeseries/body-mass-index) endpoint documentation;
  * the [Get Waist Circumference](/api-reference/data/timeseries/waist-circumference) endpoint documentation;
  * the [Get Wheelchair Push](/api-reference/data/timeseries/wheelchair-push) endpoint documentation;
  * the [Get Distance](/api-reference/data/timeseries/distance) endpoint documentation;
  * the [Get Stand Hour](/api-reference/data/timeseries/stand-hour) endpoint documentation;
  * the [Get Stand Duration](/api-reference/data/timeseries/stand-duration) endpoint documentation;
  * the [Get Sleep Apnea Alert](/api-reference/data/timeseries/sleep-apnea-alert) endpoint documentation;
  * the [Get Sleep Breathing Disturbance](/api-reference/data/timeseries/sleep-breathing-disturbance) endpoint documentation;
  * the [Get FEV1](/api-reference/data/timeseries/forced-expiratory-volume-1) endpoint documentation;
  * the [Get Forced Vital Capacity](/api-reference/data/timeseries/forced-vital-capacity) endpoint documentation;
  * the [Get Peak Expiratory Flow Rate](/api-reference/data/timeseries/peak-expiratory-flow-rate) endpoint documentation;
  * the [Get Inhaler Usage](/api-reference/data/timeseries/inhaler-usage) endpoint documentation;
  * the [Get Fall](/api-reference/data/timeseries/fall) endpoint documentation;
  * the [Get UV Exposure](/api-reference/data/timeseries/uv-exposure) endpoint documentation;
  * the [Get Daylight Exposure](/api-reference/data/timeseries/daylight-exposure) endpoint documentation;
  * the [Get Handwashing](/api-reference/data/timeseries/handwashing) endpoint documentation; and
  * the [Get Basal Body Temperature](/api-reference/data/timeseries/basal-body-temperature) endpoint documentation.
</Accordion>

### Improved LibreView practice connection process (Jan 2025)

You can now connect LibreView patients in to [46 regions in the EU environment](/wearables/guides/abbott-libreview#vital-eu-region)
and [8 regions in the US environment](/wearables/guides/abbott-libreview#vital-us-region).

<Accordion icon="link" iconType="duotone" title="Details" defaultOpen>
  Previously, the Link API and Link Widget listed only the regions to which our practice account was registered. However, these
  practice accounts can often connect to patients in a larger geographical area beyond the region of registration. For example,
  patients in most EMEA countries can connect through our Netherlands practice account.

  Therefore, we have now changed:

  1. Link Widget to display an exhaustive list of regions which our practice account can reach; and
  2. Link API to accept any ISO 3166-1 code that is on the list.

  In other words, say if you have a patient domiciled in Belgium, it is no longer necessary to teach them to choose "Netherlands" when
  connecting through the Link Widget. They can now intuitively choose "Belgium" when asked by the Link Widget.

  Check out the [Abbott LibreView](/wearables/guides/abbott-libreview) guide and
  the [Connect Email Provider](/api-reference/link/link-email-provider) endpoint
  for more information.
</Accordion>

### Electrocardiogram, Heart Rate Alert and AFib Burden (Dec 2024)

Vital now supports collecting Electrocardiogram (ECG) data and a couple of related data points from a set of providers:

| Resource                                                | Apple HealthKit <sup>\[3]</sup> | Fitbit            | Withings          | Kardia            |
| ------------------------------------------------------- | ------------------------------- | ----------------- | ----------------- | ----------------- |
| Electrocardiogram Summary<br />`electrocardiogram`      | ✅                               | -                 | ✅                 | ✅                 |
| ECG Voltage timeseries<br />`electrocardiogram_voltage` | ✅                               | -                 | ✅                 | ✅                 |
| Heart Rate Alert<br />`heart_rate_alert`                | ✅ <sup>\[1]</sup>               | ✅ <sup>\[2]</sup> | ✅ <sup>\[2]</sup> | ✅ <sup>\[2]</sup> |
| AFib Burden<br />`afib_burden`                          | ✅                               | -                 | -                 | -                 |

<Info>
  <sup>\[1]</sup> Irregular rhythm alerts, high heart rate alerts and low heart rate alerts.<br />
  <sup>\[2]</sup> Irregular rhythm alerts only.<br />
  <sup>\[3]</sup> Requires Vital iOS SDK 1.3.0+, Vital Flutter SDK 4.4.0+ or Vital React Native SDK 5.1.0+.
</Info>

<Accordion icon="heart" iconType="duotone" title="Details" defaultOpen>
  For more information, check out:

  * the [Get Electrocardiogram](/api-reference/data/electrocardiogram/get-summary) endpoint documentation;
  * the [Get Electrocardiogram Voltage](/api-reference/data/timeseries/electrocardiogram-voltage) endpoint documentation;
  * the [Get Heart Rate Alert](/api-reference/data/timeseries/heart-rate-alert) endpoint documentation; and
  * the [Get AFib Burden](/api-reference/data/timeseries/afib-burden) endpoint documentation;
  * the [Electrocardiogram data events](/event-catalog/daily.data.electrocardiogram.created) in the Event Catalog;
  * the [Electrocardiogram Voltage data events](/event-catalog/daily.data.electrocardiogram_voltage.created) in the Event Catalog;
  * the [Heart Rate Alert data events](/event-catalog/daily.data.heart_rate_alert.created) in the Event Catalog; and
  * the [AFib Burden data events](/event-catalog/daily.data.afib_burden.created) in the Event Catalog.
</Accordion>

### Sleep Cycle Summary Type (Nov 2024)

We are introducing a new Sleep Cycle summary type (`sleep_cycle`) which captures the detailed hypnogram of a sleep session.
The existing hyponogram timeseries type is deprecated in favour of this new summary type.

<Accordion icon="moon" iconType="duotone" title="Details" defaultOpen>
  Check out the [Get Sleep Cycle](/api-reference/data/sleep-cycle/get-summary) endpoint and
  the [Sleep Cycle data events](/event-catalog/daily.data.sleep_cycle.created) in the Event Catalog
  for more information.
</Accordion>

### Body Summary model extension (Nov 2024)

The Body Summary model now includes 4 new fields:

* `water_percentage` - The percentage of water in the body.
* `muscle_mass_percentage` - The percentage of muscle mass in the body.
* `visceral_fat_index` - Provider's score of visceral fat levels.
* `bone_mass_percentage` -  The percentage of bone mass in the body.

At the time of writing all four are only available from the Withings provider.

<Accordion icon="chart-scatter" iconType="duotone" title="Details" defaultOpen>
  Check out the [Get Body Summary](/api-reference/body/get-summary) endpoint and
  the [Body Created](/event-catalog/daily.data.body.created) event for more information.
</Accordion>

### Sleep Type (Nov 2024)

New Sleep summaries now have a new *Sleep Type* field.

<Accordion icon="moon" iconType="duotone" title="Details" defaultOpen>
  Vital maps the Sleep Type from the source provider whenever possible. If this is unavailable at source,
  Vital infers the Sleep Type based on the sleep session duration.

  | Sleep Type         | Description                                              |
  | ------------------ | -------------------------------------------------------- |
  | `long_sleep`       | >=3 hours of sleep                                       |
  | `short_sleep`      | \<3 hours of sleep                                       |
  | `acknowledged_nap` | User-acknowledged naps, typically under 3 hours of sleep |
  | `unknown`          | The sleep session recording is ongoing.                  |

  Check out the [Get Sleep endpoint](/api-reference/data/sleep/get-summary) and the [Sleep data events](/event-catalog/daily.data.sleep.created)
  in the Event Catalog for more information.
</Accordion>

### Apple HealthKit data sync improvements (Aug 2024)

An overhauled Apple HealthKit sync engine is now available across all Vital Mobile SDK platforms.
The changes bring historical data sync incrementality, prioritization, network resiliency and reduced resource usage.

<Accordion icon="apple" iconType="duotone" title="Details" defaultOpen>
  1. Most resources now use a resumable sync & upload process.

     * This enables the SDK to make constant forward progress, especially when you have specified a very large historical pull stage (60-365 days)
       through the [Team Data Pull Preferences](/api-reference/org-management/team-data-pull-preferences/upsert-team-data-pull-preferences) API.

  2. The SDK now prioritises syncing of summary types over timeseries data.

     * During the historical pull stage, all timeseries resources would be suppressed until all the summary types have been successfully uploaded.

     * After the historical pull stage, the SDK would make forward progress on summary types, before it proceeds to deal with the more CPU-time consuming timeseries data that are more prone to operating system throttling.

  3. With an updated iOS App Target configuration, the SDK would now self-register as a `BGProcessingTask` or `BGHealthResearchTask` (iOS 17+) to the iOS BackgroundTasks framework.

     * This would provide the SDK an additional opportunity to complete any resource sync that is not able to complete during normal HealthKit background delivery.

     * Please refer to the [Apple HealthKit guide](https://docs.tryvital.io/wearables/guides/apple-healthkit#1-setup-app-entitlements) on how to update your iOS App Target configuration in Xcode.

  | Platform     | Release Note                                                                                      |
  | ------------ | ------------------------------------------------------------------------------------------------- |
  | Native iOS   | [vital-ios 1.2.2](https://github.com/tryVital/vital-ios/releases/tag/1.2.2)                       |
  | Flutter      | [vital-flutter 4.2.1](https://github.com/tryVital/vital-flutter/releases/tag/vital_health-v4.2.1) |
  | React Native | [vital-react-native 4.2.1](https://github.com/tryVital/vital-react-native/releases/tag/4.2.1)     |
</Accordion>

### Menstrual Cycle Tracking (July 2024)

Menstrual cycle tracking data can now be collected through the Apple HealthKit and Android
Health Connect integrations.

<Accordion icon="venus" iconType="duotone" title="Details" defaultOpen>
  Ask for data permission on the `MenstrualCycle` resource from the user through the Vital Health SDK.

  Check out the [Get Menstrual Cycles](/api-reference/menstrual-cycle/get-summary) endpoint and
  the [Menstrual Cycle data events](/event-catalog/daily.data.menstrual_cycle.created) in the Event Catalog
  for more information.
</Accordion>

### Steps count in workouts (May 2024)

Workouts now include the total steps count during the session (if available).

<Accordion icon="tag" iconType="duotone" title="Details" defaultOpen>
  Check out the [Get Workouts](/api-reference/workouts/get-summary) endpoint and
  the [Workout Created](/event-catalog/daily.data.workouts.created) event for more information.
</Accordion>

### New Abbott LibreView integration (May 2024)

Vital has introduced an new Abbott LibreView provider (`abbott_libreview`). It uses password authentication,
accepting LibreView patient account credentials.

<Accordion icon="tag" iconType="duotone" title="Details" defaultOpen>
  This is an alternative option to our practice-based Freestyle Libre provider (`freestyle_libre`).

  With `abbott_libreview`, Vital uses the provided LibreView patient account credentials to connect directly
  to LibreView. There is no involvement of a LibreView practice in this integration.

  Note that both practice-based and patient-based connections would continue to be supported in parallel. The
  `abbott_libreview` integration does not replace the `freestyle_libre` integration.

  Check out the [Abbott LibreView / Freestyle Libre](/wearables/guides/abbott-libreview) guide for more information.
</Accordion>

### Removed Fitbit and Oura required scopes (May 2024)

The Fitbit profile scope and Oura email scope are no longer required for establishing connections.

For Fitbit specifically, please be aware of the [updated Fitbit Time Zone resolution precedences](/wearables/guides/fitbit#time-zone-resolution). When
your user refuses to grant both the activity and the profile scope, Fitbit data are more likely be timestamped incorrectly in UTC time basis
due to inaccurate or unavailable time zone information.

<Accordion icon="tag" iconType="duotone" title="Details" defaultOpen>
  We have now updated our Fitbit and Oura integrations not to depend on these scopes to be **minimally functional**.

  If you are interested in requiring your users to grant certain scopes when connecting an OAuth provider, check out the
  [Team Scope Requirements](/changelog/wearables/api#team-scope-requirements-apr-24) changelog entry and
  the [Set Team Scope Requirements](/api-reference/org-management/team-scope-requirements/get-team-scope-requirements) endpoint for more information.
</Accordion>

### Freestyle Libre: India region (Apr 2024)

Our Freestyle Libre integration now supports the LibreView India region.

<Accordion icon="tag" iconType="duotone" title="Details" defaultOpen>
  Check out the [Freestyle Libre](/wearables/guides/freestyle#custom-practice-enterprise-only) documentation for more information.
</Accordion>

### Health Connect Background Sync (Mar 2024)

Vital Mobile SDK now includes an experimental Background Sync feature for Android Health Connect.

<Accordion icon="robot" iconType="duotone" title="Details" defaultOpen>
  The feature is available through the following Vital Mobile SDK releases:

  | Platform       | Version |
  | -------------- | ------- |
  | Native Android | 2.0.0+  |
  | Flutter        | 3.2.0+  |
  | React Native   | 3.1.0+  |

  Check out the following documentation for information, integration guidance as well as caveats
  of the experimental Background Sync :

  * [Vital Health SDK: Automatic Data Sync](/wearables/sdks/vital-health#automatic-data-sync) for a general overview
  * [Android Health Connect integration guide](/wearables/guides/android-health-connect#background-sync-experimental), which includes guidance on the experimental Background Sync feature.
</Accordion>

### Expanded Source Type attribution (Feb 2024)

Data from Fitbit, Oura, Garmin and Freestyle Libre now comes with Source Type attributions.

<Accordion icon="tag" iconType="duotone" title="Details" defaultOpen>
  Check out the [Data Attributions](/wearables/providers/data-attributions#source-type) documentation for more information.
</Accordion>


# daily.data.activity.created
Source: https://docs.junction.com/event-catalog/daily.data.activity.created


# daily.data.activity.updated
Source: https://docs.junction.com/event-catalog/daily.data.activity.updated


# daily.data.basal_body_temperature.created
Source: https://docs.junction.com/event-catalog/daily.data.basal_body_temperature.created


# daily.data.basal_body_temperature.updated
Source: https://docs.junction.com/event-catalog/daily.data.basal_body_temperature.updated


# daily.data.blood_oxygen.created
Source: https://docs.junction.com/event-catalog/daily.data.blood_oxygen.created


# daily.data.blood_oxygen.updated
Source: https://docs.junction.com/event-catalog/daily.data.blood_oxygen.updated


# daily.data.blood_pressure.created
Source: https://docs.junction.com/event-catalog/daily.data.blood_pressure.created


# daily.data.blood_pressure.updated
Source: https://docs.junction.com/event-catalog/daily.data.blood_pressure.updated


# daily.data.body.created
Source: https://docs.junction.com/event-catalog/daily.data.body.created


# daily.data.body.updated
Source: https://docs.junction.com/event-catalog/daily.data.body.updated


# daily.data.body_mass_index.created
Source: https://docs.junction.com/event-catalog/daily.data.body_mass_index.created


# daily.data.body_mass_index.updated
Source: https://docs.junction.com/event-catalog/daily.data.body_mass_index.updated


# daily.data.body_temperature.created
Source: https://docs.junction.com/event-catalog/daily.data.body_temperature.created


# daily.data.body_temperature.updated
Source: https://docs.junction.com/event-catalog/daily.data.body_temperature.updated


# daily.data.body_temperature_delta.created
Source: https://docs.junction.com/event-catalog/daily.data.body_temperature_delta.created


# daily.data.body_temperature_delta.updated
Source: https://docs.junction.com/event-catalog/daily.data.body_temperature_delta.updated


# daily.data.caffeine.created
Source: https://docs.junction.com/event-catalog/daily.data.caffeine.created


# daily.data.caffeine.updated
Source: https://docs.junction.com/event-catalog/daily.data.caffeine.updated


# daily.data.calories_active.created
Source: https://docs.junction.com/event-catalog/daily.data.calories_active.created


# daily.data.calories_active.updated
Source: https://docs.junction.com/event-catalog/daily.data.calories_active.updated


# daily.data.calories_basal.created
Source: https://docs.junction.com/event-catalog/daily.data.calories_basal.created


# daily.data.calories_basal.updated
Source: https://docs.junction.com/event-catalog/daily.data.calories_basal.updated


# daily.data.carbohydrates.created
Source: https://docs.junction.com/event-catalog/daily.data.carbohydrates.created


# daily.data.carbohydrates.updated
Source: https://docs.junction.com/event-catalog/daily.data.carbohydrates.updated


# daily.data.daylight_exposure.created
Source: https://docs.junction.com/event-catalog/daily.data.daylight_exposure.created


# daily.data.daylight_exposure.updated
Source: https://docs.junction.com/event-catalog/daily.data.daylight_exposure.updated


# daily.data.distance.created
Source: https://docs.junction.com/event-catalog/daily.data.distance.created


# daily.data.distance.updated
Source: https://docs.junction.com/event-catalog/daily.data.distance.updated


# daily.data.electrocardiogram_voltage.created
Source: https://docs.junction.com/event-catalog/daily.data.electrocardiogram_voltage.created


# daily.data.electrocardiogram_voltage.updated
Source: https://docs.junction.com/event-catalog/daily.data.electrocardiogram_voltage.updated


# daily.data.fall.created
Source: https://docs.junction.com/event-catalog/daily.data.fall.created


# daily.data.fall.updated
Source: https://docs.junction.com/event-catalog/daily.data.fall.updated


# daily.data.fat.created
Source: https://docs.junction.com/event-catalog/daily.data.fat.created


# daily.data.fat.updated
Source: https://docs.junction.com/event-catalog/daily.data.fat.updated


# daily.data.floors_climbed.created
Source: https://docs.junction.com/event-catalog/daily.data.floors_climbed.created


# daily.data.floors_climbed.updated
Source: https://docs.junction.com/event-catalog/daily.data.floors_climbed.updated


# daily.data.forced_expiratory_volume_1.created
Source: https://docs.junction.com/event-catalog/daily.data.forced_expiratory_volume_1.created


# daily.data.forced_expiratory_volume_1.updated
Source: https://docs.junction.com/event-catalog/daily.data.forced_expiratory_volume_1.updated


# daily.data.forced_vital_capacity.created
Source: https://docs.junction.com/event-catalog/daily.data.forced_vital_capacity.created


# daily.data.forced_vital_capacity.updated
Source: https://docs.junction.com/event-catalog/daily.data.forced_vital_capacity.updated


# daily.data.glucose.created
Source: https://docs.junction.com/event-catalog/daily.data.glucose.created


# daily.data.glucose.updated
Source: https://docs.junction.com/event-catalog/daily.data.glucose.updated


# daily.data.handwashing.created
Source: https://docs.junction.com/event-catalog/daily.data.handwashing.created


# daily.data.handwashing.updated
Source: https://docs.junction.com/event-catalog/daily.data.handwashing.updated


# daily.data.heart_rate_recovery_one_minute.created
Source: https://docs.junction.com/event-catalog/daily.data.heart_rate_recovery_one_minute.created


# daily.data.heart_rate_recovery_one_minute.updated
Source: https://docs.junction.com/event-catalog/daily.data.heart_rate_recovery_one_minute.updated


# daily.data.heartrate.created
Source: https://docs.junction.com/event-catalog/daily.data.heartrate.created


# daily.data.heartrate.updated
Source: https://docs.junction.com/event-catalog/daily.data.heartrate.updated


# daily.data.hrv.created
Source: https://docs.junction.com/event-catalog/daily.data.hrv.created


# daily.data.hrv.updated
Source: https://docs.junction.com/event-catalog/daily.data.hrv.updated


# daily.data.inhaler_usage.created
Source: https://docs.junction.com/event-catalog/daily.data.inhaler_usage.created


# daily.data.inhaler_usage.updated
Source: https://docs.junction.com/event-catalog/daily.data.inhaler_usage.updated


# daily.data.insulin_injection.created
Source: https://docs.junction.com/event-catalog/daily.data.insulin_injection.created


# daily.data.insulin_injection.updated
Source: https://docs.junction.com/event-catalog/daily.data.insulin_injection.updated


# daily.data.lean_body_mass.created
Source: https://docs.junction.com/event-catalog/daily.data.lean_body_mass.created


# daily.data.lean_body_mass.updated
Source: https://docs.junction.com/event-catalog/daily.data.lean_body_mass.updated


# daily.data.meal.created
Source: https://docs.junction.com/event-catalog/daily.data.meal.created


# daily.data.meal.updated
Source: https://docs.junction.com/event-catalog/daily.data.meal.updated


# daily.data.menstrual_cycle.created
Source: https://docs.junction.com/event-catalog/daily.data.menstrual_cycle.created


# daily.data.menstrual_cycle.updated
Source: https://docs.junction.com/event-catalog/daily.data.menstrual_cycle.updated


# daily.data.mindfulness_minutes.created
Source: https://docs.junction.com/event-catalog/daily.data.mindfulness_minutes.created


# daily.data.mindfulness_minutes.updated
Source: https://docs.junction.com/event-catalog/daily.data.mindfulness_minutes.updated


# daily.data.note.created
Source: https://docs.junction.com/event-catalog/daily.data.note.created


# daily.data.note.updated
Source: https://docs.junction.com/event-catalog/daily.data.note.updated


# daily.data.peak_expiratory_flow_rate.created
Source: https://docs.junction.com/event-catalog/daily.data.peak_expiratory_flow_rate.created


# daily.data.peak_expiratory_flow_rate.updated
Source: https://docs.junction.com/event-catalog/daily.data.peak_expiratory_flow_rate.updated


# daily.data.profile.created
Source: https://docs.junction.com/event-catalog/daily.data.profile.created


# daily.data.respiratory_rate.created
Source: https://docs.junction.com/event-catalog/daily.data.respiratory_rate.created


# daily.data.respiratory_rate.updated
Source: https://docs.junction.com/event-catalog/daily.data.respiratory_rate.updated


# daily.data.sleep.created
Source: https://docs.junction.com/event-catalog/daily.data.sleep.created


# daily.data.sleep.updated
Source: https://docs.junction.com/event-catalog/daily.data.sleep.updated


# daily.data.sleep_apnea_alert.created
Source: https://docs.junction.com/event-catalog/daily.data.sleep_apnea_alert.created


# daily.data.sleep_apnea_alert.updated
Source: https://docs.junction.com/event-catalog/daily.data.sleep_apnea_alert.updated


# daily.data.sleep_breathing_disturbance.created
Source: https://docs.junction.com/event-catalog/daily.data.sleep_breathing_disturbance.created


# daily.data.sleep_breathing_disturbance.updated
Source: https://docs.junction.com/event-catalog/daily.data.sleep_breathing_disturbance.updated


# daily.data.sleep_cycle.created
Source: https://docs.junction.com/event-catalog/daily.data.sleep_cycle.created


# daily.data.sleep_cycle.updated
Source: https://docs.junction.com/event-catalog/daily.data.sleep_cycle.updated


# daily.data.stand_duration.created
Source: https://docs.junction.com/event-catalog/daily.data.stand_duration.created


# daily.data.stand_duration.updated
Source: https://docs.junction.com/event-catalog/daily.data.stand_duration.updated


# daily.data.stand_hour.created
Source: https://docs.junction.com/event-catalog/daily.data.stand_hour.created


# daily.data.stand_hour.updated
Source: https://docs.junction.com/event-catalog/daily.data.stand_hour.updated


# daily.data.steps.created
Source: https://docs.junction.com/event-catalog/daily.data.steps.created


# daily.data.steps.updated
Source: https://docs.junction.com/event-catalog/daily.data.steps.updated


# daily.data.stress_level.created
Source: https://docs.junction.com/event-catalog/daily.data.stress_level.created


# daily.data.stress_level.updated
Source: https://docs.junction.com/event-catalog/daily.data.stress_level.updated


# daily.data.uv_exposure.created
Source: https://docs.junction.com/event-catalog/daily.data.uv_exposure.created


# daily.data.uv_exposure.updated
Source: https://docs.junction.com/event-catalog/daily.data.uv_exposure.updated


# daily.data.vo2_max.created
Source: https://docs.junction.com/event-catalog/daily.data.vo2_max.created


# daily.data.vo2_max.updated
Source: https://docs.junction.com/event-catalog/daily.data.vo2_max.updated


# daily.data.waist_circumference.created
Source: https://docs.junction.com/event-catalog/daily.data.waist_circumference.created


# daily.data.waist_circumference.updated
Source: https://docs.junction.com/event-catalog/daily.data.waist_circumference.updated


# daily.data.water.created
Source: https://docs.junction.com/event-catalog/daily.data.water.created


# daily.data.water.updated
Source: https://docs.junction.com/event-catalog/daily.data.water.updated


# daily.data.weight.created
Source: https://docs.junction.com/event-catalog/daily.data.weight.created


# daily.data.weight.updated
Source: https://docs.junction.com/event-catalog/daily.data.weight.updated


# daily.data.wheelchair_push.created
Source: https://docs.junction.com/event-catalog/daily.data.wheelchair_push.created


# daily.data.wheelchair_push.updated
Source: https://docs.junction.com/event-catalog/daily.data.wheelchair_push.updated


# daily.data.workout_distance.created
Source: https://docs.junction.com/event-catalog/daily.data.workout_distance.created


# daily.data.workout_distance.updated
Source: https://docs.junction.com/event-catalog/daily.data.workout_distance.updated


# daily.data.workout_duration.created
Source: https://docs.junction.com/event-catalog/daily.data.workout_duration.created


# daily.data.workout_duration.updated
Source: https://docs.junction.com/event-catalog/daily.data.workout_duration.updated


# daily.data.workout_stream.created
Source: https://docs.junction.com/event-catalog/daily.data.workout_stream.created


# daily.data.workout_stream.updated
Source: https://docs.junction.com/event-catalog/daily.data.workout_stream.updated


# daily.data.workout_swimming_stroke.created
Source: https://docs.junction.com/event-catalog/daily.data.workout_swimming_stroke.created


# daily.data.workout_swimming_stroke.updated
Source: https://docs.junction.com/event-catalog/daily.data.workout_swimming_stroke.updated


# daily.data.workouts.created
Source: https://docs.junction.com/event-catalog/daily.data.workouts.created


# daily.data.workouts.updated
Source: https://docs.junction.com/event-catalog/daily.data.workouts.updated


# historical.data.activity.created
Source: https://docs.junction.com/event-catalog/historical.data.activity.created


# historical.data.basal_body_temperature.created
Source: https://docs.junction.com/event-catalog/historical.data.basal_body_temperature.created


# historical.data.blood_oxygen.created
Source: https://docs.junction.com/event-catalog/historical.data.blood_oxygen.created


# historical.data.blood_pressure.created
Source: https://docs.junction.com/event-catalog/historical.data.blood_pressure.created


# historical.data.body.created
Source: https://docs.junction.com/event-catalog/historical.data.body.created


# historical.data.body_mass_index.created
Source: https://docs.junction.com/event-catalog/historical.data.body_mass_index.created


# historical.data.body_temperature.created
Source: https://docs.junction.com/event-catalog/historical.data.body_temperature.created


# historical.data.body_temperature_delta.created
Source: https://docs.junction.com/event-catalog/historical.data.body_temperature_delta.created


# historical.data.caffeine.created
Source: https://docs.junction.com/event-catalog/historical.data.caffeine.created


# historical.data.calories_active.created
Source: https://docs.junction.com/event-catalog/historical.data.calories_active.created


# historical.data.calories_basal.created
Source: https://docs.junction.com/event-catalog/historical.data.calories_basal.created


# historical.data.carbohydrates.created
Source: https://docs.junction.com/event-catalog/historical.data.carbohydrates.created


# historical.data.daylight_exposure.created
Source: https://docs.junction.com/event-catalog/historical.data.daylight_exposure.created


# historical.data.distance.created
Source: https://docs.junction.com/event-catalog/historical.data.distance.created


# historical.data.electrocardiogram_voltage.created
Source: https://docs.junction.com/event-catalog/historical.data.electrocardiogram_voltage.created


# historical.data.fall.created
Source: https://docs.junction.com/event-catalog/historical.data.fall.created


# historical.data.fat.created
Source: https://docs.junction.com/event-catalog/historical.data.fat.created


# historical.data.floors_climbed.created
Source: https://docs.junction.com/event-catalog/historical.data.floors_climbed.created


# historical.data.forced_expiratory_volume_1.created
Source: https://docs.junction.com/event-catalog/historical.data.forced_expiratory_volume_1.created


# historical.data.forced_vital_capacity.created
Source: https://docs.junction.com/event-catalog/historical.data.forced_vital_capacity.created


# historical.data.glucose.created
Source: https://docs.junction.com/event-catalog/historical.data.glucose.created


# historical.data.handwashing.created
Source: https://docs.junction.com/event-catalog/historical.data.handwashing.created


# historical.data.heart_rate_recovery_one_minute.created
Source: https://docs.junction.com/event-catalog/historical.data.heart_rate_recovery_one_minute.created


# historical.data.heartrate.created
Source: https://docs.junction.com/event-catalog/historical.data.heartrate.created


# historical.data.hrv.created
Source: https://docs.junction.com/event-catalog/historical.data.hrv.created


# historical.data.inhaler_usage.created
Source: https://docs.junction.com/event-catalog/historical.data.inhaler_usage.created


# historical.data.insulin_injection.created
Source: https://docs.junction.com/event-catalog/historical.data.insulin_injection.created


# historical.data.lean_body_mass.created
Source: https://docs.junction.com/event-catalog/historical.data.lean_body_mass.created


# historical.data.meal.created
Source: https://docs.junction.com/event-catalog/historical.data.meal.created


# historical.data.menstrual_cycle.created
Source: https://docs.junction.com/event-catalog/historical.data.menstrual_cycle.created


# historical.data.mindfulness_minutes.created
Source: https://docs.junction.com/event-catalog/historical.data.mindfulness_minutes.created


# historical.data.note.created
Source: https://docs.junction.com/event-catalog/historical.data.note.created


# historical.data.peak_expiratory_flow_rate.created
Source: https://docs.junction.com/event-catalog/historical.data.peak_expiratory_flow_rate.created


# historical.data.profile.created
Source: https://docs.junction.com/event-catalog/historical.data.profile.created


# historical.data.respiratory_rate.created
Source: https://docs.junction.com/event-catalog/historical.data.respiratory_rate.created


# historical.data.sleep.created
Source: https://docs.junction.com/event-catalog/historical.data.sleep.created


# historical.data.sleep_apnea_alert.created
Source: https://docs.junction.com/event-catalog/historical.data.sleep_apnea_alert.created


# historical.data.sleep_breathing_disturbance.created
Source: https://docs.junction.com/event-catalog/historical.data.sleep_breathing_disturbance.created


# historical.data.sleep_cycle.created
Source: https://docs.junction.com/event-catalog/historical.data.sleep_cycle.created


# historical.data.stand_duration.created
Source: https://docs.junction.com/event-catalog/historical.data.stand_duration.created


# historical.data.stand_hour.created
Source: https://docs.junction.com/event-catalog/historical.data.stand_hour.created


# historical.data.steps.created
Source: https://docs.junction.com/event-catalog/historical.data.steps.created


# historical.data.stress_level.created
Source: https://docs.junction.com/event-catalog/historical.data.stress_level.created


# historical.data.uv_exposure.created
Source: https://docs.junction.com/event-catalog/historical.data.uv_exposure.created


# historical.data.vo2_max.created
Source: https://docs.junction.com/event-catalog/historical.data.vo2_max.created


# historical.data.waist_circumference.created
Source: https://docs.junction.com/event-catalog/historical.data.waist_circumference.created


# historical.data.water.created
Source: https://docs.junction.com/event-catalog/historical.data.water.created


# historical.data.weight.created
Source: https://docs.junction.com/event-catalog/historical.data.weight.created


# historical.data.wheelchair_push.created
Source: https://docs.junction.com/event-catalog/historical.data.wheelchair_push.created


# historical.data.workout_distance.created
Source: https://docs.junction.com/event-catalog/historical.data.workout_distance.created


# historical.data.workout_duration.created
Source: https://docs.junction.com/event-catalog/historical.data.workout_duration.created


# historical.data.workout_swimming_stroke.created
Source: https://docs.junction.com/event-catalog/historical.data.workout_swimming_stroke.created


# historical.data.workouts.created
Source: https://docs.junction.com/event-catalog/historical.data.workouts.created


# labtest.appointment.updated
Source: https://docs.junction.com/event-catalog/labtest.appointment.updated


# labtest.order.created
Source: https://docs.junction.com/event-catalog/labtest.order.created


# labtest.order.updated
Source: https://docs.junction.com/event-catalog/labtest.order.updated


# labtest.result.critical
Source: https://docs.junction.com/event-catalog/labtest.result.critical


# provider.connection.created
Source: https://docs.junction.com/event-catalog/provider.connection.created


# provider.connection.error
Source: https://docs.junction.com/event-catalog/provider.connection.error


# Getting Support
Source: https://docs.junction.com/home/getting-support


## Support channels

When you encounter an issue which you cannot figure out, or an unexpected API error, you are
welcome to get in touch with Vital support through these channels:

* Email Support ([help@tryvital.io](mailto:help@tryvital.io))
* Vital Slack community support channel (#vital-support)
* Your dedicated Slack support channel (for Scale plan customers).

We appreciate as much context as possible when you raise an issue. This helps us understand your
issue, enabling a quicker investigation turnaround.

## I have an issue with...

### Anything in general

| Item                  | Remarks                                    |
| --------------------- | ------------------------------------------ |
| Your Vital Team ID    | -                                          |
| Your Vital region     | US or EU                                   |
| The Vital User ID     | ...if the issue occurs on a specific user. |
| The Vital environment | Sandbox, Production or both                |

### Vital Mobile SDK

| Item               | Remarks                              |
| ------------------ | ------------------------------------ |
| Vital SDK Platform | Native, React Native, Flutter        |
| Vital SDK Version  | -                                    |
| Device OS          | Android or iOS                       |
| Device OS Version  | -                                    |
| Auth Scheme        | Vital Sign-In Token, or Team API Key |

### A Vital API endpoint

When you encounter an unexpected response from the Vital API, please provide
the `traceparent` header value from the HTTP response you received if possible. This
helps us narrow down the context surrounding your issue.

A `traceparent` response header looks like this:

```
traceparent: 00-0af7651916cd43dd8448eb211c80319c-b7ad6b7169203331-01
```

It contains a trace ID that links back to the original API request:

* If you make the API request without a `traceparent` header, Vital's infrastructure
  assigns a unique trace ID to it on entry.

* If your API request is instrumented using OpenTelemetry, W3C Trace Context or other
  interoperable tools, these tools would inject a `traceparent` header automatically.
  Vital's infrastructure would adopt the trace ID from your API request.

### A wearables provider connection

Before reporting an issue, we encourage you to try out the following steps:

<Steps>
  <Step title="Check the resource availability" icon="circle-question">
    The [Get User Connections](https://docs.tryvital.io/api-reference/user/get-users-connected-providers) endpoint
    reports the resource availability of all the connections. More specifically, it tells you:

    1. What resources are available for a given user connection
    2. Why each individual resource is available or unavailable, in terms of provider API access scopes.
  </Step>

  <Step title="Issues with historical pulls?" icon="clock-rotate-left">
    If you are having issues with historical data specifically, the [Historical Pull Introspection](https://docs.tryvital.io/api-reference/introspection/historical-pulls) endpoint
    provides a track record of historical pulls of all your user connections.
  </Step>

  <Step title="Issues with data availability?" icon="sparkles">
    If you have troubles with data availability in general, the [User Resource Introspection](https://docs.tryvital.io/api-reference/introspection/user-resources) endpoint
    is a live data ingestion record of all your user connections.

    <Note>
      This is inclusive of all historical data covered by the
      Historical Pull Introspection endpoint.
    </Note>
  </Step>
</Steps>

If you are not able to diagnose your issue using these tools, feel free to contact
Vital support for further assistance.


# Libraries
Source: https://docs.junction.com/home/libraries


We have created a few libraries to help you integrate with the Vital API. We'll continue to add support for more libraries as we add more devices. Email [support@tryvital.io](mailto:support@tryvital.io) for specific library support.

### Typed Bindings of Vital API

These typed bindings track the Vital API OpenAPI Schema.

|                                                                  |                          |
| ---------------------------------------------------------------- | ------------------------ |
| [vital-java](https://github.com/tryVital/vital-java)             | Vital API Java client    |
| [vital-go](https://github.com/tryVital/vital-go)                 | Vital API Go client      |
| [vital-node](https://www.npmjs.com/package/@tryvital/vital-node) | Vital API Node.js client |
| [vital-python](https://pypi.org/project/vital)                   | Vital API Python client  |

### Mobile SDK

|                                                                      |                                  |
| -------------------------------------------------------------------- | -------------------------------- |
| [vital-ios](https://github.com/tryVital/vital-ios)                   | Vital iOS Client                 |
| [vital-android](https://github.com/tryVital/vital-android)           | Vital Android Client             |
| [vital-flutter](https://github.com/tryVital/vital-flutter)           | Vital Flutter Client             |
| [vital-react-native](https://github.com/tryVital/vital-react-native) | Vital React Native Client        |
| [vital-connect](https://github.com/tryVital/vital-connect-rn)        | Whitelabel App using Vital's API |

### Web SDK

|                                                                  |                                     |
| ---------------------------------------------------------------- | ----------------------------------- |
| [vital-link](https://www.npmjs.com/package/@tryvital/vital-link) | React Library for initializing link |


# Quickstart
Source: https://docs.junction.com/home/quickstart

A quick introduction to building with Vital

## 1. API keys

Let's test out running Vital locally by cloning the [Quickstart app](https://github.com/tryVital/quickstart).
You can get API keys by signing up in the [Dashboard](https://app.tryvital.io).
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](/api-details/regions).

To create a team and get your API keys, you first need to sign up for a Vital account in the [Dashboard](https://app.tryvital.io).

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](/api-details/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.

<Note>
  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](mailto:support@tryvital.io)
</Note>

| 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](https://github.com/tryVital/quickstart),
customizing the `.env` file with your own Vital `API_KEY` and finally, building and running the app.

```bash 1. Clone quickstart and run locally
# 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`.

```bash 2. Run quickstart frontend
# 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.

<Warning>
  Personally identifiable information (PII), such as an email address or phone number, should not be used as input for the `user_id` parameter.
</Warning>

Enter a new `client_user_id` and tap Create:

<img src="https://mintcdn.com/vital/img/quickstart.jpg?maxW=2942&auto=format&n=nR1fvAlwouZ87zVb&q=85&s=4190b8c98c2a4b4d652019f8163ba068" alt="quickstart" width="2942" height="1458" data-path="img/quickstart.jpg" srcset="https://mintcdn.com/vital/img/quickstart.jpg?w=280&maxW=2942&auto=format&n=nR1fvAlwouZ87zVb&q=85&s=798685b14911c60e41c96ff97e7d1d1f 280w, https://mintcdn.com/vital/img/quickstart.jpg?w=560&maxW=2942&auto=format&n=nR1fvAlwouZ87zVb&q=85&s=a0c6ccd2902e57ff7dc95cb4a31fdb96 560w, https://mintcdn.com/vital/img/quickstart.jpg?w=840&maxW=2942&auto=format&n=nR1fvAlwouZ87zVb&q=85&s=30891b67fecd98d77f744c8a20edc180 840w, https://mintcdn.com/vital/img/quickstart.jpg?w=1100&maxW=2942&auto=format&n=nR1fvAlwouZ87zVb&q=85&s=938c3e8b8cd8aafbd6115cfb87fdbc47 1100w, https://mintcdn.com/vital/img/quickstart.jpg?w=1650&maxW=2942&auto=format&n=nR1fvAlwouZ87zVb&q=85&s=68dceec360e073c84dc7e333c8a5a926 1650w, https://mintcdn.com/vital/img/quickstart.jpg?w=2500&maxW=2942&auto=format&n=nR1fvAlwouZ87zVb&q=85&s=e098156b65f1c6275b88452e972bffb7 2500w" data-optimize="true" data-opv="2" />

{" "}

This can also be achieved via the API as follows.

<CodeGroup>
  ```bash Creating a Vital user (bash)
  curl --request POST \
       --url {{BASE_URL}}/v2/user/ \
       --header 'Accept: application/json' \
       --header 'Content-Type: application/json' \
       --header 'x-vital-api-key: <YOUR_API_KEY>' \
       --data '{"client_user_id":"<YOUR_CLIENT_USER_ID>"}'
  ```

  ```js Node
  import { VitalClient, VitalEnvironment } from '@tryvital/vital-node';
  import { UserCreateBody } from '@tryvital/vital-node/api';

  const client = new VitalClient({
      apiKey: '<my_api_key>',
      environment: VitalEnvironment.Sandbox,
  });

  const request: UserCreateBody = {
      clientUserId: "<client_user_id>"
  }

  const data = await client.user.create(request)
  ```

  ```python Python
  from vital.client import Vital
  from vital.environment import VitalEnvironment

  client = Vital(
    api_key="YOUR_API_KEY",
    environment=VitalEnvironment.SANDBOX
  )

  data = client.user.create(client_user_id="<client_user_id>")
  ```

  ```java Java
  import com.vital.api.Vital;
  import com.vital.api.core.Environment;
  import com.vital.api.resources.user.requests.UserCreateBody;

  Vital vital = Vital.builder()
          .apiKey("YOUR_API_KEY")
          .environment(Environment.SANDBOX)
          .build();

  UserCreateBody request = UserCreateBody
       .builder()
       .clientUserId("<client_user_id>")
       .build();

  var data = vital.user().create(request);
  ```

  ```go Go
  import (
    "context"

    vital "github.com/tryVital/vital-go"
    vitalclient "github.com/tryVital/vital-go/client"
    "github.com/tryVital/vital-go/option"
  )

  client := vitalclient.NewClient(
    option.WithApiKey("<YOUR_API_KEY>"),
    option.WithBaseURL(vital.Environments.Sandbox),
  )

  request := &vital.UserCreateBody{
       ClientUserId: "<client_user_id>",
  }

  response, err := client.User.Create(context.TODO(), request)
  if err != nil {
    return err
  }
  fmt.Printf("Received data %s\n", response)
  ```

  ```swift Swift
  let user = try await VitalClient.shared.user.create(clientUserId)
  ```
</CodeGroup>

## 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](/wearables/connecting-providers/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.

```python Generating a Link Token
# 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.

```javascript Generating a Link Token
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:

<img src="https://mintcdn.com/vital/img/link_specific.png?maxW=2210&auto=format&n=nR1fvAlwouZ87zVb&q=85&s=4e10f38bffc71e2e54dc685bf6decb69" width="75%" alt="Link specific" width="2210" height="2232" data-path="img/link_specific.png" srcset="https://mintcdn.com/vital/img/link_specific.png?w=280&maxW=2210&auto=format&n=nR1fvAlwouZ87zVb&q=85&s=b6397cdedeb46ecacf54838c8a040cb6 280w, https://mintcdn.com/vital/img/link_specific.png?w=560&maxW=2210&auto=format&n=nR1fvAlwouZ87zVb&q=85&s=d01ad93552f3a0ed32dec2059399e434 560w, https://mintcdn.com/vital/img/link_specific.png?w=840&maxW=2210&auto=format&n=nR1fvAlwouZ87zVb&q=85&s=23eefdd7138bf5edfe4d2c0a14711695 840w, https://mintcdn.com/vital/img/link_specific.png?w=1100&maxW=2210&auto=format&n=nR1fvAlwouZ87zVb&q=85&s=da9047881a8c3be9b31b588906183ac5 1100w, https://mintcdn.com/vital/img/link_specific.png?w=1650&maxW=2210&auto=format&n=nR1fvAlwouZ87zVb&q=85&s=ca0deeb2d563a8cb73a00a97ba29ac8f 1650w, https://mintcdn.com/vital/img/link_specific.png?w=2500&maxW=2210&auto=format&n=nR1fvAlwouZ87zVb&q=85&s=f63d298515ddb1813edf87cae4aa79e1 2500w" data-optimize="true" data-opv="2" />

## 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**

<CodeGroup>
  ```python Python
  from vital.client import Vital
  from vital.environment import VitalEnvironment

  client = Vital(
    api_key="YOUR_API_KEY",
    environment=VitalEnvironment.SANDBOX
  )

  data = client.sleep.get(
    user_id="<user_id>", 
    start_date="2021-01-01", 
    end_date="2021-01-02"
  )
  ```

  ```javascript Node
  import { VitalClient, VitalEnvironment } from '@tryvital/vital-node';
  import { SleepGetRequest } from '@tryvital/vital-node/api';

  const client = new VitalClient({
      apiKey: '<my_api_key>',
      environment: VitalEnvironment.Sandbox,
  });

  const request: SleepGetRequest = {
      startDate: '2021-01-01',
      endDate: '2021-01-02',
  }

  const data = await client.sleep.get('user_id', request)
  ```

  ```java Java
  import com.vital.api.Vital;
  import com.vital.api.core.Environment;
  import com.vital.api.resources.sleep.requests.SleepGetRequest;

  Vital vital = Vital.builder()
          .apiKey("YOUR_API_KEY")
          .environment(Environment.SANDBOX)
          .build();

  SleepGetRequest request = SleepGetRequest
          .builder()
          .startDate("2021-01-01")
          .endDate("2021-01-02")
          .build();

  var data = vital.sleep().get("<user_id>", request);
  ```

  ```go Go
  import (
    "context"

    vital "github.com/tryVital/vital-go"
    vitalclient "github.com/tryVital/vital-go/client"
    "github.com/tryVital/vital-go/option"
  )

  EndDate := "2021-01-02"
  request := &vital.SleepGetRequest{
    StartDate: "2021-01-01",
    EndDate:   &EndDate,
  }

  response, err := client.Sleep.Get(
    context.TODO(), 
    "<user_id>", 
    request
  )
  if err != nil {
    return err
  }
  fmt.Printf("Received data %s\n", response)
  ```

  ```swift Swift
  let sleepData = try await VitalClient.shared.summary.sleep(userId, startDate, endDate)
  ```
</CodeGroup>

## 6. SDK's and Libraries

We offer different SDKs so you can start building your app right away:

|                                                                  |                                                      |
| ---------------------------------------------------------------- | ---------------------------------------------------- |
| [vital-python](https://pypi.org/project/vital)                   | Python library for calling Vital API on your backend |
| [vital-link](https://www.npmjs.com/package/@tryvital/vital-link) | React Library for initializing link                  |
| [vital-node](https://www.npmjs.com/package/@tryvital/vital-node) | Vital Node Client                                    |
| [vital-ios](https://github.com/tryVital/vital-ios)               | Vital iOS Client                                     |
| Java                                                             | Soon to be added                                     |
| Go                                                               | Soon to be added                                     |

You can also download our [API collection](https://www.postman.com/collections/35339909-b0d080b7-3870-4aa8-a68b-a675f93a0533) or by installing postman first and clicking on the below button.

[![Run in Postman](https://run.pstmn.io/button.svg)](https://god.gw.postman.com/run-collection/35339909-b0d080b7-3870-4aa8-a68b-a675f93a0533?action=collection%2Ffork\&source=rip_markdown\&collection-url=entityId%3D35339909-b0d080b7-3870-4aa8-a68b-a675f93a0533%26entityType%3Dcollection%26workspaceId%3Ddd82502b-0c9d-4fe4-9760-73a54bc2b8bf)

## Next Steps

Congratulations, you have completed the Vital Quickstart!

There are a few directions you can go in now:

<Card title="Vital Link" icon="link" iconType="regular" href="/wearables/vital-link/introduction">
  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.
</Card>

<Card title="Vital SDKs" icon="toolbox" iconType="regular" href="/wearables/sdks/ios">
  Native toolkits to integrate Vital into iOS, Android, and Flutter
</Card>

<Card title="Vital Webhooks" icon="circle-nodes" iconType="regular" href="/webhooks/introduction">
  Webhooks are a way to receive data from Vital. We frequently poll to receive
  data from the various providers.
</Card>

* [Vital Link](/wearables/vital-link/introduction)
* [Vital SDKs](/wearables/sdks/ios)
* [Vital Webhooks](/webhooks/Introduction)


# Welcome to our Docs
Source: https://docs.junction.com/home/welcome

Here you'll find guides, resources, and references to build using Junction's APIs and SDKs.

<Note>
  We've just **rebranded from Vital to Junction**. You may see some references to
  Vital among the docs, please bear with us as we get this updated.
</Note>

<CardGroup cols={2}>
  <Card title="Lab Testing" icon="flask" color="#BF40BF" href="/lab/overview/introduction">
    Access a nationwide lab network. In-person, at-home, or hybrid methods to maximize completion rates.
  </Card>

  <Card title="Device Data Providers" icon="gears" color="#0285c7" href="/wearables/providers/introduction">
    Connect to 300+ devices, and receive data in Junction standardized schemas.
  </Card>

  <Card title="Junction API" icon="seedling" color="#16a34a" href="/api-details/junction-api">
    User management, Device connection and data access, Lab Testing orders and results, Horizon AI Query.
  </Card>

  <Card title="Junction Management API" icon="building" color="#16a34a" href="/api-details/junction-management-api">
    Programmatically manage all Junction regional and global resources in your organization.
  </Card>
</CardGroup>

## Popular Topics

<CardGroup cols={1}>
  <Card title="Quickstart" icon="bolt" color="#FDD023" href="/home/quickstart" horizontal>
    The Quickstart walk-through gives you an overview of how to integrate with
    Junction. By the end of this guide, you'll have a working app with both
    backend and frontend.
  </Card>

  <Card title="Apple HealthKit" icon="apple" href="/wearables/guides/apple-healthkit" horizontal>
    Learn how to integrate with Apple HealthKit through Junction Mobile SDKs,
    available in Native iOS, React Native and Flutter.
  </Card>

  <Card title="Android Health Connect" icon="android" href="/wearables/guides/android-health-connect" horizontal>
    Learn how to integrate with Android Health Connect through Junction Mobile
    SDKs, available in Native Android, React Native and Flutter.
  </Card>

  <Card title="Junction Link Widget" icon="link" href="/wearables/connecting-providers/introduction" horizontal>
    Junction Link enables your users to connect their account with with their
    wearable data providers. Learn how to integrate the Link Widget for a
    no-fuzz starter integration.
  </Card>

  <Card title="Junction Link API" icon="link" href="/wearables/connecting-providers/custom_widget" horizontal>
    Learn how to use the Junction Link API to build your own Link Widget.
  </Card>

  <Card title="Timestamps and Time Zones" icon="clock" href="/wearables/providers/timestamps-and-time-zones" horizontal>
    Learn about timestamp and time zone handling of wearable device data.
  </Card>

  <Card title="Webhooks & Events" icon="radar" href="/webhooks/introduction" horizontal>
    Junction can push wearable device data as webhook events to you as soon as
    they are discovered. Learn about the delivery stages, event structure as
    well as the advanced ETL Pipeline options for high volume needs.
  </Card>

  <Card title="Synthetic Data" icon="parachute-box" href="/wearables/providers/test_data" horizontal>
    Learn how to use Demo Connections — which emit synthetic data mimicking
    selected providers — as an alternative way to test your Junction
    integration.
  </Card>
</CardGroup>


# Communications
Source: https://docs.junction.com/lab/at-home-phlebotomy/communications


Communication for patients is done via email or SMS, for At-Home Phlebotomy orders.
Customers have the following options when setting this up:

* `Default` - Email and SMS communications are enabled.
* `SMS Only` - Only SMS communication is enabled.
* `Disable` - All communications from Vital are disabled.

Each option has a different set of content and status changes, depending on what triggered them.

<Info>You can enable or disable SMS and Email communications individually through the [**Vital Dashboard**](http://app.tryvital.io/), under the Team Settings section.</Info>

## Default Communications

### SMS Messages

A table of the **Order Status** and **default SMS** is provided bellow:

| Order Status            | Default Message                                                                                                                                                |
| ----------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `requisition_created`   | *"Hey **patient\_first\_name**, it's time to book your at-home phlebotomy draw. You can book a slot using the following link **booking\_link**."*              |
| `appointment_scheduled` | *"Your appointment with the phlebotomist has been booked at **date**! You can reschedule or cancel using the following link **booking\_link**."*               |
| `appointment_cancelled` | *"Hey, your at-home-phlebotomy appointment at **date** for the **team\_name** has been cancelled. You can rebook using the following link **booking\_link**."* |
| `draw_completed`        | *"Your at-home phlebotomy draw is complete! We're delivering your sample to the lab for processing."*                                                          |
| `completed`             | *"The lab has finished processing your blood sample, your results should be ready soon :)"*                                                                    |
| `cancelled`             | *"Hey, your order for the **team\_name** at-home-phlebotomy appointment has been cancelled. If this is by accident please contact support."*                   |

<Info>SMS Texts are customizable, and can be enabled or disabled individually.</Info>

### Emails

For emails, the following table describes what information each email contains for each Order Statuses:

| Order Status            | Email Content Description                                                                                                                          |
| ----------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| `requisition_created`   | An email with the booking link for **Vital Booking Widget** will be sent to the patient.                                                           |
| `appointment_scheduled` | An email confirming the appointment date and time will be sent to the patient, with the possibility of rescheduling or cancelling the appointment. |
| `appointment_cancelled` | An email confirming the cancellation of the appointment is sent, providing the possibility of scheduling a new appointment.                        |

<Info>Emails can be white labelled and sent from your own domain.</Info>

## Disable Communications

In this case, no communications will be sent from Vital. You have the ability to produce completely customized communications
using the [`Webhook events`](/lab/at-home-phlebotomy/webhooks) described previously.


# Order and Appointment Lifecycle
Source: https://docs.junction.com/lab/at-home-phlebotomy/order-appointment-lifecycle


The **At-Home Phlebotomy** orders are composed of two different lifecycles, the **Order** lifecycle and
the **appointment** lifecycle, detailed in the following sections.

## Order Lifecycle

As discussed in [`Lab Test Lifecycle - Statuses`](/lab/workflow/lab-test-lifecycle#statuses),
each lab testing modality has the following format

`[HIGH-LEVEL STATUS].[TEST MODALITY].[LOW-LEVEL STATUS]`

For each modality, there can be multiple **low-level status**, for **At Home Phlebotomy** the
possible low-level status are:

* `ordered`: Vital received the order, stored it into our system, and started processing it asynchronously.
* `requisition_created`: An order requisition form was validated and created with the partner laboratory, making the order available to be carried out.
* `requisition_bypassed`: An order requisition form wasn't created when the order was placed with us because it already existed.
* `appointment_pending`: An appointment was placed in Vital's system for the order, but doesn't have a scheduled date.
* `appointment_scheduled`: An appointment was scheduled or rescheduled for the order.
* `draw_completed`: The phlebotomy appointment was completed and the blood was drawn successfuly.
* `appointment_cancelled`: The appointment was cancelled, by either the patient, Vital or you.
* `partial_results`: The laboratory has started making partial results available.
* `completed`: The laboratory processed the blood sample and final results are available.
* `cancelled`: The order was cancelled by either the patient, Vital or you.

The Finite State Machine that defines the possible transitions for the low-level statuses described above is illustrated
in the following diagram.

<Frame caption="Possible state transitions for the At-Home Phlebotomy Order low-level statuses.">
  <img src="https://mintcdn.com/vital/img/at_home_phleb_order_lifecycle.png?maxW=2711&auto=format&n=nR1fvAlwouZ87zVb&q=85&s=7e9ab9aeda6e854e0247422f2e0ec4ec" width="2711" height="3645" data-path="img/at_home_phleb_order_lifecycle.png" srcset="https://mintcdn.com/vital/img/at_home_phleb_order_lifecycle.png?w=280&maxW=2711&auto=format&n=nR1fvAlwouZ87zVb&q=85&s=74c99b47c2f91475882fa0d44529e4cb 280w, https://mintcdn.com/vital/img/at_home_phleb_order_lifecycle.png?w=560&maxW=2711&auto=format&n=nR1fvAlwouZ87zVb&q=85&s=17fba38f5a9dd4ecd36b3dec8763fe4a 560w, https://mintcdn.com/vital/img/at_home_phleb_order_lifecycle.png?w=840&maxW=2711&auto=format&n=nR1fvAlwouZ87zVb&q=85&s=b8867e54d44913cdff4991a52571af6a 840w, https://mintcdn.com/vital/img/at_home_phleb_order_lifecycle.png?w=1100&maxW=2711&auto=format&n=nR1fvAlwouZ87zVb&q=85&s=25c081ccd1bd702b2257d999d811db4a 1100w, https://mintcdn.com/vital/img/at_home_phleb_order_lifecycle.png?w=1650&maxW=2711&auto=format&n=nR1fvAlwouZ87zVb&q=85&s=5bb64631d80f3b66b8af67a97bee8e8d 1650w, https://mintcdn.com/vital/img/at_home_phleb_order_lifecycle.png?w=2500&maxW=2711&auto=format&n=nR1fvAlwouZ87zVb&q=85&s=f70a24c352574c6935cca6535e16e272 2500w" data-optimize="true" data-opv="2" />
</Frame>

<br />

<Info>In **sandbox**, there is no async transition from the `ordered` state to the `requisition_created` state, this must be **manually triggered** via the **Vital Dashboard**.</Info>

## Appointment Lifecycle

The appointment lifecycle is separate from the order lifecyle, and it corresponds to a single appointment.
The possible status are defined as follows:

* `pending`: An appointment was placed in the system, and is pending updates from the phlebotomy service.
* `scheduled`: An appointment was scheduled or rescheduled.
* `in-progress`: The phlebotomist is in their way to the patient address.
* `cancelled`: The appointment was cancelled by either the patient, Vital or you.
* `completed`: The phlebotomy appointment was completed and the blood was drawn successfuly

The Finite State Machine that defines the possible transitions for the appointment statuses described above is illustrated
in the following diagram.

<Frame caption="Possible state transitions for the At-Home Phlebotomy Appointment statuses.">
  <img src="https://mintcdn.com/vital/img/at_home_phleb_appointment_lifecycle.png?maxW=2527&auto=format&n=nR1fvAlwouZ87zVb&q=85&s=8ea1544ef32f19632c3fc8a54627daa0" width="2527" height="2310" data-path="img/at_home_phleb_appointment_lifecycle.png" srcset="https://mintcdn.com/vital/img/at_home_phleb_appointment_lifecycle.png?w=280&maxW=2527&auto=format&n=nR1fvAlwouZ87zVb&q=85&s=e795e57b9a8d648bdefb0d0306a1be78 280w, https://mintcdn.com/vital/img/at_home_phleb_appointment_lifecycle.png?w=560&maxW=2527&auto=format&n=nR1fvAlwouZ87zVb&q=85&s=3bc0cdb900d55612830afbdc4778ff1f 560w, https://mintcdn.com/vital/img/at_home_phleb_appointment_lifecycle.png?w=840&maxW=2527&auto=format&n=nR1fvAlwouZ87zVb&q=85&s=21d26235b2587bbd5b0aae3957d12930 840w, https://mintcdn.com/vital/img/at_home_phleb_appointment_lifecycle.png?w=1100&maxW=2527&auto=format&n=nR1fvAlwouZ87zVb&q=85&s=7a847ab2c82b5ba84fd4ff20fc93830a 1100w, https://mintcdn.com/vital/img/at_home_phleb_appointment_lifecycle.png?w=1650&maxW=2527&auto=format&n=nR1fvAlwouZ87zVb&q=85&s=f1a9e3d7822b6ebcf3fdd99b62fdcf77 1650w, https://mintcdn.com/vital/img/at_home_phleb_appointment_lifecycle.png?w=2500&maxW=2527&auto=format&n=nR1fvAlwouZ87zVb&q=85&s=bcbf600f2afa033b637860ce9d7f07af 2500w" data-optimize="true" data-opv="2" />
</Frame>

The events are related to a single appointment. An order can have multiple existing appointments in Vital system, although only one appointment will be considered active
and returned when using the [GET Appointment endpoint](/api-reference/lab-testing-at-home-phlebotomy/get-appointment).


# Overview
Source: https://docs.junction.com/lab/at-home-phlebotomy/overview


At-home phlebotomy tests are one of our offered modalities.
This modality is focused on patients that don't want to go to a Laboratory,
but instead want a phlebotomist to come to their home or office to carry out the phlebotomy draw.
The phlebotomist is responsible for bringing the required equipment and tubes and then delivering those to our partner Laboratories.

## Ordering Flow overview

To achieve this, a high-level overview of the process is defined as:

* An order is placed in Vital's system through our Dashboard or API.
* The order is added to a background queue and additional checks are made before a test requisition is created with the chosen Laboratory.
* After the requisition is created, some form of communication is carried out with the patient so he can book an appointment with our phlebotomy partners.
* At the day of the appointment, our partner phlebotomist will contact the patient directly to assert that everything is correct for carrying out the appointment.
* The phlebotomist goes to the appointment, draws the patient's blood and then delivers it to the Laboratory.
* The Laboratory processes the patient's blood sample and generates the required results.
* Vital exposes the results via API as soon as they are available, both on PDF and structured data via API.

## Constraints

* Phlebotomy appointments are not supported for patients under 18 years of age.
* The same patient can't have more than one active appointment with a specific **Phlebotomy provider**.
* The addresses provided when fetching the appointment availability slots must be reachable by the phlebotomist, containing street number and unit (if exists).

To find out more details, see [`Order and Appointment Lifecycle`](/lab/at-home-phlebotomy/order-appointment-lifecycle), [`Communications`](/lab/at-home-phlebotomy/communications) and [`Webhooks`](/lab/at-home-phlebotomy/webhooks).


# Phlebotomy Service Tiers
Source: https://docs.junction.com/lab/at-home-phlebotomy/service-tiers


Vital offers multiple Tiers of phlebotomy services, with different coverage capabilities:

* **Appointment Ready:** An appointment is booked in Vital using the patient’s address and the  appointment’s date time. The scheduling is completely synchronous and fully controlled by Vital's customers through our API.
* **Appointment Request:** An appointment is requested through Vital system using the patient’s address. A phlebotomist will eventually assign themselves to the appointment and define the appointment’s date time with the patient.

The following Providers are available for each Tier:

|                     | Getlabs | Phlebfinders (Beta) |
| :------------------ | :-----: | :-----------------: |
| Appointment Ready   |    X    |                     |
| Appointment Request |         |          X          |

<Info>`appointment-request` appointments will start in the `pending` status, and won't have any time or date information.</Info>

## High Level flow for Appointment Scheduling

<Frame caption="Phlebotomy Flow.">
  <img src="https://mintcdn.com/vital/img/phlebotomy-flow.png?maxW=2658&auto=format&n=nR1fvAlwouZ87zVb&q=85&s=6e375da55c952c58d91724197db8db04" width="2658" height="3987" data-path="img/phlebotomy-flow.png" srcset="https://mintcdn.com/vital/img/phlebotomy-flow.png?w=280&maxW=2658&auto=format&n=nR1fvAlwouZ87zVb&q=85&s=94eb43487ca9b8142eca034dce7d68fd 280w, https://mintcdn.com/vital/img/phlebotomy-flow.png?w=560&maxW=2658&auto=format&n=nR1fvAlwouZ87zVb&q=85&s=2aa58db956336ed977972b1370774ebb 560w, https://mintcdn.com/vital/img/phlebotomy-flow.png?w=840&maxW=2658&auto=format&n=nR1fvAlwouZ87zVb&q=85&s=97b1e4e711f4861c364c03281b920530 840w, https://mintcdn.com/vital/img/phlebotomy-flow.png?w=1100&maxW=2658&auto=format&n=nR1fvAlwouZ87zVb&q=85&s=15a6a6d34794d800625b66c6883c6ead 1100w, https://mintcdn.com/vital/img/phlebotomy-flow.png?w=1650&maxW=2658&auto=format&n=nR1fvAlwouZ87zVb&q=85&s=aacb619a3f790451f522270c979add58 1650w, https://mintcdn.com/vital/img/phlebotomy-flow.png?w=2500&maxW=2658&auto=format&n=nR1fvAlwouZ87zVb&q=85&s=51d3bc0264921200806abed8cf64326e 2500w" data-optimize="true" data-opv="2" />
</Frame>

<br />

The recommend high level flow for selecting an appointment at Vital is:

* Place an At-Home Phlebotomy order with the [`POST /v3/order`](/api-reference/lab-testing/create-order) endpoint.
* Wait for the `Requisition Ready` status updates through our Webhooks.
* Fetch Provider data via the [`GET /v3/order/area/info`](/api-reference/lab-testing/area-info) endpoint, the response payload should look like this:

```json
{
  "zip_code": "85004",
  "phlebotomy": {
    "is_served": true,
		"providers": [
    {
      "name": "getlabs",
      "tier": ["appointment-ready"]
    },
    {
      "name": "phlebfinders",
      "tier": ["appointment-request"]
    }
    ]
  }
}
```

* Select the Provider that best fit your needs.
  * If you use the [`POST /v3/order/{order_id}/phlebotomy/appointment/book`](/api-reference/lab-testing-at-home-phlebotomy/appointment-booking) endpoint, an `appointment-ready` provider is chosen on your behalf.
  * if you use the [`POST /v3/order/{order_id}/phlebotomy/appointment/request`](/api-reference/lab-testing-at-home-phlebotomy/appointment-request) endpoint, you must select a provider that offers an `appointment-request` tier.
* Wait for the `Appointment Webhooks` and `Order Webhooks` described in the [Webhooks](/lab/at-home-phlebotomy/webhooks) section.


# Webhooks
Source: https://docs.junction.com/lab/at-home-phlebotomy/webhooks


The following webhook events are of interest, when placing an At-Home Phlebotomy order. Those are
described in detail in the following sections.

## Order webhook events

Based on the status present in [`Order and Appointment Lifecycle - Order Lifecycle`](/lab/at-home-phlebotomy/order-appointment-lifecycle#order-lifecycle),
Vital will trigger two kinds of webhook events, [`labtest.order.created`](/event-catalog/labtest.order.created) and
[`labtest.order.updated`](/event-catalog/labtest.order.updated).

The `labtest.order.created` event is triggered when an order is created in the system,
having the `ordered` status, and all subsequent status changes will trigger a `labtest.order.updated` event in the system.

<Note>The `partial_results` status does not trigger a Webhook unless specifically requested from Vital.</Note>

The webhook payload body will have the following information if the Order is in the `appointment_scheduled` status:

```json Phlebotomy Order Updated
{
  "id": "84d96c03-6b1c-4226-ad8f-ef44a6bc08af",
  "team_id": "6353bcab-3526-4838-8c92-063fa760fb6b",
  "user_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "patient_details": { "dob": "2020-01-01", "gender": "male" },
  "patient_address": {
    "receiver_name": "John Doe",
    "first_line": "123 Main St.",
    "second_line": "Apt. 208",
    "city": "San Francisco",
    "state": "CA",
    "zip": "91189",
    "country": "United States",
    "phone_number": "+1123456789"
  },
  "details": {
    "type": "at_home_phlebotomy",
    "data": {
      "id": "a655f0e4-6405-4a1d-80b7-66f06c2108a7",
      "appointment_id": "d55210cc-3d9f-4115-8262-5013f700c7be",
      "created_at": "2020-01-01T00:00:00Z",
      "updated_at": "2020-01-01T00:00:00Z"
    }
  },
  "sample_id": "123456789",
  "notes": "This is a note",
  "created_at": "2020-01-01T00:00:00Z",
  "updated_at": "2020-01-01T00:00:00Z",
  "status": "collecting_sample",
  "events": [
    {
      "id": 1,
      "created_at": "2022-01-01T00:00:00Z",
      "status": "received.at_home_phlebotomy.ordered"
    },
    {
      "id": 2,
      "created_at": "2022-01-02T00:00:00Z",
      "status": "received.at_home_phlebotomy.requisition_created"
    },
    {
      "id": 3,
      "created_at": "2022-01-03T00:00:00Z",
      "status": "collecting_sample.at_home_phlebotomy.appointment_scheduled"
    }
  ]
}
```

## Appointment webhook events

Based on the status present in [`Order and Appointment Lifecycle - Appointment Lifecycle`](/lab/at-home-phlebotomy/order-appointment-lifecycle#appointment-lifecycle),
Vital will trigger the [`labtest.appointment.updated`](/event-catalog/labtest.appointment.updated) webhook event.

<Info>
  The `labtest.appointment.updated` event is triggered for all possible appointment statuses, and is the **recommended** way of integrating to fetch all
  **At-Home Phlebotomy** status updates, together with the [Order Webhooks](#order-webhook-events).
</Info>

The webhook payload body may have the following information if the appointment is in the `scheduled` status, after a **reschedule** has happened:

```json Phlebotomy Appointment Updated
{
  "event_type": "labtest.appointment.updated",
  "data": {
    "id": "06c2c65b-74a0-4f25-a4a9-44f796296355",
    "user_id": "acf79a82-0c2c-4ca0-998b-378931793905",
    "order_id": "1ed9c8d7-e1b4-4d61-8123-0f99de5ae99a",
    "address": {
      "first_line": "123 Main St.",
      "second_line": "Apt. 208",
      "city": "San Francisco",
      "state": "CA",
      "zip_code": "91189",
      "country": "United States"
    },
    "location": {
      "lng": -122.4194155,
      "lat": 37.7749295
    },
    "start_at": "2022-01-01T00:00:00",
    "end_at": "2022-01-01T00:00:00",
    "iana_timezone": "America/New_York",
    "type": "phlebotomy",
    "provider": "getlabs",
    "status": "pending",
    "event_status": "scheduled",
    "provider_id": "123",
    "can_reschedule": true,
    "event_data": {
      "origin": "patient",
      "is_reschedule": true
    },
    "events": [
      {
        "created_at": "2022-01-01T00:00:00Z",
        "data": null,
        "status": "scheduled"
      },
      {
        "created_at": "2022-01-01T00:00:00Z",
        "data": {
          "origin": "patient",
          "is_reschedule": true
        },
        "status": "scheduled"
      },
    ]
  }
}
```

<br />

<Info>The `event_data` field contains relevant information regarding the current appointment status, and may be specific for each `provider`.</Info>


# Communications
Source: https://docs.junction.com/lab/on-site-collection/communications


<Card horizontal icon="person-digging" color="#57164A">
  This feature is in **closed beta**.

  Interested in this feature? Get in touch with your Customer Success Manager.
</Card>

Communication for patients is done via email or SMS, for On-site collection orders.
Customers have the following options when setting this up:

* `Default` - Email and SMS communications are enabled.
* `SMS Only or Email Only` - Only SMS or Email communication is enabled.
* `Disable` - All communications from Junction are disabled.

Each option has a different set of content and status changes, depending on what triggered them.

<Info>You can enable or disable SMS and Email communications individually through the [**Junction Dashboard**](http://app.tryvital.io/), under the Team Settings section.</Info>

## Default Communications

### SMS Messages

A table of the **Order Status** and **default SMS** is provided bellow:

| Order Status          | Default Message                                                                                                                                                                  |
| --------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `ordered`             | *"Hi, {patient_first_name}, your order for the {team_name} on-site collection has been placed! We'll provide you with updates on the status of your order via text messages :)"* |
| `requisition_created` | *"Hey {patient_first_name}, it's time to visit your local collection center. Please check the email you just received for instructions."*                                        |
| `draw_completed`      | *"Your on-site collection is complete! We're delivering your sample to the lab for processing."*                                                                                 |
| `completed`           | *"Your results have finished processing and should be ready soon."*                                                                                                              |
| `cancelled`           | *"Hey, your order for the {team_name} on-site collection has been cancelled. If this is by accident, please contact support."*                                                   |

<Info>SMS Texts are customizable, and can be enabled or disabled individually.</Info>

### Emails

For emails, the following table describes what information each email contains for each Order Statuses:

| Order Status          | Email Content Description                                                                              |
| --------------------- | ------------------------------------------------------------------------------------------------------ |
| `requisition_created` | An email with confirmation of the partner Lab and additional instructions will be sent to the patient. |

<Info>Emails can be customised and sent from your own domain.</Info>

## Disable Communications

In this case, no communications will be sent from Junction. You have the ability to produce completely customized communications
using the [`Webhook events`](/lab/on-site-collection/webhooks) described previously.


# Order Lifecycle
Source: https://docs.junction.com/lab/on-site-collection/order-lifecycle


<Card horizontal icon="person-digging" color="#57164A">
  This feature is in **closed beta**.

  Interested in this feature? Get in touch with your Customer Success Manager.
</Card>

The **On-site Collection** orders are composed of one lifecycle, the **Order** lifecycle, detailed in the following section.

## Order Lifecycle

As discussed in [`Lab Test Lifecycle - Statuses`](/lab/workflow/lab-test-lifecycle#statuses),
each lab testing modality has the following format

`[HIGH-LEVEL STATUS].[TEST MODALITY].[LOW-LEVEL STATUS]`

For on-site collections, this will look like:

`[HIGH-LEVEL STATUS].on_site_collection.[LOW-LEVEL STATUS]`

For each modality, there can be multiple **low-level status**, for **On-site Collection** the
possible low-level status are:

* `ordered`: Junction received the order, stored it into our system, and started processing it asynchronously.
* `requisition_created`: An order requisition form was validated and created with the partner laboratory, making the order available to be carried out.
* `requisition_bypassed`: An order requisition form wasn't created when the order was placed with us because it already existed.
* `draw_completed`: The phlebotomy was completed and the blood was drawn successfuly.
* `partial_results`: The laboratory has started making partial results available.
* `completed`: The laboratory processed the blood sample and final results are available.
* `cancelled`: The order was cancelled by either the patient, Junction or you.

This closely models that of walk-in tests. Refer to that [order lifecycle](/lab/walk-in/order-lifecycle#order-lifecycle) for a diagramatic explanation.


# Overview
Source: https://docs.junction.com/lab/on-site-collection/overview


<Card horizontal icon="person-digging" color="#57164A">
  This feature is in **closed beta**.

  Interested in this feature? Get in touch with your Customer Success Manager.
</Card>

On-site collections are one of our offered modalities. Their locations are customer-managed settings where blood draws occur outside of traditional lab-owned patient service centers — such as primary care clinics, employer health centers, or event-based wellness pop-ups.

## Ordering Flow overview

To achieve this, a high-level overview of the process is defined as:

* An order is placed in Junction's system through our Dashboard or API.
* The order is added to a background queue and additional checks are made before a test requisition is created with the chosen Laboratory.
* After the requisition is created, some form of communication is carried out with the patient.
* After that, the patient can go at any time they want to the draw location to have their blood drawn.
* The Laboratory processes the patient's blood sample and generates the required results.
* Junction exposes the results via API as soon as they are available, both on PDF and structured data via API.

To find out more details, see [`Order Lifecycle`](/lab/on-site-collection/order-lifecycle), [`Communications`](/lab/on-site-collection/communications) and [`Webhooks`](/lab/on-site-collection/webhooks).


# Webhooks
Source: https://docs.junction.com/lab/on-site-collection/webhooks


<Card horizontal icon="person-digging" color="#57164A">
  This feature is in **closed beta**.

  Interested in this feature? Get in touch with your Customer Success Manager.
</Card>

The following webhook events are of interest, when placing an On-site collection. Those are
described in detail in the following sections.

## Order webhook events

Based on the status present in [`Order Lifecycle`](/lab/on-site-collection/order-lifecycle),
Junction will trigger two kinds of webhook events, [`labtest.order.created`](/event-catalog/labtest.order.created) and
[`labtest.order.updated`](/event-catalog/labtest.order.updated).

The `labtest.order.created` event is triggered when an order is created in the system,
having the `ordered` status, and all subsequent status changes will trigger a `labtest.order.updated` event in the system.

<Note>The `partial_results` status does not trigger a Webhook unless specifically requested from Junction.</Note>

The webhook payload body will have the following information if the Order is in the `completed` status:

```json On-site Collection Order Updated
{
  "id": "84d96c03-6b1c-4226-ad8f-ef44a6bc08af",
  "team_id": "6353bcab-3526-4838-8c92-063fa760fb6b",
  "user_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "patient_details": { "dob": "2020-01-01", "gender": "male" },
  "patient_address": {
    "receiver_name": "John Doe",
    "first_line": "123 Main St.",
    "second_line": "Apt. 208",
    "city": "San Francisco",
    "state": "CA",
    "zip": "91189",
    "country": "United States",
    "phone_number": "+1123456789"
  },
  "details": {
    "type": "on_site_collection",
    "data": {
      "id": "a655f0e4-6405-4a1d-80b7-66f06c2108a7",
      "created_at": "2020-01-01T00:00:00Z",
      "updated_at": "2020-01-01T00:00:00Z"
    }
  },
  "sample_id": "123456789",
  "notes": "This is a note",
  "created_at": "2020-01-01T00:00:00Z",
  "updated_at": "2020-01-01T00:00:00Z",
  "status": "completed",
  "events": [
    {
      "id": 1,
      "created_at": "2022-01-01T00:00:00Z",
      "status": "received.on_site_collection.ordered"
    },
    {
      "id": 2,
      "created_at": "2022-01-02T00:00:00Z",
      "status": "received.on_site_collection.requisition_created"
    },
    {
      "id": 33,
      "created_at": "2022-01-03T00:00:00Z",
      "status": "sample_with_lab.on_site_collection.draw_completed"
    },
    {
      "id": 4,
      "created_at": "2022-01-04T00:00:00Z",
      "status": "sample_with_lab.on_site_collection.partial_results"
    },
    {
      "id": 5,
      "created_at": "2022-01-05T00:00:00Z",
      "status": "completed.on_site_collection.completed"
    }
  ]
}
```


# Insurance Ordering
Source: https://docs.junction.com/lab/overview/insurance


<Card horizontal icon="person-digging" color="#57164A">
  This feature is in **closed beta**.

  Interested in this feature? Get in touch with your Customer Success Manager.
</Card>

Vital supports ordering with commercial insurance billing. To set this up, there are a set of steps required. This document explains the complete flow for ordering via commercial insurance.

## Setting Insurance Data

<Note>
  **Medicare and Medicaid location inference closed beta**

  If insurance is covered by Medicare or Medicaid, we have closed beta support for inferring the plan to use based on a patient's address. This endpoint supports `payor_code`s with values of `MEDFED` (Medicare) and
  `MAIDFED` (Medicaid) to do this.

  For example, supplying a `payor_code` of `MEDFED` for a patient that lives in Arizona will create insurance data using Arizona's Medicare plan payor code.

  Medicare and Medicaid location inference is in closed beta. Get in touch with your Customer Success manager for more information or check out the [API docs](/api-reference/user/create-insurance) on the beta channel.
</Note>

To place an order for a `user` in Vital with commercial insurance, you must first provide Vital with insurance data.

This can be done via the [`POST /{user_id}/insurance`](/api-reference/user/create-insurance) endpoint, with the following payload:

<Note>
  Note that you can only set insurance data for users that already have patient information set, either via an order or via the [`PATCH /v2/user/{user_id}/info`](/api-reference/user/upsert-info).
</Note>

It is expected that insurance data will become outdated or change with time. It is the customer's responsability to update this data with Vital in order to minimise the risk of a denied claim.

```json
"insurance": {
    "payor_code": "string",
    "member_id": "string",
    "group_id": "string", // optional
    "relationship": "Self, Spouse, Other",
    "insured": {
        "first_name": "string",
        "last_name": "string",
        "dob": "YYYY-MM-DD",
        "gender": "string",
        "address": {
            "first_line": "string", 
            "second_line": "string", // optional
            "zip_code": "string",
            "state": "string",
            "city": "string",
        },
        "phone_number": "string",
        "email": "string"
    },
    "guarantor": {
        "first_name": "string",
        "last_name": "string",
        "dob": "YYYY-MM-DD",
        "gender": "string",
        "address": {
            "first_line": "string", 
            "second_line": "string", // optional
            "zip_code": "string",
            "state": "string",
            "city": "string",
        },
        "phone_number": "string",
        "email": "string",
    } // optional if relationship is Self
}
```

### Insured, Guarantor and Relationship

First, let's understand the `relationship`, `insured` and `guarantor` fields.

`insured` refers to the insured person, and must always be provided. The `relationship` field, is the relationship between the patient and the holder of the insurance.
For example, if the insured person and the insurance holder are the same, then the relationship is `Self`.

The `guarantor` is an optional field, that must be provided when the relationship is **NOT** `Self`. The guarantor is the financially responsible party. If provided when the relationship is `Self`, we will store it, but it may not be propagated to all lab partners, as not all partners accept a guarantor in this situation.

### Payor Code

The `payor code` is a lab specific identifier for an insurance company. Vital has abstracted this away into our own Vital payor codes, allowing customers to supply one lab-agnostic payor code for all labs.

To obtain this code, use the [Search Payor Code](/api-reference/lab-testing-insurance/search-payor-get) endpoint, using the insurance company name, and select the `code` from your insurance company.

It is also possible to use this endpoint to search using external provider's payor codes (e.g Change HealthCare or Availity).

```json
[
  {
    "code": "AARPA",
    "name": "AARP",
    "aliases": [
      "AARP",
      "AARP"
    ],
    "org_address": {
      "first_line": "PO BOX 740819",
      "second_line": null,
      "country": "US",
      "zip": "30374",
      "city": "ATLANTA",
      "state": "GA"
    }
  },
]
```

## Ordering

Once the above steps are complete, you can place an order as usual, with two differences.

In order to trigger the commercial insurance flow, you must supply the following extra fields in the [POST /order](/api-reference/lab-testing/create-order) payload:

```json
{
	"icd_codes": ["ICD.10"], 
	"billing_type": "commercial_insurance" 
}
```

### Billing type

By default, Vital orders are Client Bill. In order to trigger the insurance flow, you must supply the `billing_type` field, with `commercial_insurance`.

### Diagnosis Codes

Insurance orders require diagnosis codes to be supplied. You can search for diagnosis codes in our [Search ICD Code](/api-reference/lab-testing-insurance/search-diagnosis) endpoint.

## Insurance Availability

Not all labs and not all states are cleared for insurance ordering. You can verify if a zip code is served for insurance via the [`GET /v3/order/area/info`](/api-reference/lab-testing/area-info) endpoint.

If a particular lab supports insurance, then you should see `commercial_insurance` in the supported bill types.

```json
{
  "zip_code": "85007",
  "central_labs": {
    "labcorp": {
      "patient_service_centers": {
        "within_radius": 15,
        "radius": "25"
      },
      "supported_bill_types": [
        "commercial_insurance"
      ]
    },
    ...
  }
}
```

## Error Cases

1. Order with `commercial_insurance` billing for a lab that does not support it.
2. Order with `commercial_insurance` billing for a state that does not support it.
3. Order with `commercial_insurance` billing and provide no ICD codes or invalid ICD codes.
4. Order with `commercial_insurance` billing and the user has no insurance data.


# Introduction
Source: https://docs.junction.com/lab/overview/introduction


Vital's lab test API allows digital health companies to carry out at-home lab testing.
Companies can use the API to order a variety of tests, using multiple sampling methods.

We partner with CLIA and CAP certified labs across the United States that cover a range of different diagnostic tests. For example lipids panels, metabolic profiles, hormone tests and more.
We collect these test samples via at-home kits, or phlebotomy.

### Features

Our lab test API gives you an end-to-end experience, from ordering a test all the way to receiving results, all with one API call!

What we offer:

* Multiple [test modalities](/lab/overview/testing-modalities) through one unified API.
* 50 State Physician network - you can use your own physician if you have one, or we will automatically assign one from our network.
* Updates throughout the test lifecycle - we automatically send you webhook updates and SMS updates to your patients so that you both never miss an update.
* Test results: we will update you once the test results are ready. In case of abnormal results, we also provide follow-ups through our Physician network.
* 1:1 support: after production launch, you will have direct access to Slack and our engineers.

### Start integrating

You can sign-up today to our sandbox environment. The [quickstart](/lab/overview/quickstart-api) guide will help you getting from zero to ordering tests in less than 30 minutes! Once the integration is ready, switching to production will just be a matter of switching API keys.

### Production launch

As a first step, we need to define what type of testing you want to offer to your users. We will have an introduction call to go over the test, projected volumes, customizations for kits and other questions you might have. Once we have all this information, we will begin setting up the test kits for distribution. Once the integration is complete, you will have access to the dashboard to start ordering tests via our API.

In [this page](https://tryvital.io/labs), you can check out some examples of the test panels we offer, and book an introductory call with us.

### Support

We will assist you throughout the whole integration with Vital. After launch, you will have a dedicated account manager with access to Slack, and 1:1 support with our engineers.

### Coverage

Our lab test API is available throughout the US. This is our current coverage by test modality:

* [At-home test kits](/lab/overview/testing-modalities#at-home-test-kits): 49 states (all excluding NY).
* [Walk-in tests](/lab/overview/testing-modalities#walk-in-tests): 49 states (all excluding NY).
* [At-home phlebotomy](/lab/overview/testing-modalities#at-home-phlebotomy): 35 states at the moment. Full coverage coming soon.
* [On-site collection](/lab/overview/testing-modalities#on-site-collection): In beta testing

<Info>
  To find out more about our coverage, you can use the [area info endpoint](/api-reference/lab-testing/area-info) - this endpoint takes a zip code and tells whether that area is covered by our service or not. Or you can contact us at [support@tryvital.io](mailto:support@tryvital.io) for more info.
</Info>


# Patient Service Centers and Appointments
Source: https://docs.junction.com/lab/overview/locations


# Finding nearest serviceable Patient Service Centers

Verifying if a particular zip code is serviceable is an important step, as not all labs have patient service centers within a state or within a reasonable distance.

The recommend high level flow for verifying PSC availability at Vital is:

* Fetch PSC location data via the [`GET /v3/order/area/info`](/api-reference/lab-testing/area-info) endpoint, the response payload should look like this:

```json
{
  "zip_code": "85004",
  "central_labs": {
    "labcorp": {
        "within_radius": 5, # number of PSC's within radius of provided zip code
        "radius": "25", # miles
        "capabilities": ["stat"] # aggregate list of capabilities provided by PSCs within the radius
    }
  }
  ...
}
```

<Note>
  A **capability** is a specific service that a PSC provides, for example STAT testing.
</Note>

If specific data regarding the PSC's is required, then you can also query the [`GET /v3/order/psc/info`](/api-reference/lab-testing/psc-info) for specific information on the PSC's within the radius of the provided zip code.

```json
{
  "lab_id": 27,
  "slug": "labcorp",
  "patient_service_centers": [
    {
      "metadata": {
        "name": "LABCORP",
        "state": "AZ",
        "city": "Phoenix",
        "zip_code": "85006",
        "first_line": "1300 N 12th St",
        "second_line": "Ste 300",
        "phone_number": "480-878-3988",
        "fax_number": "844-346-5903",
        "hours": null
      },
      "distance": "25",
      "site_code": "ABC",
      "capabilities": ["stat"]
    },
  ]
}
```

# Booking appointments at Patient Service Centers

<Note>
  Currently only available for Quest
</Note>

Vital allows booking of appointments directly with the Patient Service Centers for some labs. In order to book these appointments, you can use the [PSC Appointment API](/api-reference/lab-testing/psc-schedulling/appointment-psc-availability).

Patient Service Centers have access to the booked appointment, and these can be cancelled/updated outside our system. When this happens, we do not have visibility.

In order for the patient/customer to be able to track the appointment individually, we expose the `external_id` paramenter in the appointment endpoints/webhooks. This code is the unique identifier of the appointment at the provider, and should be made aware to the patient.

We provide it to the patient via the SMS communications for the appointment.

## Appointment Availability

You can use the [availability API](/api-reference/lab-testing/psc-schedulling/appointment-psc-availability) to obtain the available slots. You can feed in the `site_code` you obtain from the [`GET /v3/order/psc/info`](/api-reference/lab-testing/psc-info) endpoint, or supply a zip code directly. If you provider a zip code, a max of 3 PSC locations will be displayed.

Note that since this endpoint can return availability for multiple PSC's, there may be multiple timezones. The individual start and end times are in UTC, and each location has it's own `iana_timezone` key which should be used to convert these start and end dates to the correct timezone.
The overarching `timezone` key will always be `null` in this endpoint\`

## Booking

You can [book](/api-reference/lab-testing/psc-schedulling/appointment-psc-booking), [reschedule](/api-reference/lab-testing/psc-schedulling/appointment-psc-rescheduling) or [cancel](/api-reference/lab-testing/psc-schedulling/appointment-psc-cancelling) with Vital, as many times as you want.


# Order and Follow-up Physician
Source: https://docs.junction.com/lab/overview/physicians


For an order to be valid/complete, both the request and the results need to be validated by a physician. As such, Vital provides three flows:

## 1. Order and Results through Vital Physician Network

The validation of both the order and the results is done by Vital’s physician network.

For each order, Vital's physician network validates the requisition and, when the results are available, they are uploaded to Vital’s physician network to be evaluated for abnormal/critical results.
On the physician's judgement, the patient may receive a phone call regarding their results.

## 2. Order and Results with Customer Physician Network

In this flow, the Customer must specify a `physician` when making an order request. Both the order and the results are the responsability of the Customer's chosen physician.

## 3. Order with Vital Physician Network and Results with Customer Physician Network

In this flow, the Customer does not specify a `physician` when making an order request - they use Vital’s physician network.

However, the results aren’t uploaded to Vital’s physician network and it's the Customer's physicians responsability to validate the results and do the follow ups.

<Warning>
  When there are critical results, Vital’s physician network will always be notified.
</Warning>


# Quickstart
Source: https://docs.junction.com/lab/overview/quickstart


We have carefully designed Vital’s API to ensure a seamless and hassle-free experience for developers. You can get up and running with just a few lines of code. In this guide, we will walk you through the essential steps to order your first lab test.

### What you need

* If you haven't done so yet, you can get API keys by signing up for a Vital account in the [Dashboard](https://app.tryvital.io). Detailed instructions are available [here](/home/quickstart#1-api-keys).
* One of our [client libraries](/home/libraries). The lab testing API is available for the [python](https://pypi.org/project/vital/) and [node](https://www.npmjs.com/package/@tryvital/vital-node) SDKs. If none of those fit your use-case, you can always directly call the API. Email [support@tryvital.io](mailto:support@tryvital.io) for specific library support.

In the following, replace `{{BASE_URL}}` with your team's [environment URL](/home/environments).

### (1) Creating a user

In the context of our API, a user refers to the patient who will be undergoing the lab test. All you need to provide is a string identifying the user on your side (`client_user_id`). The response to this call returns the userId on our side, which you'll be able to use for future requests.

You can find more details in our [API quickstart guide](/home/quickstart#3-creating-your-first-user).

<CodeGroup>
  ```bash Creating a Vital user (bash)
  curl --request POST \
       --url {{BASE_URL}}/v2/user/ \
       --header 'Accept: application/json' \
       --header 'Content-Type: application/json' \
       --header 'x-vital-api-key: <YOUR_API_KEY>' \
       --data '{"client_user_id":"<YOUR_CLIENT_USER_ID>"}'
  ```

  ```js Node
  import { VitalClient, VitalEnvironment } from '@tryvital/vital-node';
  import { UserCreateBody } from '@tryvital/vital-node/api';

  const client = new VitalClient({
      apiKey: '<my_api_key>',
      environment: VitalEnvironment.Sandbox,
  });

  const request: UserCreateBody = {
      clientUserId: "<client_user_id>"
  }

  const data = await client.user.create(request)
  ```

  ```python Python
  from vital.client import Vital
  from vital.environment import VitalEnvironment

  client = Vital(
    api_key="YOUR_API_KEY",
    environment=VitalEnvironment.SANDBOX
  )

  data = client.user.create(client_user_id="<client_user_id>")
  ```

  ```java Java
  import com.vital.api.Vital;
  import com.vital.api.core.Environment;
  import com.vital.api.resources.user.requests.UserCreateBody;

  Vital vital = Vital.builder()
          .apiKey("YOUR_API_KEY")
          .environment(Environment.SANDBOX)
          .build();

  UserCreateBody request = UserCreateBody
       .builder()
       .clientUserId("<client_user_id>")
       .build();

  var data = vital.user().create(request);
  ```

  ```go Go
  import (
    "context"

    vital "github.com/tryVital/vital-go"
    vitalclient "github.com/tryVital/vital-go/client"
    "github.com/tryVital/vital-go/option"
  )

  client := vitalclient.NewClient(
    option.WithApiKey("<YOUR_API_KEY>"),
    option.WithBaseURL(vital.Environments.Sandbox),
  )

  request := &vital.UserCreateBody{
       ClientUserId: "<client_user_id>",
  }

  response, err := client.User.Create(context.TODO(), request)
  if err != nil {
    return err
  }
  fmt.Printf("Received data %s\n", response)
  ```
</CodeGroup>

### (2) Listing Available Tests

To retrieve the set of lab tests you have access to, use the `/v3/lab_tests` API endpoint. In Sandbox, you will already have access to a default set of tests. Once you're ready to head to production, we can [setup a call](/lab/overview/introduction#production-launch) and get you ready for launch!

<CodeGroup>
  ```bash Listing available tests (bash)
  curl --request GET \
       --url {{BASE_URL}}/v3/lab_tests/ \
       --header 'Accept: application/json' \
       --header 'x-vital-api-key: <YOUR_API_KEY>' \
       --header 'Content-Type: application/json'
  ```

  ```python Python
  from vital.client import Vital
  from vital.environment import VitalEnvironment

  client = Vital(
    api_key="YOUR_API_KEY",
    environment=VitalEnvironment.SANDBOX
  )

  data = client.lab_tests.get();
  ```

  ```javascript Node
  import { VitalClient, VitalEnvironment } from '@tryvital/vital-node';

  const client = new VitalClient({
      apiKey: '<my_api_key>',
      environment: VitalEnvironment.Sandbox,
  });

  const data = await client.labTests.get();
  ```

  ```java Java
  import com.vital.api.Vital;
  import com.vital.api.core.Environment;

  Vital vital = Vital.builder()
          .apiKey("YOUR_API_KEY")
          .environment(Environment.SANDBOX)
          .build();

  var data = vital.labTests().get();
  ```

  ```go Go
  import (
    "context"

    vital "github.com/tryVital/vital-go"
    vitalclient "github.com/tryVital/vital-go/client"
    "github.com/tryVital/vital-go/option"
  )

  client := vitalclient.NewClient(
    option.WithApiKey("<YOUR_API_KEY>"),
    option.WithBaseURL(vital.Environments.Sandbox),
  )

  response, err := client.LabTests.Get(context.TODO())
  if err != nil {
      return err
  }
  fmt.Printf("Received data %s\n", response)
  ```
</CodeGroup>

This will return a list of all the available tests to you. They include a description, turnaround time and price:

```json Response
{
  "lab_tests": [
    {
      "id": "e2eaa385-a311-4f17-b33f-2165e3d24dd9"
      "name": "Lipids Panel",
      "description": "Cholesterol tests",
      "sample_type": "dried blood spot",
      "method": "testkit",
      "price": 10.0,
      "is_active": True,
      "lab": {
          "slug": "USSL",
          "name": "US Specialty Lab",
          "first_line_address": "123 Main St",
          "city": "New York",
          "zipcode": "10001",
      },
      "markers": [
          {
              "name": "Thyroid Stimulating Hormone",
              "slug": "tsh",
              "description": "",
              "min_value": 100,
              "max_value": 200,
              "unit": "fg/L"
          }
      ],
    }
  ]
}
```

You can then use the test `id` when creating an order.

### (3) Placing an order

Ordering a test for your user is as simple as making an API call:

<CodeGroup>
  ```bash Ordering a test (bash)
  curl --request POST \
       --url {{BASE_URL}}/v3/order/ \
       --header 'Accept: application/json' \
       --header 'x-vital-api-key: <API_KEY>' \
       --header 'Content-Type: application/json' \
       --data '
  {
    "user_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "patient_details": {
      "dob": "2022-07-06T22:20:26.796Z",
      "gender": "male | female",
      "email": "test@test.com"
    },
    "patient_address": {
      "receiver_name": "John Doe",
      "street": "Hazel Road",
      "street_number": "102",
      "city": "San Francisco",
      "state": "CA",
      "zip": "91789",
      "country": "U.S.",
      "phone_number": "+14158180852"
    },
    "lab_test_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "physician": {
      "first_name": "John",
      "last_name": "Doe",
      "email": "john@doe.com",
      "npi": "123456789",
      "licensed_states": ["CA", "NY"],
      "created_at": "2022-07-06T22:20:26.796Z",
      "updated_at": "2022-07-06T22:20:26.796Z"
    }
  }
  '
  ```

  ```python Python
  from vital.client import Vital
  from vital.environment import VitalEnvironment
  from vital.types.gender import Gender
  from vital.types.patient_address_compatible import PatientAddressCompatible
  from vital.types.patient_details import PatientDetails
  from datetime import datetime

  client = Vital(
    api_key="YOUR_API_KEY",
    environment=VitalEnvironment.SANDBOX
  )

  data = client.lab_tests.create_order(
      user_id="63661a2b-2bb3-4125-bb1a-b590f64f057f",
      lab_test_id="5b41f610-ebc5-4803-8f0c-a61c3bdc7faf",
      patient_details=PatientDetails(
          first_name="John",
          last_name="Doe",
          dob=datetime.fromisoformat("2020-01-01"),
          gender=Gender.MALE,
          phone_number="+1123456789",
          email="email@email.com"
      ),
      patient_address=PatientAddressCompatible(
        receiver_name="john Doe",
        first_line="123 Main St.",
        second_line="Apt. 208",
        city="San Francisco",
        state="CA",
        zip="91189",
        country="US",
        phone_number="+1123456789"
      ),
  )
  ```

  ```javascript Node
  import { VitalClient, VitalEnvironment } from '@tryvital/vital-node';
  import { CreateOrderRequestCompatible} from '@tryvital/vital-node/api/resources/labTests';
  import { Gender } from '@tryvital/vital-node/api';

  const client = new VitalClient({
      apiKey: '<my_api_key>',
      environment: VitalEnvironment.Sandbox,
  });

  const request: CreateOrderRequestCompatible = {
      userId: "63661a2b-2bb3-4125-bb1a-b590f64f057f",
      labTestId: "5b41f610-ebc5-4803-8f0c-a61c3bdc7faf",
      patientDetails: {
          firstName: "John",
          lastName: "Doe",
          dob: new Date("2020-01-01"),
          gender: Gender.Male,
          phoneNumber: "+1123456789",
          email: "email@email.com"
      },
      patientAddress: {
        receiverName: "john Doe",
        firstLine: "123 Main St.",
        secondLine: "Apt. 208",
        city: "San Francisco",
        state: "CA",
        zip: "91189",
        country: "US",
        phoneNumber: "+1123456789"
      },
  }

  const data = await client.labTests.createOrder(request)
  ```

  ```java Java
  import com.vital.api.Vital;
  import com.vital.api.core.Environment;
  import com.vital.api.resources.labtests.requests.LabTestsGetAreaInfoRequest;

  Vital vital = Vital.builder()
        .apiKey("YOUR_API_KEY")
        .environment(Environment.SANDBOX)
        .build();

  PatientDetails details = PatientDetails.builder()
        .firstName("John")
        .lastName("Doe")
        .dob(OffsetDateTime.parse("2020-01-01"))
        .gender(Gender.MALE)
        .phoneNumber("+1123456789")
        .email("email@email.com")
        .build();

  PatientAddressCompatible address = PatientAddressCompatible
        .builder()
        .firstLine("123 Main St.")
        .city("San Francisco")
        .state("CA")
        .zip("91189")
        .country("US")
        .phoneNumber("+1123456789")
        .build();

  CreateOrderRequestCompatible request = CreateOrderRequestCompatible
        .builder()
        .userId("63661a2b-2bb3-4125-bb1a-b590f64f057f")
        .labTestId("5b41f610-ebc5-4803-8f0c-a61c3bdc7faf")
        .patientDetails(details)
        .patientAddress(address)
        .build();

  var data = vital.labTests().createOrder(request);
  ```

  ```go Go
  import (
    "context"

    vital "github.com/tryVital/vital-go"
    vitalclient "github.com/tryVital/vital-go/client"
    "github.com/tryVital/vital-go/option"
  )

  client := vitalclient.NewClient(
    option.WithApiKey("<YOUR_API_KEY>"),
    option.WithBaseURL(vital.Environments.Sandbox),
  )

  details := &vital.PatientDetails{
     FirstName:   "John",
     LastName:    "Doe",
     Dob:         time.Date(2020, 1, 1, 0, 0, 0, 0, time.UTC),
     Gender:      vital.GenderMale,
     PhoneNumber: "+1123456789",
     Email:       "email@email.com",
  }

  address := &vital.PatientAddressCompatible{
     ReceiverName: vital.String("john Doe"),
     FirstLine:    "123 Main St.",
     SecondLine:   vital.String("Apt. 208"),
     City:         "San Francisco",
     State:        "CA",
     Zip:          "91189",
     Country:      "US",
     PhoneNumber:  vital.String("+1123456789"),
  }

  request := &vital.CreateOrderRequestCompatible{
     UserId:         "63661a2b-2bb3-4125-bb1a-b590f64f057f",
     LabTestId:      "5b41f610-ebc5-4803-8f0c-a61c3bdc7faf",
     PatientDetails: details,
     PatientAddress: address,
  }

  response, err := client.LabTests.CreateOrder(context.TODO(), request)
  if err != nil {
     return err
  }
  fmt.Printf("Received data %s\n", response)
  ```
</CodeGroup>

```json Response
{
        "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6"),
        "user_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
        "patient_details": {"dob": "2020-01-01", "gender": "male"},
        "patient_address": {
            "receiver_name": "John Doe",
            "first_line": "123 Main St.",
            "second_line": "Apt. 208",
            "city": "San Francisco",
            "state": "CA",
            "zip": "91189",
            "country": "United States",
            "phone_number": "+1123456789",
        },
        "details": {
            "type": "testkit",
            "data": {
                "id": "a655f0e4-6405-4a1d-80b7-66f06c2108a7",
                "shipment": {
                    "id": "d55210cc-3d9f-4115-8262-5013f700c7be",
                    "outbound_tracking_number": "<outbound_tracking_number>",
                    "outbound_tracking_url": "<outbound_tracking_url>",
                    "inbound_tracking_number": "<inbound_tracking_number>",
                    "inbound_tracking_url": "<inbound_tracking_url>",
                    "outbound_courier": "usps",
                    "inbound_courier": "usps",
                    "notes": "<notes>",
                    "created_at": "2020-01-01T00:00:00.000Z",
                    "updated_at": "2020-01-01T00:00:00.000Z",
                },
                "created_at": "2020-01-01T00:00:00Z",
                "updated_at": "2020-01-01T00:00:00Z",
            },
        },
        "diagnostic_lab_test": {
            "name": "Lipids Panel",
            "description": "Cholesterol test",
            "method": "testkit",
        },
        "sample_id": "123456789",
        "notes": "This is a note",
        "created_at": "2020-01-01T00:00:00Z",
        "updated_at": "2020-01-01T00:00:00Z",
        "status": "collecting_sample",
        "events": [
            {
                "id": 1,
                "created_at": "2022-01-01T00:00:00Z",
                "status": "received.testkit.ordered",
            }
    ],
}
```

As demonstrated in this Quickstart Guide, integrating with our API is straightforward, allowing you to access a wide range of lab tests with minimal effort. Placing an order for a lab test is as simple as making a request to the appropriate endpoint. With our user-friendly design and clear documentation, you can harness the power of our clinical test API to enhance your application and deliver a seamless experience to your users.


# Testing in Sandbox
Source: https://docs.junction.com/lab/overview/sandbox


In order for Customers to be able to simulate the ordering process in the sandbox environment, Vital provides both simulated results and a way to transition an order through it's [lifecycle](/lab/workflow/lab-test-lifecycle).

## Creating Lab Tests

Every created team comes with 3 standard `Lab Tests` to allow the Customer to test all 3 modalities.

However, since most customers choose to have their own custom lab tests, you should create your own tests using the [API](/lab/workflow/create-test). This is encouraged, as Vital generates results based on the associated markers. More on this on the [results section](/lab/overview/sandbox#results).

## Lifecycle

When an order is placed in the sandbox environment, it is "stuck" in the `ordered` state and will not progress unless triggered to do so. This can be done through the dashboard, or through the [API](/api-reference/lab-testing/simulate-order).

Initiating the simulation process will progress the order through the expected success states defined in the [lifecycle section](/lab/workflow/lab-test-lifecycle), triggering all expected webhooks, emails and SMS's.

<Warning>
  When testing the At-Home Phlebotomy, there is only one specific address which is allowed, this address is `West Lincoln Street, Phoenix, AZ 85004, USA`.
</Warning>

## Results

In order to allow Customers to test, Vital generate's fake results for each lab test, based on the [expected markers](/lab/results/result-formats#expected-results).

The generated results will cycle through all possible [result types](/lab/results/result-formats#resulttype).

<Warning>
  Note that generated values might not match the expected unit.
</Warning>

As for the PDF results, these are not generated, and Vital returns an example PDF that does not reflect the ordered test.\
\\

## Customizing the Response

You can customize the end response of the results via the body of the [Simulate Order](api-reference/lab-testing/simulate-order) endpoint.

There are three avenues of customization currently:

1. Interpretation

   Supplying the `interpretation` field will set the status of the result to the supplied value. If you set it to critical, then the critical result workflow will be triggered.

```json
{
  "interpretation": "critical"
}
```

2. Result Types

This field controls what result types will be generated. Ommiting it will means the result will cycle through all of them.

```json
{
  "result_types": ["numeric", "comment"]
}
```

3. Missing Results

Supplying this field will generate missing biomarkers in the result.

```json
{
  "has_mising_results": true
}
```


# Testing Modalities
Source: https://docs.junction.com/lab/overview/testing-modalities


By integrating with our API, you will have access to the following testing modalities:

* At-home test kit.
* At-home phlebotomy visit.
* Walk-in test visit.
* On-site collection visit (in closed beta).

## At-home test kits

This involves sending a kit to a patient's home. They will then be able to collect their sample specimen and send it back to our lab networks via mail.

At home testing kits are comprised of a number of components such as:

<div className="flex flex-row">
  <div>
    * Mailer Box
    * Blade Lancets
    * Plasters
    * Gauze
    * ADX Card
    * Blood collection card
    * Saliva Tubes
    * Collection Supplies
    * Instruction Booklet

    Additional components can be included in the test kit box. To fully customize the kit, just contact us [support@tryvital.io](mailto:support@tryvital.io).
  </div>

  <img src="https://mintcdn.com/vital/img/wyndly.png?maxW=2226&auto=format&n=nR1fvAlwouZ87zVb&q=85&s=f2084c7903a38d9b99e4bfd88f863af2" className="w-1/2 h-1/2" width="2226" height="1716" data-path="img/wyndly.png" srcset="https://mintcdn.com/vital/img/wyndly.png?w=280&maxW=2226&auto=format&n=nR1fvAlwouZ87zVb&q=85&s=d9f76214dd436624f1eee45ebb7dc8aa 280w, https://mintcdn.com/vital/img/wyndly.png?w=560&maxW=2226&auto=format&n=nR1fvAlwouZ87zVb&q=85&s=5c49891b9b73b447872428a774c35a31 560w, https://mintcdn.com/vital/img/wyndly.png?w=840&maxW=2226&auto=format&n=nR1fvAlwouZ87zVb&q=85&s=b7848c44bb77cbcd5f45a64d4f5853f2 840w, https://mintcdn.com/vital/img/wyndly.png?w=1100&maxW=2226&auto=format&n=nR1fvAlwouZ87zVb&q=85&s=3baa469ceb85d7deed3d7e48a5432619 1100w, https://mintcdn.com/vital/img/wyndly.png?w=1650&maxW=2226&auto=format&n=nR1fvAlwouZ87zVb&q=85&s=ad75e0fcb5bb5a73f203ae1f9ef1a73d 1650w, https://mintcdn.com/vital/img/wyndly.png?w=2500&maxW=2226&auto=format&n=nR1fvAlwouZ87zVb&q=85&s=311df6e7edfd9ccaa1855b0084e9d7c3 2500w" data-optimize="true" data-opv="2" />
</div>

## At-home phlebotomy

At-home phlebotomy requires a phlebotomist to visit a patient's home and carrying out the phlebotomy draw. The sample is then delivered to the lab by the phlebotomist.

The flow for at-home phlebotomy orders is as follows:

* [Place an order](/lab/overview/quickstart) via the API.
* The order is processed in the background. For at-home phlebotomy, this means generating the requisition form for the lab test.
* Once the requisition form is ready, a webhook update and an email to the patient are sent. The email will them know that they can now book an appointment.
* The patient goes through Vital's appointment booking dashboard, where they can select a location and time from the available slots.
* Once the appointment takes place and the sample is drawn, it will be taken to the lab.
* Once the lab analyzes the results, the order is complete and the results can be [fetched](/lab/results/result-formats).

## Walk-in tests

Walk-in tests require the patient to visit a lab location (often referred to as a Patient Service Center or PSC)—such as Quest, Labcorp, or BioReference—to have their sample collected. A requisition form is needed to perform the test, which Junction’s API generates if the patient meets the required conditions.

This workflow closely mirrors the at-home phlebotomy flow, except that appointment scheduling is not required. With a "walk-in" test, a patient can simply *walk in* to a PSC or they can schedule an appointment (Quest only).

## On-site collection

On-site collection also require the patient to visit a Patient Service Center closely mirrors the walk-in test flow. Scheduling an appointment is not necessary. On-site collections are currently in beta testing.

<Info>
  Expanded support for on-site or in-clinic draws coming soon!
</Info>


# Turnaround Times
Source: https://docs.junction.com/lab/overview/turnaround-times


<Card horizontal icon="person-digging" color="#57164A">
  This feature is in **closed beta**.

  Interested in this feature? Get in touch with your Customer Success Manager.
</Card>

For a comprehensive Dashboard-focused overview of turnaround times, check out [the product guide](https://support.junction.com/articles/9137043704-turnaround-time). This page focuses on the API aspects.

We have two different turnaround time metrics:

1. Common turnaround time which 95% of orders should fall within.
2. Worst-case turnaround time which 99% of orders should fall within.

Furthermore, each operates on three distinct levels:

1. Markers
2. Panels
3. Orders

<Note>
  Turnaround times are calculated from historical data. For some tests, we may not yet have enough data to make a determination on its turnaround time. We won't include turnaround times for these tests in our API responses.
</Note>

## Marker turnaround times

Marker turnaround times are based on historical orders of each marker. If a marker has been ordered enough such that we can make a statistically-viable determination on its average turnaround time, we will include these in payloads containing marker data. For example, the response body for [retrieving markers for a lab test](https://docs.junction.com/api-reference/lab-testing/lab-test-markers) includes the common and worst-case number of days to receive results for that marker after collection time. If we don't have enough data for that marker, those values will be null.

## Panel turnaround times

Panels comprise of one or more markers, and the turnaround time for the panel is the largest turnaround time among its constituent markers. Just like in marker response bodies, lab test response bodies return the common and worst-case turnaround times (in days) for the panel. You can see this when [getting all available tests](https://docs.junction.com/api-reference/lab-testing/tests-paginated), for example. If any of the markers in the panel have null turnaround times, then the panel also has a null turnaround time.

## Order turnaround times

An order's turnaround time is the same as its panel, so we don't repeat that information in the top level order response body. You can still find that information in the `lab_test` object within the response body if you need it. Instead, the top level body includes two related fields:

1. Expected result by date
2. Worst-case result by date

These will be null unless the order's lab test has a non-null turnaround time *and* the sample collection has already been performed. The time of sample collection is what we add to the panel turnaround times to determine the expected and worst-case result by dates. [Retrieving an order](https://docs.junction.com/api-reference/lab-testing/get-order) is an example of where this is included.


# Critical Results
Source: https://docs.junction.com/lab/results/critical-results


When our Lab partners return results to Vital, they may return specific interpretations for each Marker:

* `normal`, the marker value is inside the lab reference range.
* `abnormal`, the marker value is outside the lab reference range.
* `critical`, the marker value falls in the critical range for that marker, which can be life-threatening.

These values are returned in an `interpretation` field for results, both in each individual marker and the overall results object:

```json Resuls Object
{
  "metadata": {
    "age": 19,
    "dob": "18/08/1993",
    "clia_number": "12331231",
    "patient": "Bob Smith",
    "provider": "Dr. Jack Smith",
    "laboratory": "LabCorp",
    "date_reported": "2020-01-01",
    "date_collected": "2022-02-02",
    "specimen_number": "123131",
    "date_received": "2022-01-01",
    "status": "final",
    "interpretation": "critical"
  },
  "results": [
    {
      "name": "Hemoglobin",
      "slug": "hemoglobin",
      "unit": "g/dL",
      "notes": null,
      "value": 100.2,
      "timestamp": null,
      "max_range_value": 17.7,
      "min_range_value": 13.0,
      "is_above_max_range": true,
      "is_below_min_range": false,
      "interpretation": "critical"
    },
    {
      "name": "Sodium",
      "slug": "unknown",
      "unit": "mmol/L",
      "notes": null,
      "value": 136,
      "timestamp": null,
      "max_range_value": 144,
      "min_range_value": 134,
      "is_above_max_range": false,
      "is_below_min_range": false,
      "interpretation": "normal"
    }
  ]
}
```

Besides the `interpretation` field, there is also the `status` field, which can assume the values of `final` or `partial`, as the critical results are notified as soon as they're available, not all tests are guaranteed to have been processed by the lab.

For critical results, the laboratory will contact a physician, so they can provide further information to the patient. The physician called is the Vital assigned physician. They act as the ordering physician when placing the order. After the call is made, and Vital has received the results from the laboratory, a `labtest.result.critical` event is sent. The webhook payload contains the following information:

```json Critical Results Webhook Payload
{
  "data": {
    "created_at": "2023-09-04T19:02:33.042533+00:00",
    "updated_at": "2023-09-04T19:02:47.106778+00:00",
    "order_id": "93ae03a7-626f-4cf4-802b-1fb6b3c339c7",
    "sample_id": "W4123LKB3VTL",
    "status": "final",
    "interpretation": "critical",
    "team_id": "482gh249-cd9d-4049-bb42-db5682cdf1d2",
    "user_id": "db5d34d5-bf7b-4e25-b119-9asd53694f45"
  },
  "event_type": "labtest.result.critical"
}
```

After you receive the webhook, you can use the [`GET /order/{order_id}/result`](/api-reference/results/get-results) endpoint to fetch the raw results.

You can test the webhook event by using the [Vital Dashboard](https://app.tryvital.io) Webhooks section,
where you can register an endpoint and subscribe to the `labtest.result.critical` event.
The following images show what the screen should look like after you have an endpoint registered
and have selected the `Testing` section inside the endpoint configurations.

<img src="https://mintcdn.com/vital/img/critical-event-testing.png?maxW=3380&auto=format&n=nR1fvAlwouZ87zVb&q=85&s=579d9c59c9fe68fb169d6eea1bdf2b76" width="100%" width="3380" height="1738" data-path="img/critical-event-testing.png" srcset="https://mintcdn.com/vital/img/critical-event-testing.png?w=280&maxW=3380&auto=format&n=nR1fvAlwouZ87zVb&q=85&s=74b51c226f2a03f534f65d56bfac22fd 280w, https://mintcdn.com/vital/img/critical-event-testing.png?w=560&maxW=3380&auto=format&n=nR1fvAlwouZ87zVb&q=85&s=a50c1f82c9b0a4399b85111a7857d536 560w, https://mintcdn.com/vital/img/critical-event-testing.png?w=840&maxW=3380&auto=format&n=nR1fvAlwouZ87zVb&q=85&s=a1ed0df9eaf6789b0de599432b6df970 840w, https://mintcdn.com/vital/img/critical-event-testing.png?w=1100&maxW=3380&auto=format&n=nR1fvAlwouZ87zVb&q=85&s=ddfb0458417bfb7933e7d53930fd848d 1100w, https://mintcdn.com/vital/img/critical-event-testing.png?w=1650&maxW=3380&auto=format&n=nR1fvAlwouZ87zVb&q=85&s=b9358c7c41322aec5aa1e75e57e03c04 1650w, https://mintcdn.com/vital/img/critical-event-testing.png?w=2500&maxW=3380&auto=format&n=nR1fvAlwouZ87zVb&q=85&s=1f785edec7f9ac124221570cddf510b6 2500w" data-optimize="true" data-opv="2" />

You can then click the `Send Example` button and should receive a HTTP call in the registered url.


# null
Source: https://docs.junction.com/lab/results/follow-up


When the test results are ready, you will receive a `labtest.order.updated` webhook where the order has a `complete` status. That means the results are ready and can be [fetched](/lab/results/result-formats).

In case of abnormal results, our physician will determine if a call with the patient is required, and if so, they will follow up to figure out the next steps. Please keep in mind that the follow up call with the patient only happens for orders processed by our physician network. If you provided your own physician when you placed the order, you will be responsible for following up with your patients.


# Result Formats
Source: https://docs.junction.com/lab/results/result-formats


Vital's API returns results in two different formats.

* `PDF`
* `JSON`

## PDF Results

We return the raw results in PDF form, that we receive directly from our partner labs. This can be retrieved as follows:

```bash Get order results PDF
curl --request GET \
     --url {{BASE_URL}}/v3/order/result/pdf \
     --header 'Accept: application/json' \
     --header 'Content-Type: application/pdf' \
     --header 'x-vital-api-key: <your_api_key>' \
```

<Note>
  Some laboratories do not issue PDFs for partial results, and only provide PDF reports once all results are finalized
</Note>

An example result:

<img src="https://mintcdn.com/vital/img/test_result.jpg?maxW=1406&auto=format&n=nR1fvAlwouZ87zVb&q=85&s=7dda5e281875ba4d4f1ed7ca93eef2e6" className="w-2/3 h-2/3" width="1406" height="1818" data-path="img/test_result.jpg" srcset="https://mintcdn.com/vital/img/test_result.jpg?w=280&maxW=1406&auto=format&n=nR1fvAlwouZ87zVb&q=85&s=21589e1e35af4db6580e1c8eae02b423 280w, https://mintcdn.com/vital/img/test_result.jpg?w=560&maxW=1406&auto=format&n=nR1fvAlwouZ87zVb&q=85&s=526834616467ea4db098a61568a85af7 560w, https://mintcdn.com/vital/img/test_result.jpg?w=840&maxW=1406&auto=format&n=nR1fvAlwouZ87zVb&q=85&s=9214c93b4f2b7c9953d46803196db688 840w, https://mintcdn.com/vital/img/test_result.jpg?w=1100&maxW=1406&auto=format&n=nR1fvAlwouZ87zVb&q=85&s=dac448736059ff46fe3bbcd33646ba4b 1100w, https://mintcdn.com/vital/img/test_result.jpg?w=1650&maxW=1406&auto=format&n=nR1fvAlwouZ87zVb&q=85&s=449769e6be82dc9349dce18f06258035 1650w, https://mintcdn.com/vital/img/test_result.jpg?w=2500&maxW=1406&auto=format&n=nR1fvAlwouZ87zVb&q=85&s=28d86fbff69f7ce40841026ec9ea6938 2500w" data-optimize="true" data-opv="2" />

## JSON Results

We also return the parsed results in JSON format, so you can use them to generate your own forms.

These results are returned in a structured format, which you can find [here](/api-reference/results/get-results).

<Warning>The `results` field, according to the spec, can return either a `list[BiomarkerResult]` or an untyped `dict`. This is due to backwards compatibility, and you can disregard the untyped `dict`</Warning>

### Result Status

The `status` field can be one of the following:

1. `ResultStatus.PARTIAL` - The results are partial.
   Labs can return results before all biomarkers are available.
   Vital makes these results available to you as soon as we receive them, but does not send a webhook notification for `partial` results.

   This means that if you probe the API for results, you might get a `partial` result, even if there was no webhook for a `labtest.update` event.

   This is done due to the possibility of [critical values](/lab/workflow/lab-test-lifecycle#critical-results) in the results.

2. `ResultStatus.FINAL` - The results are complete.
   This means that all biomarkers are available, and the results are final. You will receive a `labtest.update` webhook notification for this event.

### BiomarkerResult

A `BiomarkerResult` has the following definition:

```python
name: str
slug: str
value: float  # deprecated
result: str
type: ResultType
unit: str | None
timestamp: datetime | None
notes: str | None
min_range_value: float | None
max_range_value: float | None
is_above_max_range: bool | None
is_below_min_range: bool | None
interpretation: str = Interpretation.NORMAL
loinc: str | None
loinc_slug: str | None
provider_id: str | None
source_markers: List[ParentBiomarkerData] | None 
```

#### ResultType

Results can fall into one of the following categories:

1. `ResultType.NUMERIC` - A numeric result, e.g. `1.2`

   In this case, the `result` field will be a string representation of the number, and the `value` field will be a float representation of the number.

2. `ResultType.RANGE` - A range result, e.g. `<1.2`

   In this case, the `result` field will be a string representation of the range value, and the `value` field will be `-1`.

   Note that you will also find the `<1.2` value in the `notes` field.

   A range result will always be a value following the pattern `^([<>]=?\d*(\.\d+)?|(\d*(\.\d+)?-\d*(\.\d+)?))$`.

3. `ResultType.COMMENT` - A text result, e.g. `Positive`

   In this case, the `result` field will be a string representation of the text, and the `value` field will be `-1`.

   Note that you will also find the `Positive` value in the `notes` field.

<Warning>The `value` field in deprecated and will eventually be removed.</Warning>

#### Interpretation

Interpretation is a string value that can be one of the following:

1. `Interpretation.NORMAL` - The result is within normal parameters.
2. `Interpretation.ABNORMAL` - The result is outside of normal parameters.
3. `Interpretation.CRITICAL` - The result is outside of critical parameters.
   In this case, refer to the [critical values](/lab/workflow/lab-test-lifecycle#critical-results) section.

#### Standardisation - LOINC

It's possible to test the same biomarkers across different laboratories. For these to match, we use the [LOINC](https://loinc.org/) standard.

In the `BiomarkerResult` object, you can see two fields `loinc_slug` and `loinc`. These fields refer to the LOINC standard. Customers should use this standard, so it's possible to match results across different laboratories.
You can expect that the `slug` field is what the laboratory returns to us - and the `loinc_slug` is the standardised version.

An example:

| Lab     | Slug            | LOINC  | LOINC Slug                  |
| ------- | --------------- | ------ | --------------------------- |
| Labcorp | hdl-cholesterol | 2085-9 | cholesterol-in-hdl-mass-vol |
| USSL    | hdl             | 2085-9 | cholesterol-in-hdl-mass-vol |

As you can see, the same biomarker `HDL Cholesterol` can have different slugs across different laboratories. However it's represented by the same LOINC value.

#### Expected Results

When ordering a `lab_test`, you can see which `markers` each test orders. These can either be `panels` composed of multiple `biomarkers` or just individual `biomarkers`.

This means that a `lab_test` with only one associated `marker`, such as `Lipid Panel`, can return multiple `result markers`. We call these expected results.
Each `marker` can thus be composed of multiple `expected results` which match to a `loinc`.

As an example, here's the expected results for the `Lipid Panel` marker:

```json
"expected_results":[
   {
      "id":1108,
      "name":"VLDL Cholesterol Cal",
      "slug":"vldl-cholesterol-cal",
      "lab_id":6,
      "provider_id":"011919",
      "loinc":{
         "id":5062,
         "name":"Cholesterol in VLDL Calc [Mass/Vol]",
         "slug":"cholesterol-in-vldl-calc-mass-vol",
         "code":"13458-5",
         "unit":"mg/dL"
      }
   },
   {
      "id":1109,
      "name":"Cholesterol, Total",
      "slug":"cholesterol-total",
      "lab_id":6,
      "provider_id":"001065",
      "loinc":{
         "id":11940,
         "name":"Cholesterol [Mass/Vol]",
         "slug":"cholesterol-mass-vol",
         "code":"2093-3",
         "unit":"mg/dL"
      }
   },
   {
      "id":1110,
      "name":"HDL Cholesterol",
      "slug":"hdl-cholesterol",
      "lab_id":6,
      "provider_id":"011817",
      "loinc":{
         "id":11858,
         "name":"Cholesterol in HDL [Mass/Vol]",
         "slug":"cholesterol-in-hdl-mass-vol",
         "code":"2085-9",
         "unit":"mg/dL"
      }
   },
   {
      "id":1112,
      "name":"Triglycerides",
      "slug":"triglycerides",
      "lab_id":6,
      "provider_id":"001172",
      "loinc":{
         "id":16384,
         "name":"Triglyceride [Mass/Vol]",
         "slug":"triglyceride-mass-vol",
         "code":"2571-8",
         "unit":"mg/dL"
      }
   },
   {
      "id":1113,
      "name":"LDL Chol Calc (NIH)",
      "slug":"ldl-chol-calc-nih",
      "lab_id":6,
      "provider_id":"012059",
      "loinc":{
         "id":5060,
         "name":"Cholesterol in LDL Calc [Mass/Vol]",
         "slug":"cholesterol-in-ldl-calc-mass-vol",
         "code":"13457-7",
         "unit":"mg/dL"
      }
   }
]
```

You can use this information to verify if the final results are composed of all expected results.

In order to obtain this data, you can use the following endpoints:

1. [GET /v3/lab\_tests/markers](/api-reference/lab-testing/biomarkers)

   This allows you to search markers based on laboratory or name.

2. [GET /v3/lab\_tests/\{id}/markers](/api-reference/lab-testing/lab-test-markers)

   This allows you to see all markers associated with a lab test and it's expected results.

#### Source Markers

As mentioned above, a marker can be composed of one or more results. This means that if you order a `Lipid Panel`, there will be no `Lipid Panel` result returned, but instead a series of markers that originate from the `Lipid Panel`.

Vital identifies the source marker via the `source_markers` field.

```json
    {
      "name": "Sex Horm Binding Glob, Serum",
      "slug": "sex-horm-binding-glob-serum",
      "value": 30.4,
      "result": "30.4",
      "type": "numeric",
      "unit": "nmol/L",
      "timestamp": "2024-10-31T09:08:00+00:00",
      "notes": "Final",
      "min_range_value": 24.6,
      "max_range_value": 122,
      "is_above_max_range": false,
      "is_below_min_range": false,
      "interpretation": "normal",
      "loinc": "13967-5",
      "loinc_slug": "sex-hormone-binding-globulin-moles-vol",
      "provider_id": "082016",
      "source_markers": [
        {
          "marker_id": 229,
          "name": "Testosterone Free, Profile I",
          "slug": "testosterone-free-profile-i",
          "provider_id": "140226"
        }
      ]
    },
```

When Vital cannot identify the source, then this field will be `null`, indicating that this is an unsolicited result.
There may also be more than one `source` marker, if there are two or more ordered markers that contain the same underlying result, using the same testing method.

#### Missing Results

At times labs will commit mistakes, and expected results will be missing. Vital identifies these and parses them into a separate structure, named `missing_results`.

This data has the following format:

```python
name: str
slug: str
inferred_failure_type: FailureType
note: str | None = None
loinc: str | None = None
loinc_slug: str | None = None
provider_id: str | None = None
source_markers: List[ParentBiomarkerData] | None = None
```

`inferred_failure_type` is the Vital assigned error type.
The error type is inferred from the comments received from the lab. They are to help assess possibly root causes of missing results, and aid the customer in identifying issues in aggregate. The way that we infer these error types is subject to change as we continue to refine and achieve more granular understanding of failure modes.

1. `quantity_not_sufficient_failure`

   The lab could not process this result due to an insufficient quantity of collected sample. This could be due to the patient refusing to collect more, the phlebotomist being to unable to collect the proper volume of blood from the sample, or the phlebotomist not collecting all of the sample they were meant to collect.

2. `collection_process_failure`

   This is indicative of potential failures to follow the entirety phlebotomy process, often immediately following the collection. For example, improper centrifugation of the collected sample, improper refrigeration. While these are the most likely causes, there are other reasons for why sample quality may have been degraded.

3. `drop_off_failure`

   This speaks to a specific form of collection process failures. Specifically that the sample was not received by the lab in proper condition. Possible issues correspond to improper freezing, or refrigeration, or was exposed to excessive transport delay.

4. `internal_lab_failure`

   This speaks to failures that are most likely to have happened internal to the lab. This includes issues such as misplacing a collected sample, or errors that could not be best attributed to any external cause.

5. `order_entry_failure`

   The test was not performed because it was not properly ordered at the lab.

6. `non_failure`

   This speaks to a failure that should not impact the patient. For example, it may indicate that a duplicate test was ordered.

7. `unknown_failure`

   This is a failure mode that could not be properly attributed to any specific failure mode. Potentially the results were simply left out and Vital was not provided any additional information.

8. `patient_condition_failure`

   This speaks to a failure to result due to specifics of the patient's physical condition. For example, the patient may have had some food very high in fats that immediately prior to a collection. It is possible that improper storage and handling can cause samples to fail in ways that appear to be a patient condition failure.

9. `missing_result_calc_failure`

   This failure indicates that a calculated field is missing because the underlying tests required to perform the calculation were either unable to be processed, or yielded a result outside of the allowable parameters to perform the calculation

10. `missing_demo_aoe_calc_failure`

Some results may require additional information reported in AOE (ask on order entry) in order to yield results, such as age, to be properly calculated.


# Communications
Source: https://docs.junction.com/lab/testkits/communications


Communication for patients is done via SMS, for At-home Teskit orders.
Customers have the following options when setting this up:

* `Default` - SMS communications are enabled.
* `Disable` - All communications from Vital are disabled.

Each option has a different set of content and status changes, depending on what triggered them.

<Info>You can enable or disable SMS individually through the [**Vital Dashboard**](http://app.tryvital.io/), under the Team Settings section.</Info>

## Default Communications

### SMS Messages

A table of the **Order Status** and **default SMS** is provided bellow:

| Order Status       | Default Message                                                                                                                                        |
| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `ordered`          | Hey **receiver\_name**, your order for the **team\_name** health kit has been placed! We'll update you with where it is in the process via messages :) |
| `transit_customer` | Your order for the **team\_name** test kit is in transit, and should be arriving by **eta**.                                                           |
| `out_for_delivery` | Your order for the **team\_name** test kit is out for delivery, and should be arriving by today                                                        |
| `delivered_to_lab` | Your test kit has arrived to our labs we're processing your sample now!                                                                                |
| `completed`        | The lab has finished processing your test kit, your results should be ready soon :)                                                                    |
| `cancelled`        | Hey, your order for the **team\_name** test kit has been cancelled, If this is by accident please contact support.                                     |

<Info>SMS Texts are customizable, and can be enabled or disabled individually.</Info>

### Emails

We do not send emails for At-home Testkits.

## Disable Communications

In this case, no communications will be sent from Vital. You have the ability to produce completely customized communications
using the [`Webhook events`](/lab/testkits/webhooks) described previously.


# Order Lifecycle
Source: https://docs.junction.com/lab/testkits/order-lifecycle


The **At-Home Testkit** can be composed of two distinct **Order** lifecycles, which we detail bellow.

## Order Lifecycle

As discussed in [`Lab Test Lifecycle - Statuses`](/lab/workflow/lab-test-lifecycle#statuses),
each lab testing modality has the following format

`[HIGH-LEVEL STATUS].[TEST MODALITY].[LOW-LEVEL STATUS]`

For each modality, there can be multiple **low-level status**, for **At-Home Testkit** the
possible low-level status are:

### Registered Teskits

* `ordered`: Vital received the order, stored it into our system, and started processing it asynchronously.
* `requisition_created`: An order requisition form was validated and created with the partner laboratory, making the order available to be carried out.
* `requisition_bypassed`: An order requisition form wasn't created when the order was placed with us because it already existed.
* `transit_customer`: The teskit is shipped and in transit to the customer.
* `out_for_delivery`: The teskit is out for delivery.
* `with_customer`: The teskit is delivered to the customer.
* `transit_lab`: The customer has sent the testkit back to the lab.
* `delivered_to_lab`: The lab has received the testkit.
* `failure_to_deliver_to_customer`: The shipping company was unable to deliver the testkit to the customer.
* `failure_to_deliver_to_lab`: The shipping company was unable to deliver the testkit to the lab.
* `problem_in_transit_customer`: The shipping company encountered a problem while delivering the testkit to the customer.
* `problem_in_transit_lab`: The shipping company encountered a problem while delivering the testkit to the lab.
* `sample_error`: The collected sample was unprocessable by the lab.
* `completed`: The laboratory processed the blood sample and final results are available.
* `cancelled`: The order was cancelled by either the patient, Vital or you.

The Finite State Machine that defines the possible transitions for the low-level statuses described above is illustrated
in the following diagram.

<Frame caption="Possible state transitions for the At-Home Testkit Order low-level statuses.">
  <img src="https://mintcdn.com/vital/img/testkit_lifecycle.png?maxW=1776&auto=format&n=nR1fvAlwouZ87zVb&q=85&s=ca65d55da1b6ab906f916c6b1f65b64e" width="1776" height="781" data-path="img/testkit_lifecycle.png" srcset="https://mintcdn.com/vital/img/testkit_lifecycle.png?w=280&maxW=1776&auto=format&n=nR1fvAlwouZ87zVb&q=85&s=b4e566de576bbbeeab290e0dd22c2d22 280w, https://mintcdn.com/vital/img/testkit_lifecycle.png?w=560&maxW=1776&auto=format&n=nR1fvAlwouZ87zVb&q=85&s=edf9b5e0ff746a0aa11e7276fd8a55f9 560w, https://mintcdn.com/vital/img/testkit_lifecycle.png?w=840&maxW=1776&auto=format&n=nR1fvAlwouZ87zVb&q=85&s=62c4ac842283298ec56d193c8c29896c 840w, https://mintcdn.com/vital/img/testkit_lifecycle.png?w=1100&maxW=1776&auto=format&n=nR1fvAlwouZ87zVb&q=85&s=f9bd0109388fca6387974ed9c5a507bb 1100w, https://mintcdn.com/vital/img/testkit_lifecycle.png?w=1650&maxW=1776&auto=format&n=nR1fvAlwouZ87zVb&q=85&s=2beef45fdda1e1f5faec3d0659772799 1650w, https://mintcdn.com/vital/img/testkit_lifecycle.png?w=2500&maxW=1776&auto=format&n=nR1fvAlwouZ87zVb&q=85&s=bc00246753d962999f4858a0251d5843 2500w" data-optimize="true" data-opv="2" />
</Frame>

### Registrable Testkits

* `ordered`: Vital received the order, stored it into our system, and started processing it asynchronously.
* `awaiting_registration`: Order is created but no user has been registered yet
* `transit_customer`: The teskit is shipped and in transit to the customer.
* `out_for_delivery`: The teskit is out for delivery.
* `with_customer`: The teskit is delivered to the customer.
* `registered`: Order has been registered, and a requisition will be created.
* `requisition_created`: An order requisition form was validated and created with the partner laboratory, making the order available to be carried out.
* `transit_lab`: The customer has sent the testkit back to the lab.
* `delivered_to_lab`: The lab has received the testkit.
* `failure_to_deliver_to_customer`: The shipping company was unable to deliver the testkit to the customer.
* `failure_to_deliver_to_lab`: The shipping company was unable to deliver the testkit to the lab.
* `problem_in_transit_customer`: The shipping company encountered a problem while delivering the testkit to the customer.
* `problem_in_transit_lab`: The shipping company encountered a problem while delivering the testkit to the lab.
* `sample_error`: The collected sample was unprocessable by the lab.
* `completed`: The laboratory processed the blood sample and final results are available.
* `cancelled`: The order was cancelled by either the patient, Vital or you.

The Finite State Machine that defines the possible transitions for the low-level statuses described above is illustrated
in the following diagram.

<Frame caption="Possible state transitions for the registrable At-Home Testkit Order low-level statuses.">
  <img src="https://mintcdn.com/vital/img/testkit_lifecycle_registrable.png?maxW=1794&auto=format&n=nR1fvAlwouZ87zVb&q=85&s=e7cb49a9c344d95d2d95d4c2667e7ec0" width="1794" height="1053" data-path="img/testkit_lifecycle_registrable.png" srcset="https://mintcdn.com/vital/img/testkit_lifecycle_registrable.png?w=280&maxW=1794&auto=format&n=nR1fvAlwouZ87zVb&q=85&s=dd4704c4a1fb8eece44a618df67818f1 280w, https://mintcdn.com/vital/img/testkit_lifecycle_registrable.png?w=560&maxW=1794&auto=format&n=nR1fvAlwouZ87zVb&q=85&s=d5bac7fae028bf2f2fc332ebaadbdf05 560w, https://mintcdn.com/vital/img/testkit_lifecycle_registrable.png?w=840&maxW=1794&auto=format&n=nR1fvAlwouZ87zVb&q=85&s=a092174272a52d72f456c68a94787fe2 840w, https://mintcdn.com/vital/img/testkit_lifecycle_registrable.png?w=1100&maxW=1794&auto=format&n=nR1fvAlwouZ87zVb&q=85&s=7422953cade24e3e9269d157ba395537 1100w, https://mintcdn.com/vital/img/testkit_lifecycle_registrable.png?w=1650&maxW=1794&auto=format&n=nR1fvAlwouZ87zVb&q=85&s=64e0ef5209114c1d4b379ba7d179b7e9 1650w, https://mintcdn.com/vital/img/testkit_lifecycle_registrable.png?w=2500&maxW=1794&auto=format&n=nR1fvAlwouZ87zVb&q=85&s=86cc056e3dee037caae0a8b7d2a57554 2500w" data-optimize="true" data-opv="2" />
</Frame>

<br />

<Info>In **sandbox**, there is no async transition from the `ordered` state to the `requisition_created` state, this must be **manually triggered** via the **Vital Dashboard**.</Info>


# Overview
Source: https://docs.junction.com/lab/testkits/overview


At-home Testkits are one of our offered modalities.
This modality involves sending a kit to a patient’s home, where the patient will collect their own sample and send the kit to our Lab network through mail.

Within this modality, we provide two types of testkits, those which are pre-registered to a user, and those which need to to be (registered by the patient upon receiving the kit)\[lab/workflow/order-registrable-testkit].

## Ordering Flow overview

To achieve this, a high-level overview of the process is defined as:

* An order is placed in Vital's system through our Dashboard or API.
* The order is added to a background queue and additional checks are made before the kit is shipped to the provided address.
* Once the order shipment is created, a requisition is generated.
* After the requisition is created, some form of communication is carried out with the patient.
* If the kit is not registered, then the user must register the kit before results can be provided.
* The patient receives the kit, collects their sample, and sends the kit back through mail.
* The Laboratory processes the patient's blood sample and generates the required results.
* Vital exposes the results via API as soon as they are available, both on PDF and structured data via API.

## Constraints

* If the teskit is un-registered, then the user must register it in order for the results to be processed.

To find out more details, see [`Order and Appointment Lifecycle`](/lab/testkits/order-lifecycle), [`Communications`](/lab/testkits/communications) and [`Webhooks`](/lab/testkits/webhooks).


# Webhooks
Source: https://docs.junction.com/lab/testkits/webhooks


The following webhook events are of interest, when placing an At-Home Testkit order. Those are
described in detail in the following sections.

## Order webhook events

Based on the status present in [`Order Lifecycle`](/lab/testkit/order-lifecycle),
Vital will trigger two kinds of webhook events, [`labtest.order.created`](/event-catalog/labtest.order.created) and
[`labtest.order.updated`](/event-catalog/labtest.order.updated).

The `labtest.order.created` event is triggered when an order is created in the system,
having the `ordered` status, and all subsequent status changes will trigger a `labtest.order.updated` event in the system.

The webhook payload body will have the following information if the Order is in the `requisition_created` status:

```json Testkit Order Updated
{
   "data":{
      "created_at":"2023-09-01T18:02:41.210495+00:00",
      "details":{
         "data":{
            "created_at":"2023-09-01T18:02:41.247443+00:00",
            "id":"3c046d74-347e-4e28-9e0d-c5b720a8e219",
            "shipment":{
               "id":"ae0323d4-2c18-4aea-a0e7-d73b377315b1",
               "inbound_courier":null,
               "inbound_tracking_number":null,
               "inbound_tracking_url":null,
               "notes":null,
               "outbound_courier":null,
               "outbound_tracking_number":null,
               "outbound_tracking_url":null
            },
            "updated_at":"2023-09-01T18:02:42.186312+00:00"
         },
         "type":"testkit"
      },
      "events":[
         {
            "created_at":"2023-09-01T18:02:41.271401+00:00",
            "id":4056,
            "status":"received.testkit.ordered"
         },
         {
            "created_at":"2023-09-01T18:05:12.618156+00:00",
            "id":4057,
            "status":"received.testkit.requisition_created"
         }
      ],
      "health_insurance_id":null,
      "id":"e1c380c1-7df4-487f-869e-f1be0193ca25",
      "lab_test":{
         "fasting":false,
         "id":"0cb9f34f-c3df-4a13-8ca1-19429a82611b",
         "is_active":true,
         "is_delegated":false,
         "lab":null,
         "markers":null,
         "method":"testkit",
         "name":"Female General Wellness",
         "price":45,
         "sample_type":"dried_blood_spot",
         "slug":"general_wellness_female_002"
      },
      "notes":null,
      "patient_address":{
        ...
      },
      "patient_details":{
        ...
      },
      "physician":{
         ...
      },
      "priority":false,
      "requisition_form_url":null,
      "sample_id": "some_id,
      "shipping_details":null,
      "status":"received",
      "team_id":"f07f59d2-2903-4bcd-a2ac-3e87fa47c4bc",
      "updated_at":"2023-09-01T18:02:41.210495+00:00",
      "user_id":"f6cdf185-6815-4b2b-9482-798b75168689"
   },
   "event_type":"labtest.order.updated"
}
```


# Communications
Source: https://docs.junction.com/lab/walk-in/communications


Communication for patients is done via email or SMS, for Walk-in orders.
Customers have the following options when setting this up:

* `Default` - Email and SMS communications are enabled.
* `SMS Only or Email Only` - Only SMS or Email communication is enabled.
* `Disable` - All communications from Vital are disabled.

Each option has a different set of content and status changes, depending on what triggered them.

<Info>
  You can enable or disable SMS and Email communications individually through the [**Vital Dashboard**](http://app.tryvital.io/), under the Team Settings section.
</Info>

## Default Communications

### SMS Messages

A table of the **Order Status** and **default SMS** is provided bellow:

| Order Status            | Default Message                                                                                                                                                                                                                           |
| ----------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `ordered`               | *`"Hi, {patient_first_name}, your order for the {team_name} walk-in-test has been placed! We'll provide you with updates on the status of your order via text messages :)."`*                                                             |
| `requisition_created`   | *`"Hey {patient_first_name}, it's time to visit your local {lab_name} center. Please check the email you just received for instructions."`*                                                                                               |
| `appointment_scheduled` | `"Your appointment with the lab has been booked at {date} over at {address}! Here's your appointment key: {appointment_key}` <Note>   This message is sent only for Quest orders and Quest appointments placed through Vital API. </Note> |
| `appointment_cancelled` | *`"Hey, your lab appointment at {date} for {team_name} has been cancelled."`* <Note>   This message is sent only for Quest orders and Quest appointments placed through Vital API. </Note>                                                |
| `completed`             | *"Your results have finished processing, your results should be ready soon."*                                                                                                                                                             |
| `cancelled`             | *`"Hey, your order for the {team_name} walk-in-test has been cancelled. If this is by accident please contact support."`*                                                                                                                 |

<Info>
  SMS Texts are customizable, and can be enabled or disabled individually.
</Info>

### Emails

For emails, the following table describes what information each email contains for each Order Statuses:

| Order Status          | Email Content Description                                                                              |
| --------------------- | ------------------------------------------------------------------------------------------------------ |
| `requisition_created` | An email with confirmation of the partner Lab and additional instructions will be sent to the patient. |

<Info>
  Emails can be customised and sent from your own domain.
</Info>

## Disable Communications

In this case, no communications will be sent from Vital. You have the ability to produce completely customized communications
using the [`Webhook events`](/lab/at-home-phlebotomy/webhooks) described previously.


# Order and Appointment Lifecycle
Source: https://docs.junction.com/lab/walk-in/order-lifecycle


The **Walk-In Phlebotomy** orders are composed of two different lifecycles, the **Order** lifecycle and
the **appointment** lifecycle, detailed in the following sections.

## Order Lifecycle

As discussed in [`Lab Test Lifecycle - Statuses`](/lab/workflow/lab-test-lifecycle#statuses),
each lab testing modality has the following format

`[HIGH-LEVEL STATUS].[TEST MODALITY].[LOW-LEVEL STATUS]`

For each modality, there can be multiple **low-level status**, for **Walk-In Phlebotomy** the
possible low-level status are:

* `ordered`: Vital received the order, stored it into our system, and started processing it asynchronously.
* `requisition_created`: An order requisition form was validated and created with the partner laboratory, making the order available to be carried out.
* `requisition_bypassed`: An order requisition form wasn't created when the order was placed with us because it already existed.
* `appointment_pending`: An appointment was placed in Vital's system for the order, but doesn't have a scheduled date.
* `appointment_scheduled`: An appointment was scheduled or rescheduled for the order.
* `appointment_cancelled`: The appointment was cancelled, by either the patient, Vital or you.
* `partial_results`: The laboratory has started making partial results available.
* `completed`: The laboratory processed the blood sample and final results are available.
* `cancelled`: The order was cancelled by either the patient, Vital or you.

The Finite State Machine that defines the possible transitions for the low-level statuses described above is illustrated
in the following diagram.

<Frame caption="Possible state transitions for the Walk-In Phlebotomy Order low-level statuses.">
  <img src="https://mintcdn.com/vital/img/walkin-statuses.png?maxW=796&auto=format&n=nR1fvAlwouZ87zVb&q=85&s=f0565210d851bbf7993d084d42794ec7" width="796" height="996" data-path="img/walkin-statuses.png" srcset="https://mintcdn.com/vital/img/walkin-statuses.png?w=280&maxW=796&auto=format&n=nR1fvAlwouZ87zVb&q=85&s=12b99b8b84befc4da56fc7b89e9885cc 280w, https://mintcdn.com/vital/img/walkin-statuses.png?w=560&maxW=796&auto=format&n=nR1fvAlwouZ87zVb&q=85&s=ad4c31069591a35120fc240098b3026e 560w, https://mintcdn.com/vital/img/walkin-statuses.png?w=840&maxW=796&auto=format&n=nR1fvAlwouZ87zVb&q=85&s=92f05a4ba771af50354567cec974e359 840w, https://mintcdn.com/vital/img/walkin-statuses.png?w=1100&maxW=796&auto=format&n=nR1fvAlwouZ87zVb&q=85&s=3fe290a4e0ebf2b7e6484d5469662273 1100w, https://mintcdn.com/vital/img/walkin-statuses.png?w=1650&maxW=796&auto=format&n=nR1fvAlwouZ87zVb&q=85&s=0a2f27ff478eef7e7fff42f587619d30 1650w, https://mintcdn.com/vital/img/walkin-statuses.png?w=2500&maxW=796&auto=format&n=nR1fvAlwouZ87zVb&q=85&s=1b5dc918aa9811e391b587dd8b2c8d55 2500w" data-optimize="true" data-opv="2" />
</Frame>

<br />

<Info>In **sandbox**, there is no async transition from the `ordered` state to the `requisition_created` state, this must be **manually triggered** via the **Vital Dashboard**.</Info>

## Appointment Lifecycle

The appointment lifecycle is separate from the order lifecyle, and it corresponds to a single appointment.
The possible status are defined as follows:

* `pending`: An appointment was placed in the system, and is pending updates from the phlebotomy service.
* `scheduled`: An appointment was scheduled or rescheduled.

The Finite State Machine that defines the possible transitions for the appointment statuses described above is illustrated
in the following diagram.

<Frame caption="Possible state transitions for the Walk-In Phlebotomy Appointment statuses.">
  <img src="https://mintcdn.com/vital/img/walkin_appt_statuses.png?maxW=1454&auto=format&n=nR1fvAlwouZ87zVb&q=85&s=f4e44197a29a8dbd39ae9c8beca97137" width="1454" height="854" data-path="img/walkin_appt_statuses.png" srcset="https://mintcdn.com/vital/img/walkin_appt_statuses.png?w=280&maxW=1454&auto=format&n=nR1fvAlwouZ87zVb&q=85&s=07dd102e2b0d60ec3945d5e65f02f9ca 280w, https://mintcdn.com/vital/img/walkin_appt_statuses.png?w=560&maxW=1454&auto=format&n=nR1fvAlwouZ87zVb&q=85&s=7fd8cb50535e5f025b17f10175b3065e 560w, https://mintcdn.com/vital/img/walkin_appt_statuses.png?w=840&maxW=1454&auto=format&n=nR1fvAlwouZ87zVb&q=85&s=3d2d4516c6c226ab3edf0705b11cce77 840w, https://mintcdn.com/vital/img/walkin_appt_statuses.png?w=1100&maxW=1454&auto=format&n=nR1fvAlwouZ87zVb&q=85&s=14cba661070040fed7f9aead0e04eca8 1100w, https://mintcdn.com/vital/img/walkin_appt_statuses.png?w=1650&maxW=1454&auto=format&n=nR1fvAlwouZ87zVb&q=85&s=d9d85d776ae5c9392f745678b032e8c8 1650w, https://mintcdn.com/vital/img/walkin_appt_statuses.png?w=2500&maxW=1454&auto=format&n=nR1fvAlwouZ87zVb&q=85&s=a20504fb89e05c80130979dcf9554f97 2500w" data-optimize="true" data-opv="2" />
</Frame>

The events are related to a single appointment. An order can have multiple existing appointments in Vital system, although only one appointment will be considered active
and returned when using the [GET Appointment endpoint](/api-reference/lab-testing/psc-schedulling/get-psc-appointment).


# Overview
Source: https://docs.junction.com/lab/walk-in/overview


Walk-in tests are one of our offered modalities.
This modality is focused on patients that are able to go to a Laboratory to have their blood drawn.

## Ordering Flow overview

To achieve this, a high-level overview of the process is defined as:

* An order is placed in Vital's system through our Dashboard or API.
* The order is added to a background queue and additional checks are made before a test requisition is created with the chosen Laboratory.
* After the requisition is created, some form of communication is carried out with the patient so he can go to the assigned partner Laboratory.
* After that, the patient can go at any time they want to the laboratory to have their blood drawn.
* The Laboratory processes the patient's blood sample and generates the required results.
* Vital exposes the results via API as soon as they are available, both on PDF and structured data via API.

To find out more details, see [`Order Lifecycle`](/lab/walk-in/order-lifecycle), [`Communications`](/lab/walk-in/communications) and [`Webhooks`](/lab/walk-in/webhooks).


# Webhooks
Source: https://docs.junction.com/lab/walk-in/webhooks


The following webhook events are of interest, when placing a Walk-in order. Those are
described in detail in the following sections.

## Order webhook events

Based on the status present in [`Order Lifecycle`](/lab/walk-in/order-lifecycle),
Vital will trigger two kinds of webhook events, [`labtest.order.created`](/event-catalog/labtest.order.created) and
[`labtest.order.updated`](/event-catalog/labtest.order.updated).

The `labtest.order.created` event is triggered when an order is created in the system,
having the `ordered` status, and all subsequent status changes will trigger a `labtest.order.updated` event in the system.

<Note>The `partial_results` status does not trigger a Webhook unless specifically requested from Vital.</Note>

The webhook payload body will have the following information if the Order is in the `completed` status:

```json Walk-in Order Updated
{
  "id": "84d96c03-6b1c-4226-ad8f-ef44a6bc08af",
  "team_id": "6353bcab-3526-4838-8c92-063fa760fb6b",
  "user_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "patient_details": { "dob": "2020-01-01", "gender": "male" },
  "patient_address": {
    "receiver_name": "John Doe",
    "first_line": "123 Main St.",
    "second_line": "Apt. 208",
    "city": "San Francisco",
    "state": "CA",
    "zip": "91189",
    "country": "United States",
    "phone_number": "+1123456789"
  },
  "details": {
    "type": "walk_in_test",
    "data": {
      "id": "a655f0e4-6405-4a1d-80b7-66f06c2108a7",
      "created_at": "2020-01-01T00:00:00Z",
      "updated_at": "2020-01-01T00:00:00Z"
    }
  },
  "sample_id": "123456789",
  "notes": "This is a note",
  "created_at": "2020-01-01T00:00:00Z",
  "updated_at": "2020-01-01T00:00:00Z",
  "status": "completed",
  "events": [
    {
      "id": 1,
      "created_at": "2022-01-01T00:00:00Z",
      "status": "received.walk_in_test.ordered"
    },
    {
      "id": 2,
      "created_at": "2022-01-02T00:00:00Z",
      "status": "received.walk_in_test.requisition_created"
    },
    {
      "id": 3,
      "created_at": "2022-01-03T00:00:00Z",
      "status": "collecting_sample.walk_in_test.appointment_pending"
    },
    {
      "id": 4,
      "created_at": "2022-01-03T00:00:00Z",
      "status": "collecting_sample.walk_in_test.appointment_scheduled"
    },
    {
      "id": 5,
      "created_at": "2022-01-04T00:00:00Z",
      "status": "sample_with_lab.walk_in_test.partial_results"
    },
    {
      "id": 6,
      "created_at": "2022-01-04T00:00:00Z",
      "status": "completed.walk_in_test.completed"
    }
  ]
}
```


# Ask on Order Entry (AOE)
Source: https://docs.junction.com/lab/workflow/aoe


Some biomarkers require answers to clinical questions, this is referred to as AOE. These can be as simple as the volume of a particular marker, or the ethnicity of the patient.

<Note>
  Questions that are related to fasting (e.g  code `FSTING`) do not need to be answered. Vital uses the default value you provided for fasting at the [lab test](/api-reference/lab-testing/post-test) creation time. However, if you do answer them, then the answered value overrides the preset test value.
</Note>

There are 4 types of AOE:

1. `choice`
2. `multiple_choice`
3. `numeric`
4. `text`

`choice` and `multiple_choice` have a set list of answers to pick from, while `numeric` and `text` don't and are free form responses.

AOE questions can also be required or optional.

## Where to find the questions

As these AOE are directly related to biomarkers, you can find them in the [`GET /v3/lab_tests/markers`](/api-reference/lab-testing/biomarkers) endpoint or in the [`GET /v3/lab_tests/{lab_test_id}/markers`](/api-reference/lab-testing/lab-test-markers) endpoint, in the `aoe` object.

As an example, let's look at the `Lead, Blood (Adult)` marker. We have omitted some extra questions for the sake of this doc.

```json
{
  "id": 173,
  "name": "Lead, Blood (Adult)",
  "provider_id": "007625",
  ...
  "questions": [
    {
      "id": 1234567890251,
      "code": "BLPURP",
      "type": "choice",
      "value": "BLOOD LEAD PURPOSE",
      "constraint": null,
      "answers": [
        {
          "id": 1234567890252,
          "code": "LCANS4",
          "value": "I - INITIAL"
        },
        {
          "id": 1234567890253,
          "code": "LCANS5",
          "value": "R - REPEAT"
        },
        {
          "id": 1234567890254,
          "code": "LCANS6",
          "value": "F - FOLLOW-UP"
        }
      ],
      "required": true,
      "sequence": 1
    },
  ]
`
```

Each question has it's own `id`, which will be required to answer it. The types we refer to above are an enum that is represented by `type`.

The `answers` list contains a list of possible answers in the case that `type` is one of `choice` or `multiple_choice`, otherwise it is empty.

`required` deems whether the questions MUST be answered in order for the order to be valid, otherwise a error will be shown `Missing required questions - "question"`.

## How to answer

Answering is done at order time, via the [`POST /v3/order`](/api-reference/lab-testing/create-order) endpoint, in the field `aoe_answers`.

This field has the following format:

```json
{
    "aoe_answers": [
        {
            "marker_id": <int>,
            "question_id": <int>,
            "answer": <str>,
        }
    ]
}
```

You will populate this list with the answers to the questions defined in the `marker` object, as explained [above](/lab/workflow/aoe#where-to-find-the-questions).

The `marker_id` refers to the Vital [marker id](/api-reference/lab-testing/biomarkers), and the `question_id` to the id of the question being answered.

For example, marker `Leader, Blood (Adult)`, has the following data:

```json
{
  "id": 173,
  "name": "Lead, Blood (Adult)",
  "provider_id": "007625",
  ...
  "questions": [
    {
      "id": 1234567890251,
      "code": "BLPURP",
      "type": "choice",
      "value": "BLOOD LEAD PURPOSE",
      "constraint": null,
      "answers": [
        {
          "id": 1234567890252,
          "code": "LCANS4",
          "value": "I - INITIAL"
        },
        {
          "id": 1234567890253,
          "code": "LCANS5",
          "value": "R - REPEAT"
        },
        {
          "id": 1234567890254,
          "code": "LCANS6",
          "value": "F - FOLLOW-UP"
        }
      ],
      "required": true,
      "sequence": 1
    },
  ]
```

In order to answer the required question, you will need the `marker_id` which is the `id` field, the `question_id` in `questions[0].id` and one of the `code` values in the `question[0].answers` field.

### Answer types

The `answer` field contains the actual answer to the question and it's value will depend on the type and question itself.

1. `choice` and `multiple_choice`

In this case, the `answer` should contain the `code` field in the list of `answers` provided, as shown [here](/lab/workflow/aoe#where-to-find-the-questions).

e.g The question is as follows for marker of id `173`:

```json
{
  "id": 173,
  "questions": [
    {
      "id": 1234567890251,
      "code": "BLPURP",
      "type": "choice",
      "value": "BLOOD LEAD PURPOSE",
      "constraint": null,
      "answers": [
        {
          "id": 1234567890252,
          "code": "LCANS4",
          "value": "I - INITIAL"
        },
        {
          "id": 1234567890253,
          "code": "LCANS5",
          "value": "R - REPEAT"
        },
        {
          "id": 1234567890254,
          "code": "LCANS6",
          "value": "F - FOLLOW-UP"
        }
      ],
      "required": true,
      "sequence": 1
    },
  ]
}
```

The answer is:

```json
{
    "aoe_answers": [
        {
            "marker_id": 173,
            "question_id": 1234567890251,
            "answer": "LCANS4",
        }
    ]
}
```

2. `text`

This case can encompass many responses, and depends on the question itself.

<Note>
  In some instances, the `text` case contains a `constraint` field. This is a string tooltip indicator of the constraints applied by the lab on this particular question.
</Note>

e.g The question is as follows for marker of id `173`:

```json
{
  "id": 173,
  "questions": [
    {
      "id": 1234567890304,
      "code": "EDDATE",
      "type": "text",
      "constraint": null,
      "value": "EDD/EDC DATE",
      "answers": [],
      "required": true,
      "sequence": 2
    }, 
  ]
}
```

The answer is:

```json
{
    "aoe_answers": [
        {
            "marker_id": 173,
            "question_id": 1234567890304,
            "answer": "19900101",
        }
    ]
}
```

3. `numeric`

In this case, the `answer` should be a numeric string representation of the actual value.

e.g The question is as follows for marker of id `173`:

```json
{
  "id": 173,
  "questions": [
    {
      "id": 1234567890240,
      "code": "COLVOL",
      "type": "numeric",
      "constraint": null,
      "value": "URINE VOLUME (MILLILITERS)",
      "answers": [],
      "required": true,
      "sequence": 1
    }
  ]
}
```

The answer is:

```json
{
    "aoe_answers": [
        {
            "marker_id": 173,
            "question_id": 1234567890240,
            "answer": "1000",
        }
    ]
}
```


# Cancelling an Order
Source: https://docs.junction.com/lab/workflow/cancelling-an-order


Cancelling an order depends how far along in the process the order is in. If an order is early enough in its lifecycle, i.e.:

1. Requisition form is not generated.
2. Order wasn't send.
3. The phlebotomist is not on their way.

It's possible to cancel it by making a request to the [cancel endpoint](/lab/workflow/cancelling-an-order#cancel-endpoint).

For at-home phlebotomy, cancel the appointment first if it has been scheduled. You can cancel a phlebotomy appointment by making a request to the [phlebotomy appointment cancellation endpoint](/lab/workflow/cancelling-an-order#cancel-appointment-endpoint).

<Warning>
  When it comes to cancelling an order, to avoid the financial costs associated with late cancelling, we advise the following:

  * For test-kits, we recommend cancelling the order before it's shipped. Kits are typically shipped within 24 hours after they are ordered.
  * For at-home phlebotomy, appointments can be cancelled without consequence with a notice of at least 24 hours. Cancelling an order with less than 24h notice may incur a financial cost.
</Warning>

### Cancel appointment endpoint

<CodeGroup>
  ```bash cURL
  curl --request PATCH \
       --url '{{BASE_URL}}/v3/order/<order_id>/phlebotomy/appointment/cancel' \
       --header 'accept: application/json' \
       --header 'x-vital-api-key: {YOUR_KEY}' \
       --data '{"cancellation_reason_id": "7dfd7da5-ed6e-40bb-a7e4-c8003f0c10a9"}'
  ```

  ```python Python
  from vital.client import Vital
  from vital.environment import VitalEnvironment

  client = Vital(
    api_key="YOUR_API_KEY",
    environment=VitalEnvironment.SANDBOX
  )

  client.lab_tests.cancel_phlebotomy_appointment(
  		order_id="<order_id>",
  		cancellation_reason_id="<cancellation_reason_id>",
  )
  ```

  ```javascript Node
  import { VitalClient, VitalEnvironment } from '@tryvital/vital-node';
  import {  AppointmentCancelRequest } from '@tryvital/vital-node/api';

  const client = new VitalClient({
      apiKey: '<my_api_key>',
      environment: VitalEnvironment.Sandbox,
  });

  const request: AppointmentCancelRequest = {
      cancellationReasonId: "<reason_id>",
  }

  const data = await client.labTests.cancelPhlabotomyAppointment("<order_id>", request);
  ```

  ```java Java
  import com.vital.api.Vital;
  import com.vital.api.core.Environment;
  import com.vital.api.resources.labtests.requests.AppointmentCancelRequest;

  Vital vital = Vital.builder()
          .apiKey("YOUR_API_KEY")
          .environment(Environment.SANDBOX)
          .build();

  AppointmentCancelRequest request = AppointmentCancelRequest
          .builder()
          .cancellationReasonId("<reason_id")
          .build();

  var data = vital.labTests().cancelPhlabotomyAppointment("<order_id>", request);
  ```

  ```go Go
  import (
    "context"

    vital "github.com/tryVital/vital-go"
    vitalclient "github.com/tryVital/vital-go/client"
    "github.com/tryVital/vital-go/option"
  )

  client := vitalclient.NewClient(
    option.WithApiKey("<YOUR_API_KEY>"),
    option.WithBaseURL(vital.Environments.Sandbox),
  )

  request := &vital.AppointmentCancelRequest{
      CancellationReasonId: "<cancellation_reason_id>",
  }

  response, err := client.LabTests.CancelPhlabotomyAppointment(context.TODO(), "<order_id>", request)
  if err != nil {
      return err
  }
  fmt.Printf("Received data %s\n", response)
  ```
</CodeGroup>

You will receive a response specifying awhether the order was successfully cancelled or not.

```json Appointent Cancellation response
{
    "id": "413d7205-f8a9-42ed-aa4a-edb99e481ca0",
    "user_id": "202b2c2f-fb4c-44dc-a4f8-621186fde227",
    "address": {
        "first_line": "West Lincoln Street",
        "second_line": "",
        "city": "Phoenix",
        "state": "AZ",
        "zip_code": "85004",
        "unit": "14"
    },
    "location": {
        "lng": -112.0772235,
        "lat": 33.4421912
    },
    "start_at": "2023-05-17T20:00:00+00:00",
    "end_at": "2023-05-17T22:00:00+00:00",
    "iana_timezone": "America/Phoenix",
    "type": "phlebotomy",
    "provider": "getlabs",
    "status": "cancelled",
    "provider_id": "e89eb489-7382-4966-bb14-7ab4763eba6c",
    "can_reschedule": true
}
```

### Cancel endpoint

<CodeGroup>
  ```bash cURL
  curl --request DELETE \
       --url {{BASE_URL}}/v3/lab_test/<order_id>/cancel \
       --header 'Accept: application/json' \
       --header 'x-vital-api-key: <API_KEY>' \
       --header 'Content-Type: application/json' \
  ```

  ```python Python
  from vital import Client

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

  data = client.LabTests.cancel_order(order_id='<order_id>');
  ```

  ```javascript Node
  import { VitalClient, VitalEnvironment } from '@tryvital/vital-node';

  const client = new VitalClient({
      apiKey: '<my_api_key>',
      environment: VitalEnvironment.Sandbox,
  });

  const data = await client.labTests.cancelOrder("<order_id>");
  ```

  ```java Java
  import com.vital.api.Vital;
  import com.vital.api.core.Environment;

  Vital vital = Vital.builder()
          .apiKey("YOUR_API_KEY")
          .environment(Environment.SANDBOX)
          .build();

  var data = vital.labTests().cancelOrder("<order_id>");
  ```

  ```go Go
  import (
    "context"

    vital "github.com/tryVital/vital-go"
    vitalclient "github.com/tryVital/vital-go/client"
    "github.com/tryVital/vital-go/option"
  )

  client := vitalclient.NewClient(
    option.WithApiKey("<YOUR_API_KEY>"),
    option.WithBaseURL(vital.Environments.Sandbox),
  )

  response, err := client.LabTests.CancelOrder(context.TODO(), "<order_id>")
  if err != nil {
    return err
  }
  fmt.Printf("Received data %s\n", response)
  ```
</CodeGroup>

You will receive a response specifying whether the order was successfully cancelled or not.

```json Cancellation response
{
        "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6"),
        "user_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
        "patient_details": {"dob": "2020-01-01", "gender": "male"},
        "patient_address": {
            "receiver_name": "John Doe",
            "first_line": "123 Main St.",
            "second_line": "Apt. 208",
            "city": "San Francisco",
            "state": "CA",
            "zip": "91189",
            "country": "United States",
            "phone_number": "+1123456789",
        },
        "details": {
            "type": "testkit",
            "data": {
                "id": "a655f0e4-6405-4a1d-80b7-66f06c2108a7",
                "shipment": {
                    "id": "d55210cc-3d9f-4115-8262-5013f700c7be",
                    "outbound_tracking_number": "<outbound_tracking_number>",
                    "outbound_tracking_url": "<outbound_tracking_url>",
                    "inbound_tracking_number": "<inbound_tracking_number>",
                    "inbound_tracking_url": "<inbound_tracking_url>",
                    "outbound_courier": "usps",
                    "inbound_courier": "usps",
                    "notes": "<notes>",
                    "created_at": "2020-01-01T00:00:00.000Z",
                    "updated_at": "2020-01-01T00:00:00.000Z",
                },
                "created_at": "2020-01-01T00:00:00Z",
                "updated_at": "2020-01-01T00:00:00Z",
            },
        },
        "diagnostic_lab_test": {
            "name": "Lipids Panel",
            "description": "Cholesterol test",
            "method": "testkit",
        },
        "sample_id": "123456789",
        "notes": "This is a note",
        "created_at": "2020-01-01T00:00:00Z",
        "updated_at": "2020-01-01T00:00:00Z",
        "status": "cancelled",
        "events": [
            {
                "id": 1,
                "created_at": "2022-01-01T00:00:00Z",
                "status": "received.testkit.ordered",
            },
            {
                "id": 2,
                "created_at": "2022-01-01T00:00:00Z",
                "status": "cancelled.testkit.cancelled",
            }
    ],
}
```


# Creating a Lab Test
Source: https://docs.junction.com/lab/workflow/create-test


Vital provides a way to create your own lab tests. Lab tests are a collection or pre-set of orderable markers. These are made up of:

1. One or more marker IDs or Provider IDs.
2. The collection method: `testkit`, `walk_in_test`, `at_home_phlebotomy`, or `on_site_collection`.

Once a Lab Test is created and approved, you can use it when making a order.

<Warning>
  When you create a Lab Test, it is not immediately available. We need to
  validate and approve it on our side, before you can use it when making orders.
</Warning>

### Example

To begin, make a request to our [`GET /v3/lab_tests/markers`](/api-reference/lab-testing/biomarkers) endpoint, in order to choose the markers you want to test for.

```json Get all markers
{
  "markers": [
    {
      "id": 1,
      "name": "17-OH Progesterone LCMS",
      "slug": "17-oh-progesterone-lcms",
      "description": "17-OH Progesterone LCMS",
      "lab_id": 1,
      "provider_id": "070085",
      "type": null,
      "unit": null,
      "price": "N/A"
    },
    {
      "id": 2,
      "name": "ABO Grouping",
      "slug": "abo-grouping",
      "description": "ABO Grouping",
      "lab_id": 1,
      "provider_id": "006056",
      "type": null,
      "unit": null,
      "price": "N/A"
    }
  ],
  "total": 2,
  "page": 1,
  "size": 2
}
```

With this information, you can create a lab test using [`POST /v3/lab_tests`](/api-reference/lab-testing/post-test).

As an example, let's say you wanted a test from `Labcorp`, with markers with provider ids `006056` and `070085`:

```python Create a new test
from vital import Client

client = Client(api_key, "sandbox")

data = client.LabTests.create_test(
  name="Example test",
  description="Example test",
  method="at_home_phlebomoty",
  provider_ids=["006056", "070085"] # or use the marker ids e.g marker_ids=[1, 2],
)
```

<Note>
  It is possible to create a test with either the marker id or provider id. Provider ids are the recommended way, since these are shared accross environments. Not all labs provide these, so in their absence, use the marker id.
</Note>

Once your lab test creation is successful you will receive the following response:

```json
{
  "lab_test": {
    "name": "Example test",
    "description": "Example test",
    "sample_type": "serum",
    "method": "at_home_phlebomoty",
    "price": 10,
    "is_active": false,
    "lab": {
      "slug": "labcorp",
      "name": "LabCorp",
      "first_line_address": "123 Main St",
      "city": "San Francisco",
      "zipcode": "91789"
    },
    "markers": [
      {
        "name": "17-OH Progesterone LCMS",
        "slug": "17-oh-progesterone-lcms",
        "description": "17-OH Progesterone LCMS"
      },
      {
        "name": "ABO Grouping",
        "slug": "abo-grouping",
        "description": "ABO Grouping"
      }
    ]
  }
}
```

Do notice that `is_active` is set to `false`. You can verify its status by calling the [lab tests endpoint](/api-reference/lab-testing/tests).


# Importing an Order
Source: https://docs.junction.com/lab/workflow/importing-order


<Card horizontal icon="person-digging" color="#57164A">
  This feature is in **closed beta**.

  Interested in this feature? Get in touch with your Customer Success Manager.
</Card>

If you want to track orders with Junction that weren’t originally placed with Junction, you can import an order.

<Warning>
  It's crucial that imported orders are created with the correct sample ID. This is the **requisition number** or **control number** for Labcorp orders, or the **lab reference ID** for Quest orders. If in doubt, contact your Junction Customer Service Manager to confirm what you should supply for the sample ID.

  The sample ID must also uniquely identify the order. If you supply an ID that clashes with an existing order, that will result in a validation error.
</Warning>

An imported order can be cancelled, receive results, and functions similarly to orders originally placed with Junction, but with one important exception: a requisition will not be created. This means you cannot use the [endpoint to retrieve the requisition](/api-reference/lab-testing/requisition-pdf) for an imported order since Junction does not have access to it.

After an order is successfully imported, it will be in the `requisition_bypassed` state (for example, an imported testkit order would have a `received.testkit.requisition_bypassed` status). This status supports transitioning to the same states that `requisition_created` does.

<Info>
  Since import skips the regular order creation flow, no communications are sent to patients about the order being created, but communications are sent for subsequent events that might occur (order completion, for example).
</Info>

### Example

```python Python
from vital.client import Vital
from vital.environment import VitalEnvironment
from vital.types.billing import Billing
from vital.types.gender import Gender
from vital.types.lab_test_collection_method import LabTestCollectionMethod
from vital.types.order_set_request import OrderSetRequest
from vital.types.patient_address_compatible import PatientAddressCompatible
from vital.types.patient_details import PatientDetails
from vital.types.physician_create_request import PhysicianCreateRequest
from datetime import datetime

client = Vital(
  api_key="YOUR_API_KEY",
  environment=VitalEnvironment.SANDBOX
)

data = client.lab_tests.import_order(
    user_id="63661a2b-2bb3-4125-bb1a-b590f64f057f",
    billing_type=Billing.CLIENT_BILL,
    order_set=OrderSetRequest(lab_test_ids=["0e18c2f8-0740-475d-8868-431f7e9c0cfd"]),
    collection_method=LabTestCollectionMethod.WALK_IN_TEST,
    physician=PhysicianCreateRequest(first_name="Jane", last_name="Doe", npi=""),
    patient_details=PatientDetails(
        first_name="John",
        last_name="Doe",
        dob=datetime.fromisoformat("2020-01-01"),
        gender=Gender.MALE,
        phone_number="+1123456789",
        email="email@email.com"
    ),
    patient_address=PatientAddressCompatible(
      receiver_name="John Doe",
      first_line="123 Main St.",
      second_line="Apt. 208",
      city="San Francisco",
      state="CA",
      zip="91189",
      country="US",
      phone_number="+1123456789"
    ),
    sample_id="1234567890",
)
```

This example assumes you provide your own physician. The physician must be provided if your team configuration is set up as delegated. The billing type provided must also be appropriate to your team configuration. These aspects will be validated when making the request.

Since the request represents an existing order, we don’t perform strict address validation on the patient address, to make it easier to import orders exactly as they were placed in the original interface.

The response object schema is the same as [creating an order](/api-reference/lab-testing/create-order).


# Lab Test Lifecycle
Source: https://docs.junction.com/lab/workflow/lab-test-lifecycle


## Introduction

We encapsulate our lab test modalities in the `order` object. This is the main object you will interact with, as it contains all the information related to that lab test. An order has a high-level status which represents where the order is throughout its lifecycle, e.g. received/delivered/completed/cancelled etc.

The high-level status is the same across test modalities. On top of that, each modality has its own sub-statuses, to represents lifecycle stages specific to that modality. For example, test-kits involve shipping of the box, so we have a whole set of statuses to track the shipment.

<Warning>
  **Please note**: To ensure future compatibility, we ask that you avoid exhaustive matching on enum values such as an order’s status. We may introduce new statuses (and other enum values) over time, and code that assumes all current values are exhaustive could break or fail to compile with SDK upgrades.

  To stay compatible and benefit from future enhancements, treat unknown values gracefully—for example, by using default cases or limiting checks to only the values your integration depends on.
</Warning>

## Statuses

Statuses are namespaced with the following format:

`[HIGH-LEVEL STATUS].[TEST MODALITY].[LOW-LEVEL STATUS]`

As an example, the status `collecting_sample.at_home_phlebotomy.appointment_scheduled` means the patient has scheduled an at-home phlebotomy appointment.

### High-level statuses

The high-level statuses of an order, are represented by `order.status`:

* `received`: we received the order, stored it into our system, and started processing it.
* `collecting_sample`: these track collecting the sample from the patient. For test-kits, these track the shipment of the kit. For at-home phlebotomy and walk-in tests, these track appointment scheduling and management.
* `sample_with_lab`: the lab received the sample and is currently analyzing it.
* `completed`: the order is complete and the results are ready.
* `cancelled`: the order has been cancelled, by you or the patient.
* `failed`: we failed to process the order.

Modality specific sub-statuses are encapsulated in the `order.events` list. These include a list of all the events for that test:

```json Test kit order status
{
        ...,
        "status": "cancelled",
        "events": [
            {
                "id": 1,
                "created_at": "2022-01-01T00:00:00Z",
                "status": "received.testkit.ordered",
            },
            {
                "id": 2,
                "created_at": "2022-01-01T00:00:00Z",
                "status": "received.testkit.requisition_created",
            },
            {
                "id": 3,
                "created_at": "2022-01-01T00:00:00Z",
                "status": "collecting_sample.testkit.transit_customer"
            },
    ],
}
```

Below is a full list of all the available statuses by test modality. The names should be self-descriptive. Please do not hesitate to contact us if you need any additional clarification!

### Test-kit statuses

* `received.testkit.ordered`
* `received.testkit.awaiting_registration`
* `received.testkit.testkit_registered`
* `received.testkit.requisition_created`
* `received.testkit.requisition_bypassed`
* `collecting_sample.testkit.transit_customer`
* `collecting_sample.testkit.out_for_delivery`
* `collecting_sample.testkit.with_customer`
* `collecting_sample.testkit.transit_lab`
* `collecting_sample.testkit.problem_in_transit_customer`
* `collecting_sample.testkit.problem_in_transit_lab`
* `sample_with_lab.testkit.delivered_to_lab`
* `completed.testkit.completed`
* `failed.testkit.failure_to_deliver_to_customer`
* `failed.testkit.failure_to_deliver_to_lab`
* `failed.testkit.sample_error`
* `failed.testkit.lost`
* `cancelled.testkit.cancelled`
* `cancelled.testkit.do_not_process`

### Walk-in visit statuses

* `received.walk_in_test.ordered`
* `received.walk_in_test.requisition_created`
* `received.walk_in_test.requisition_bypassed`
* `collecting_sample.walk_in_test.appointment_pending`
* `collecting_sample.walk_in_test.appointment_scheduled`
* `collecting_sample.walk_in_test.appointment_cancelled`
* `sample_with_lab.walk_in_test.partial_results`
* `completed.walk_in_test.completed`
* `failed.walk_in_test.sample_error`
* `cancelled.walk_in_test.cancelled`

### At-home phlebotomy statuses

* `received.at_home_phlebotomy.ordered`
* `received.at_home_phlebotomy.requisition_created`
* `received.at_home_phlebotomy.requisition_bypassed`
* `collecting_sample.at_home_phlebotomy.appointment_pending`
* `collecting_sample.at_home_phlebotomy.appointment_scheduled`
* `collecting_sample.at_home_phlebotomy.draw_completed`
* `collecting_sample.at_home_phlebotomy.appointment_cancelled`
* `sample_with_lab.at_home_phlebotomy.partial_results`
* `completed.at_home_phlebotomy.completed`
* `cancelled.at_home_phlebotomy.cancelled`

### On-site collection statuses (currently in beta testing)

* `received.on_site_collection.ordered`
* `received.on_site_collection.requisition_created`
* `received.on_site_collection.requisition_bypassed`
* `collecting_sample.on_site_collection.draw_completed`
* `sample_with_lab.on_site_collection.partial_results`
* `completed.on_site_collection.completed`
* `failed.on_site_collection.sample_error`
* `cancelled.on_site_collection.cancelled`


# Ordering a Registrable Testkit
Source: https://docs.junction.com/lab/workflow/order-registrable-testkit


Under the [standard Testkit ordering flow](/api-reference/lab-testing/create-order), you place a Testkit order for a specific patient. This resulting Testkit is bound to that patient, and the Testkit cannot be passed on to someone else.

With Registrable Testkits, Vital offers a different option — Testkits not bound to any specific patient can be ordered to a specific household address. The patient registration process is deferred until an actual patient intends to use the Testkit.

<Warning>
  Note that this only applies to Testkits, not Walk-in Phlebotomy or At-home Phlebotomy.
</Warning>

This involves two steps:

1. Ordering the Testkit.
2. Registering a patient.

After step 1, the order is sent to the requested address and generates all the same webhooks as a regular order would. However it is stuck on the `received.testkit.awaiting_registration` state, meaning that no requisition form is generated for this order, and no results can be obtained until step 2 is done.

After step 2, the order flow resumes as normal, the patient sends the `testkit` to the lab, the order is progressed to the `received.testkit.testkit_registered` state and, again, all the same webhooks as in the regular order flow are dispatched.

### Example

To make an order, make a request to our [`POST /v3/order/testkit`](/api-reference/lab-testing/create-unregistered-order), to fulfil step 1.

```python Python
from vital import Client

client = Client(api_key, "sandbox")

data = client.LabTests.create_unregistered_testkit_order(
  user_id="63661a2b-2bb3-4125-bb1a-b590f64f057f",
  lab_test_id="5b41f610-ebc5-4803-8f0c-a61c3bdc7faf",
  shipping_details={
    "receiver_name": "john Doe",
    "street": "123 Main St.",
    "street_number": "Apt. 208",
    "city": "San Francisco",
    "state": "CA",
    "zip": "91189",
    "country": "US",
    "phone_number": "+11234567890"
  }
)
```

The `testkit` is now ordered, and will be sent to the specified address. Once delivered, it can be kept until it's expiration.

Once the `testkit` is with it's intended patient, it should be registered (step 2).

In order to register, Vital requires a `sample_id`, which is found within the `testkit` itself. This is an unique identifier.
Vital also requires the patient details and address.
Besides this, if using Vital's physician network, then supplying the consents field is required. If providing your own physician, then the physician information is required.

For this example, we will assume the use of your own physician.

To register a `testkit` order, make a request to our [`POST /v3/order/testkit/register/`](/api-reference/lab-testing/register-order), to fulfil step 2.

```python Python
client = Client(api_key, "sandbox")

data = client.LabTests.register_testkit_order(
  user_id="63661a2b-2bb3-4125-bb1a-b590f64f057f",
  sample_id="123123123",
  patient_details={
    "first_name": "John",
    "last_name": "Doe",
    "dob": "2020-01-01",
    "gender": "male",
    "phone_number": "+1123456789",
    "email": "email@email.com"
  },
  patient_address={
    "receiver_name": "john Doe",
    "street": "123 Main St.",
    "street_number": "Apt. 208",
    "city": "San Francisco",
    "state": "CA",
    "zip": "91189",
    "country": "US"
  },
  physician={
    "first_name": "Doctor",
    "last_name": "Doc",
    "npi": "123123123"
  }
)
```

Your `testkit` order is now registered, and the order flow should resume as normal. For more information regarding the lifecycle of a test, refer to the [lab test lifecyle](/lab/workflow/lab-test-lifecycle) page.


# Order Requirements
Source: https://docs.junction.com/lab/workflow/order-requirements


### Consents

When you order a lab test through our API, you may have to collect consents from the patient and forward it to us. The following consents may include:

* `hipaa-authorization`.
* `terms-of-use`.
* `telehealth-informed-consent`.

### Physician

As mentioned [in the introduction](/lab/overview/introduction#features), you don't need to have your own Physician to place orders with Vital. When you [order a test](/lab/overview/quickstart#3-placing-an-order), you can pass an optional `physician` argument.
If provided, the order will use your physician. If not, your order will go through with Vital's physician network. For more information, please check [our lab testing page](https://tryvital.io/labs) and [book an introductory call with us](https://cal.com/team/vital/discovery-call).

### Minors

Ordering for minors (under 18 years old) requires a specific configuration, which you can request with your Junction Customer Success Manager.

Once enabled, you are able to order for a minor patient, by providing information regarding the medical proxy.

This information can be supplied at [ordering time](/api-reference/lab-testing/create-order#body-patient-details-medical-proxy), or at any time by updating the [user demographics](/api-reference/user/upsert-info#body-medical-proxy).


# Ordering
Source: https://docs.junction.com/lab/workflow/ordering


# Concepts

Vital has a series of concepts to grasp regarding ordering:

* [Lab Tests](/lab/workflow/create-test)
* [Lifecyle of an Order](/lab/workflow/lab-test-lifecycle)
* [AoE](/lab/workflow/aoe)
* [Registrable Kits](/lab/workflow/order-registrable-testkit)
* [Scheduled Orders](/lab/workflow/scheduled-orders)

In this document, we will focus on orderable panels/biomarkers.

### Markers

[*Markers*](/api-reference/lab-testing/biomarkers) are individual, orderable tests, at the lab level. So, for example, at *Labcorp* you can order a `Lipid Panel` test and a `Vitamin D` test, a `panel` and a `biomarker` respectively. At Vital, these are both refered to as **markers**.

### Lab Tests

[*Lab Tests*](/api-reference/lab-testing/post-test) are a collection of markers, or a preset combination of markers, that you can order. Using the example above, you can create a `Labcorp Lipid Panel and Vitamin D` lab test. You can then place orders at Vital using this preset. This is useful for situations where you repeatedly want to order the same markers.

# Ordering

When placing an [Order](/api-reference/lab-testing/create-order), you will see an `order_set` field. This is what defines what markers will be ordered.

There are multiple combinations allowed with this field, so let's explore all of them.

### Ordering a *Lab Test*

When ordering from **one** previously created *Lab Test*, the `order_set` field should be populated as follows:

<CodeGroup>
  ```python Python
  from vital.client import Vital
  from vital.environment import VitalEnvironment

  client = Vital(
    api_key="YOUR_API_KEY",
    environment=VitalEnvironment.SANDBOX
  )

  client.lab_tests.create_order(
          order_set=OrderSet(
              lab_test_ids=["lab_test_id"]
          )
          ...
  )
  ```
</CodeGroup>

### Ordering from multiple *Lab Tests*

You may want to combine two or more existing Lab Tests without creating a new one. This is possible by doing:

<CodeGroup>
  ```python Python
  from vital.client import Vital
  from vital.environment import VitalEnvironment

  client = Vital(
    api_key="YOUR_API_KEY",
    environment=VitalEnvironment.SANDBOX
  )

  client.lab_tests.create_order(
          order_set=OrderSet(
              lab_test_ids=["lab_test_id1", "lab_test_id_2"]
          )
          ...
  )
  ```
</CodeGroup>

### Ordering without a *Lab Test*

This is what Vital calls `à la carte` ordering. You may want to order from the marker compendium without creating a preset.

<Note>
  This is a team level configuration that must be requested from Vital. Not all markers can be ordered in this manner.
</Note>

It is possible to order `a-la-carte` using Vital `marker_ids` or the lab's `provider_id`.

<CodeGroup>
  ```python Python
  from vital.client import Vital
  from vital.environment import VitalEnvironment

  client = Vital(
    api_key="YOUR_API_KEY",
    environment=VitalEnvironment.SANDBOX
  )

  client.lab_tests.create_order(
          order_set=OrderSet(
              add_on=AddOn(
                  provider_ids=["322022"]
                  # marker_ids=[1] 
              )
          ),
          collection_method="walk_in_test",
          ...
  )
  ```
</CodeGroup>

### Order *Lab Tests* with extra *Markers*

You may also add extra **markers** to an order. For example, you want to order the `Labcorp Lipid Panel and Vitamin D` but for this particular patient, you also want to order a `CBC Panel`.

<CodeGroup>
  ```python Python
  from vital.client import Vital
  from vital.environment import VitalEnvironment

  client = Vital(
    api_key="YOUR_API_KEY",
    environment=VitalEnvironment.SANDBOX
  )

  client.lab_tests.create_order(
          order_set=OrderSet(
              lab_test_ids=["lab_test_id"],
              add_on=AddOn(
                  provider_ids=["322022"]
                  # marker_ids=[1] 
              )
          ),
          collection_method="walk_in_test",
          ...
  )
  ```
</CodeGroup>

<Note>
  When supplying the `add_on` field, it is always required to provide the `collection_method` field.
</Note>

## Collection Method

Further explored in the documentation, Vital also has the concept of *Collection Method*. Vital currently supports three methods, [`At Home Phlebotomy`](lab/at-home-phlebotomy/overview), [`Walk In Phlebotomy`](lab/walk-in/overview) and [`Testkits`](lab/testkits/overview).
When ordering, you must select one of these, either at lab test creation, or at ordering time.

<CodeGroup>
  ```python Python
  from vital.client import Vital
  from vital.environment import VitalEnvironment

  client = Vital(
    api_key="YOUR_API_KEY",
    environment=VitalEnvironment.SANDBOX
  )

  client.lab_tests.create_order(
          order_set=OrderSet(
              lab_test_ids=["lab_test_id"],
          ),
          collection_method="walk_in_test",
          ...
  )
  ```
</CodeGroup>

## À La Carte Markers

As mentioned above, not all `markers` are `a la carte` orderable. You can find which one's are orderable via the [GET /v3/lab\_tests/markers](/api-reference/lab-testing/biomarkers).

<CodeGroup>
  ```python Python
  from vital.client import Vital
  from vital.environment import VitalEnvironment

  client = Vital(
    api_key="YOUR_API_KEY",
    environment=VitalEnvironment.SANDBOX
  )

  markers = client.lab_tests.get_markers(
          name="322022",
          a_la_carte_enabled=True
  )

  if not all([m.a_la_carte_enabled for m in markers.markers]):
      raise Exception("Markers not a_la_carte_enabled")
  ```
</CodeGroup>

## Error Cases

With the existance of various allowed combinations with the `order_set` field, there's many validations that are done server side. Here are some of the errors you can expect to encounter:

### 400 Bad Request

1. `collection_method must be set if add_on is set`: When the `add_on` field is supplied, you must provide the `collection_method`.
2. `marker_ids or provider_ids must be set in add_on`: One of `marker_ids` or `provider_ids` must be set, if the `add_on` field is provided.
3. `cannot set both marker_ids and provider_ids in add_on`: Similarly, only one of the former fields can be provided.
4. `cannot order lab_tests from multiple labs`: You can only order multiple lab tests from the same lab.
5. `cannot order with lab tests with multiple collection methods`: You must supply a `collection_method` if ordering multiple lab tests with multiple collection methods.
6. `Lab <lab name> does not allow gender <gender value>`: The associated lab restricts which patient genders it accepts. This restriction applies to the entire lab, not to individual lab tests.


# Partial Result Notifications
Source: https://docs.junction.com/lab/workflow/partials


Orders may have partial results, meaning that the lab has made available part of the result, while the full result is not complete. In general, these are short lived and as such, Vital does not expose them via webhooks.
Some orders however have long lived partial results, specifically when one ordered marker takes significantly longer to result than the others.

In these situations, clients may want to be notified of the existance of partial results. As such, Vital provides a team level configuration that enables the delivery of partial result webhooks. Similarly to other events, these are triggered via a `labtest.order.updated` event in the system.

Orders can also experience multiple partials in their lifecycle. In these cases, Vital will send a webhook for each partial update. So if your order experiences two partial results before a final, complete result, you should expect to receive two `labtest.order.updated` webhooks with `partial` status.

For example, in the second partial result, you would receive a webhook with the following body:

<Note>Note that the `events` block contains two `sample_with_lab.walk_in_test.partial_results` events.</Note>

```json Walk-in Order Updated
{
  "id": "84d96c03-6b1c-4226-ad8f-ef44a6bc08af",
  "team_id": "6353bcab-3526-4838-8c92-063fa760fb6b",
  "user_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "patient_details": { "dob": "2020-01-01", "gender": "male" },
  "patient_address": {
    "receiver_name": "John Doe",
    "first_line": "123 Main St.",
    "second_line": "Apt. 208",
    "city": "San Francisco",
    "state": "CA",
    "zip": "91189",
    "country": "United States",
    "phone_number": "+1123456789"
  },
  "details": {
    "type": "walk_in_test",
    "data": {
      "id": "a655f0e4-6405-4a1d-80b7-66f06c2108a7",
      "created_at": "2020-01-01T00:00:00Z",
      "updated_at": "2020-01-01T00:00:00Z"
    }
  },
  "sample_id": "123456789",
  "notes": "This is a note",
  "created_at": "2020-01-01T00:00:00Z",
  "updated_at": "2020-01-01T00:00:00Z",
  "status": "sample_with_lab",
  "events": [
    {
      "id": 1,
      "created_at": "2022-01-01T00:00:00Z",
      "status": "received.walk_in_test.ordered"
    },
    {
      "id": 2,
      "created_at": "2022-01-02T00:00:00Z",
      "status": "received.walk_in_test.requisition_created"
    },
    {
      "id": 3,
      "created_at": "2022-01-03T00:00:00Z",
      "status": "sample_with_lab.walk_in_test.partial_results"
    },
    {
      "id": 4,
      "created_at": "2022-01-04T00:00:00Z",
      "status": "sample_with_lab.walk_in_test.partial_results"
    }
  ]
}
```


# Scheduled Orders
Source: https://docs.junction.com/lab/workflow/scheduled-orders


Vital provides a way to schedule your orders for a future date, both via the API and via the Vital Dashboard. A Scheduled order is
one that will only be fulfilled in the future, so it won't be created in the Partner Laboratories until the defined date. This is useful for
defining follow-up orders after placing an initial Lab Order for a patient.

## Ordering through the API

To place a scheduled order through the API, you should use the [Create Order endpoint](/api-reference/lab-testing/create-order),
passing the `activate_by` date parameter. The `activate_by` parameter defines when that order is scheduled for,
and it will move from the `ordered` to the `requisition_created` status when the date arrives.

If you want to query all placed orders, you may use [Get Orders endpoint](/api-reference/lab-testing/get-orders), passing an `order_activation_types` query parameter, which accept the following values `["current", "scheduled"]`.

* If the parameter is not provided, every order is returned.
* If `current` is provided, orders with a `null` `activate_by` date or with `activate_by` set before the current date are returned.
* If `scheduled` is provided, orders with an `activate_by` date greater than the current date are returned.

Placing a scheduled order for 6 of January of 2025 would look like this:

```json Placing a Scheduled Order request
{
  "user_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "patient_details": {
    "dob": "2022-07-06T22:20:26.796Z",
    "gender": "male | female",
    "email": "test@test.com"
  },
  "patient_address": {
    "receiver_name": "John Doe",
    "street": "Hazel Road",
    "street_number": "102",
    "city": "San Francisco",
    "state": "CA",
    "zip": "91789",
    "country": "U.S.",
    "phone_number": "+14158180852"
  },
  "lab_test_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "physician": {
    "first_name": "John",
    "last_name": "Doe",
    "email": "john@doe.com",
    "npi": "123456789",
    "licensed_states": ["CA", "NY"],
    "created_at": "2022-07-06T22:20:26.796Z",
    "updated_at": "2022-07-06T22:20:26.796Z"
  },
  "activate_by": "2025-01-06"
}
```

## Ordering through the Vital Dashboard

To place a Scheduled Order through the dashboard, just follow the normal procedure until you reach the Lab Testing selection screen.

<Frame caption="Select Lab Test.">
  <img src="https://mintcdn.com/vital/img/order_lab_testing_selection.png?maxW=2574&auto=format&n=nR1fvAlwouZ87zVb&q=85&s=930757017b176320eb2ddc6684a09b65" width="2574" height="1270" data-path="img/order_lab_testing_selection.png" srcset="https://mintcdn.com/vital/img/order_lab_testing_selection.png?w=280&maxW=2574&auto=format&n=nR1fvAlwouZ87zVb&q=85&s=ca0653a73bd6efd2c9c9b40ada7861ab 280w, https://mintcdn.com/vital/img/order_lab_testing_selection.png?w=560&maxW=2574&auto=format&n=nR1fvAlwouZ87zVb&q=85&s=d46bfa6de2d2ea7e6f9421c304ce6806 560w, https://mintcdn.com/vital/img/order_lab_testing_selection.png?w=840&maxW=2574&auto=format&n=nR1fvAlwouZ87zVb&q=85&s=42e6b064bccd4b062515d66dec245447 840w, https://mintcdn.com/vital/img/order_lab_testing_selection.png?w=1100&maxW=2574&auto=format&n=nR1fvAlwouZ87zVb&q=85&s=a21e13a25e7a58465ae41e1f6c86e698 1100w, https://mintcdn.com/vital/img/order_lab_testing_selection.png?w=1650&maxW=2574&auto=format&n=nR1fvAlwouZ87zVb&q=85&s=c978c21bbc1433ec86f0c764404b4770 1650w, https://mintcdn.com/vital/img/order_lab_testing_selection.png?w=2500&maxW=2574&auto=format&n=nR1fvAlwouZ87zVb&q=85&s=a5506536206af115e99b2182ffef633b 2500w" data-optimize="true" data-opv="2" />
</Frame>

Notice that there is a checkbox for defining this order as scheduled for the future, after the checkbox is selected you can pass in the desired scheduled date.

After that, you can filter out the `Scheduled` and `Current` orders in the dashboard using the filter in the orders listing.

<Frame caption="Order List filter.">
  <img src="https://mintcdn.com/vital/img/order_list_filter.png?maxW=2400&auto=format&n=nR1fvAlwouZ87zVb&q=85&s=0e4044ef57867adff3bc3b966fa8851f" width="2400" height="924" data-path="img/order_list_filter.png" srcset="https://mintcdn.com/vital/img/order_list_filter.png?w=280&maxW=2400&auto=format&n=nR1fvAlwouZ87zVb&q=85&s=718b815ce18d04bdf8d145d369e680ff 280w, https://mintcdn.com/vital/img/order_list_filter.png?w=560&maxW=2400&auto=format&n=nR1fvAlwouZ87zVb&q=85&s=51c91c07d52c94a40a30f57614f1ab55 560w, https://mintcdn.com/vital/img/order_list_filter.png?w=840&maxW=2400&auto=format&n=nR1fvAlwouZ87zVb&q=85&s=6aea2999c21c6a1ed3c256d2b0c83ad0 840w, https://mintcdn.com/vital/img/order_list_filter.png?w=1100&maxW=2400&auto=format&n=nR1fvAlwouZ87zVb&q=85&s=49963f0d27470217d88d32c4e47a2aa2 1100w, https://mintcdn.com/vital/img/order_list_filter.png?w=1650&maxW=2400&auto=format&n=nR1fvAlwouZ87zVb&q=85&s=e6fded9eae4df20a7971090b10cbd3e2 1650w, https://mintcdn.com/vital/img/order_list_filter.png?w=2500&maxW=2400&auto=format&n=nR1fvAlwouZ87zVb&q=85&s=4b8450f555acd10eaa704b71b16ed974 2500w" data-optimize="true" data-opv="2" />
</Frame>


# Provider Types
Source: https://docs.junction.com/wearables/connecting-providers/auth_types


Providers have different authentication flows. Some require a username and password, others require an email address and password. Vital supports the following provider types:

* `OAuth`
* `Email`
* `Email + Password`

The majority of providers are `OAuth` providers. These providers require a user to be redirected to a third party website to authenticate. Once authenticated, the user is redirected back to the link widget.
The `Email` and `Email + Password` providers require a user to enter their email address and password into the link widget. This is then sent to Vital and used to connect to the provider.

The list of providers and their oauth types are as follows:

### 'OAuth'

Current OAuth providers are:

| Provider     | Description                                                   |
| ------------ | ------------------------------------------------------------- |
| `Fitbit`     | Activity Trackers (all devices)                               |
| `Garmin`     | Fitness watches (all devices)                                 |
| `Oura`       | Smart Sleep tracking ring                                     |
| `Strava`     | Running & Cycling Social Network                              |
| `Wahoo`      | Cycling Equipment                                             |
| `iHealth`    | Blood pressure, Fitness scales, Glucometers & Fitness watches |
| `Withings`   | Fitness scales, watches and health monitors                   |
| `Google Fit` | Activity Trackers (all devices)                               |
| `Polar`      | Finnish sports tech pioneer                                   |
| `Cronometer` | Nutrition data                                                |
| `Omron`      | Blood Pressure data                                           |
| `WHOOP`      | Smart Activity Watches                                        |
| `Dexcom`     | Glucose monitors                                              |

To connect an oauth provider:

<CodeGroup>
  ```javascript Node
  import { VitalClient, VitalEnvironment } from '@tryvital/vital-node';
  import { LinkTokenExchange, LinkGenerateOauthLinkRequest, OAuthProviders } from '@tryvital/vital-node/api';


  const client = new VitalClient({
      apiKey: '<my_api_key>',
      environment: VitalEnvironment.Sandbox,
  });

  const request: LinkTokenExchange = {
      userId: "<user_id>",
  }
  const tokenResponse = await client.link.token(request)

  const linkRequest: LinkGenerateOauthLinkRequest = {
      vitalLinkToken: tokenResponse.linkToken,
  }

  const auth = await client.link.generateOauthLink(
      OAuthProviders.<provider>,
      linkRequest
  )
  ```

  ```python Python
  from vital.client import Vital
  from vital.environment import VitalEnvironment
  from vital.types.o_auth_providers import OAuthProviders

  client = Vital(
    api_key="YOUR_API_KEY",
    environment=VitalEnvironment.SANDBOX
  )

  token_response = client.link.token(user_id="<user_id>")

  oauth = client.link.generate_oauth_link(
    oauth_provider=OAuthProviders.<provider>,
    vital_link_token=token_response.link_token,
  )
  ```

  ```java Java
  import com.vital.api.Vital;
  import com.vital.api.core.Environment;
  import com.vital.api.resources.link.requests.LinkGenerateOauthLinkRequest;
  import com.vital.api.resources.link.requests.LinkTokenExchange;
  import com.vital.api.types.OAuthProviders;

  Vital vital = Vital.builder()
          .apiKey("YOUR_API_KEY")
          .environment(Environment.SANDBOX)
          .build();

  LinkTokenExchange request = LinkTokenExchange
          .builder()
          .userId("<user_id>")
          .build();

  var token_response = vital.link().token(request);

  LinkGenerateOauthLinkRequest link_request = LinkGenerateOauthLinkRequest
          .builder()
          .vitalLinkToken(token_response.getLinkToken())
          .build();

  var oauth = vital.link().generateOauthLink(OAuthProviders.OURA, link_request);
  ```

  ```go Go
  import (
    "context"

    vital "github.com/tryVital/vital-go"
    vitalclient "github.com/tryVital/vital-go/client"
    "github.com/tryVital/vital-go/option"
  )

  client := vitalclient.NewClient(
    option.WithApiKey("<YOUR_API_KEY>"),
    option.WithBaseURL(vital.Environments.Sandbox),
  )
  provider := vital.ProvidersOura
  request := &vital.LinkTokenExchange{
    UserId:   "<user_id>",
    Provider: &provider,
  }

  response, err := client.Link.Token(context.TODO(), request)

  if err != nil {
    return err
  }

  generateLinkRequest := &vital.LinkGenerateOauthLinkRequest{
    VitalLinkToken: response.LinkToken,
  }

  oauth, err := client.Link.GenerateOauthLink(context.TODO(), vital.OAuthProvidersOura, generateLinkRequest)

  if err != nil {
    return err
  }
  fmt.Printf("Received data %s\n", oauth)
  ```
</CodeGroup>

For `OAuth` Providers we return an `oauth_url` that can be used to redirect users to. In a web view, on redirection, you should check the user has connected to the provider successfully. In the case of mobile, the user should receive a message to return to the app.

The possible error codes that are returned are as follows:

* `401 INVALID_REQUEST` Link Token is Invalid
* `400 MISSING_LINK_TOKEN` Missing link token
* `400 INVALID_PROVIDER` Provider is not supported
* `400 INVALID_USER_ID` User id is incorrect
* `400 INVALID_CREDENTIALS` Credentials for provider are incorrect

### 'Email'

Current email providers are:

| Provider    | Description                |
| ----------- | -------------------------- |
| `Freestyle` | Abbott CGM Glucose monitor |

### 'Email + Password'

Current email and password providers are:

| Provider            | Description                        |
| ------------------- | ---------------------------------- |
| `Zwift`             | Virtual cycling and running        |
| `Peloton`           | Popular Indoor Exercise bike       |
| `Eight Sleep`       | Smart Mattress                     |
| `Beurer`            | Blood pressure and glucose devices |
| `Hammerhead`        | Cycling Computer                   |
| `Dexcom G6 & Older` | CGM Glucose Monitor                |
| `MyFitnessPal`      | Meal Tracking Application          |
| `Kardia`            | EKG Application                    |

To connect a email and password provider:

<CodeGroup>
  ```javascript Node
  import { VitalClient, VitalEnvironment } from '@tryvital/vital-node';
  import { IndividualProviderData, PasswordProviders } from '@tryvital/vital-node/api';

  const request: IndividualProviderData = {
      username: '<username>',
      password: '<password>',
  }
  const data = await client.link.connectPasswordProvider(PasswordProviders.<provider>, request)
  ```

  ```python Python
  from vital.client import Vital
  from vital.environment import VitalEnvironment
  from vital.types.password_providers import PasswordProviders

  client = Vital(
    api_key="YOUR_API_KEY",
    environment=VitalEnvironment.SANDBOX
  )

  data = client.link.connect_password_provider(
    PasswordProviders.<provider>,
    username="<username>",
    password="<password>"
  )
  ```

  ```java Java
  import com.vital.api.Vital;
  import com.vital.api.core.Environment;
  import com.vital.api.resources.link.requests.IndividualProviderData;
  import com.vital.api.types.PasswordProviders;

  Vital vital = Vital.builder()
          .apiKey("YOUR_API_KEY")
          .environment(Environment.SANDBOX)
          .build();

  IndividualProviderData request = IndividualProviderData
          .builder()
          .username("<username>")
          .password("<password>")
          .build();

  var data = vital.link().connectPasswordProvider(PasswordProviders.<provider>, request);
  ```

  ```go Go
  import (
    "context"

    vital "github.com/tryVital/vital-go"
    vitalclient "github.com/tryVital/vital-go/client"
    "github.com/tryVital/vital-go/option"
  )

  client := vitalclient.NewClient(
    option.WithApiKey("<YOUR_API_KEY>"),
    option.WithBaseURL(vital.Environments.Sandbox),
  )

  request := &vital.IndividualProviderData{
    Username: "<username>",
    Password: "<password>",
  }

  response, err := client.Link.ConnectPasswordProvider(
    context.TODO(),
    vital.PasswordProviders<provider>,
    request
  )
  if err != nil {
    return err
  }
  fmt.Printf("Received data %s\n", response)
  ```
</CodeGroup>


# Bring Your Own OAuth
Source: https://docs.junction.com/wearables/connecting-providers/bring-your-own-oauth/overview


<Info>
  Bring Your Own OAuth (BYOO) is available for [the Grow and Scale plans](https://tryvital.io/pricing).
  WHOOP BYOO is available for [the Launch, Grow and Scale plans](https://tryvital.io/pricing). See [our WHOOP Guide](/wearables/guides/whoop) for more information.
</Info>

Vital supports bringing your own OAuth application credentials, so that your user would see the OAuth consent flow
in your own brand when they connect to cloud-based OAuth providers.

This provides a more cohesive experience for your users as it gives a truly whitelabelled experience for your application/mobile application.

Typically when you don't use custom credentials your oauth screen will look like this and used our shared credentials:

<img src="https://mintcdn.com/vital/img/default_credentials.png?maxW=2988&auto=format&n=nR1fvAlwouZ87zVb&q=85&s=04b95b231b872f9398549cf4b0d36119" alt="Default Credentials" width="2988" height="1700" data-path="img/default_credentials.png" srcset="https://mintcdn.com/vital/img/default_credentials.png?w=280&maxW=2988&auto=format&n=nR1fvAlwouZ87zVb&q=85&s=d2117132fc6cbbce081341bd02c73149 280w, https://mintcdn.com/vital/img/default_credentials.png?w=560&maxW=2988&auto=format&n=nR1fvAlwouZ87zVb&q=85&s=9d843df8a30599b24da84940ddb51269 560w, https://mintcdn.com/vital/img/default_credentials.png?w=840&maxW=2988&auto=format&n=nR1fvAlwouZ87zVb&q=85&s=ac1ada38b021d86b113491f8da0a9088 840w, https://mintcdn.com/vital/img/default_credentials.png?w=1100&maxW=2988&auto=format&n=nR1fvAlwouZ87zVb&q=85&s=28b9ede4ef69f145bc39b9b84b5d746d 1100w, https://mintcdn.com/vital/img/default_credentials.png?w=1650&maxW=2988&auto=format&n=nR1fvAlwouZ87zVb&q=85&s=b3810c7050126f6485c1b0adf2dd743d 1650w, https://mintcdn.com/vital/img/default_credentials.png?w=2500&maxW=2988&auto=format&n=nR1fvAlwouZ87zVb&q=85&s=738de12a1ebd055cd1edfe7d999220fc 2500w" data-optimize="true" data-opv="2" />

With custom credentials you can use your own team name and setup your own logo for the provider.

## OAuth Providers supporting BYOO

<Warning>
  Some BYOO providers do not have a developer program with open sign-up.
</Warning>

| Provider                                            | Slug                | Remarks                                 |
| --------------------------------------------------- | ------------------- | --------------------------------------- |
| [Fitbit](https://www.fitbit.com/global/uk/home)     | `fitbit`            | -                                       |
| [Garmin](https://www.garmin.com)                    | `garmin`            | -                                       |
| [Google Fit](https://www.google.com/fit/)           | `google_fit`        | -                                       |
| [Oura](https://ouraring.com)                        | `oura`              | -                                       |
| [Strava](https://www.strava.com)                    | `strava`            | -                                       |
| [Wahoo](https://wahoofitness.com)                   | `wahoo`             | -                                       |
| [Withings](https://www.withings.com)                | `withings`          | -                                       |
| [Dexcom](https://www.dexcom.com)                    | `dexcom_v3`         | [↗️ Guide](/wearables/guides/dexcom_v3) |
| [WHOOP](https://www.whoop.com)                      | `whoop_v2`          | [↗️ Guide](/wearables/guides/whoop)     |
| [Polar](https://www.polar.com/accesslink-api/)      | `polar`             | -                                       |
| [Cronometer](https://www.cronometer.com)            | `cronometer`        | -                                       |
| [Omron](https://www.omron-healthcare.com)           | `omron`             | -                                       |
| [MyFitnessPal API](https://www.myfitnesspalapi.com) | `my_fitness_pal_v2` | -                                       |
| [MapMyFitness](https://developer.mapmyfitness.com)  | `map_my_fitness`    | -                                       |
| [Ultrahuman](https://www.ultrahuman.com)            | `ultrahuman`        | -                                       |

### Provider Rate Limits

<Note>
  This section documents the *starting* rate limit of a brand new OAuth application, should you choose to BYOO.
</Note>

| Provider                                        | Starting Rate Limit                                                                 |
| ----------------------------------------------- | ----------------------------------------------------------------------------------- |
| [Fitbit](https://www.fitbit.com/global/uk/home) | 150 requests per hour per user                                                      |
| [Garmin](https://www.garmin.com)                | 10,000 days of data per minute                                                      |
| [Google Fit](https://www.google.com/fit/)       | 600 requests per minute                                                             |
| [Oura](https://ouraring.com)                    | 5,000 requests per 5 minutes                                                        |
| [Strava](https://www.strava.com)                | 100 requests per 15 minutes<br />1,000 requests per day                             |
| [Wahoo](https://wahoofitness.com)               | 200 requests per 5 minutes<br />1,000 requests per hour<br />5,000 requests per day |
| [Withings](https://www.withings.com)            | 120 requests per minute                                                             |
| [Dexcom](https://www.dexcom.com)                | 60,000 requests per hour                                                            |
| [WHOOP](https://www.whoop.com)                  | 100 requests per minute<br />10,000 requests per day                                |
| [Polar](https://www.polar.com/accesslink-api/)  | 20 requests per 15 minutes per user<br />100 requests per day per user              |
| [Cronometer](https://www.cronometer.com)        | N/A                                                                                 |
| [Omron](https://www.omron-healthcare.com)       | N/A                                                                                 |

## Setting up your OAuth credentials

### Through the Org Management API

<OrgManagementAPI />

<Steps>
  <Step title="Setup your OAuth application">
    Use the [Prepare Team Custom Credentials](/api-reference/org-management/team-custom-credentials/prepare-team-custom-credentials)
    endpoint to obtain the instructions to setup your OAuth application.
  </Step>

  <Step title="Set your application credentials">
    Use the [Set Team Custom Credentials](/api-reference/org-management/team-custom-credentials/upsert-team-custom-credentials) endpoint
    to apply your OAuth application credentials to your Vital Team.

    <AccordionGroup>
      <Accordion title="Credentials that are activated immediately" icon="bolt" defaultOpen>
        BYOO credentials for the following providers are immediately active, once set through the [Set Team Custom Credentials](/api-reference/org-management/team-custom-credentials/upsert-team-custom-credentials):

        | Provider                                            | Slug                |
        | --------------------------------------------------- | ------------------- |
        | [Garmin](https://www.garmin.com)                    | `garmin`            |
        | [Google Fit](https://www.google.com/fit/)           | `google_fit`        |
        | [Oura](https://ouraring.com)                        | `oura`              |
        | [Strava](https://www.strava.com)                    | `strava`            |
        | [Wahoo](https://wahoofitness.com)                   | `wahoo`             |
        | [Withings](https://www.withings.com)                | `withings`          |
        | [Dexcom](https://www.dexcom.com)                    | `dexcom_v3`         |
        | [WHOOP](https://www.whoop.com)                      | `whoop_v2`          |
        | [Polar](https://www.polar.com/accesslink-api/)      | `polar`             |
        | [Cronometer](https://www.cronometer.com)            | `cronometer`        |
        | [Omron](https://www.omron-healthcare.com)           | `omron`             |
        | [Ultrahuman](https://www.ultrahuman.com)            | `ultrahuman`        |
        | [MyFitnessPal API](https://www.myfitnesspalapi.com) | `my_fitness_pal_v2` |
        | [MapMyFitness](https://developer.mapmyfitness.com)  | `map_my_fitness`    |
      </Accordion>

      <Accordion title="Credentials that need support intervention once set" icon="message-question" defaultOpen>
        The following providers are not immediately active. You need to take a couple of extra steps to activate them:

        [Fitbit](https://www.fitbit.com/global/uk/home) (`fitbit`)

        1. You must press the "Verify" button on all the Webhook Subscribers in the Fitbit Developer Portal.
        2. Once the buttons are gone and replaced by (usually zeroed) delivery statistics, it implies that Fitbit has completed the verification challenge with Vital.
      </Accordion>
    </AccordionGroup>
  </Step>
</Steps>

### Through Vital Support

To setup custom OAuth application credentials, you need to do the following:

1. Create a developer account with the cloud-based OAuth providers.
2. Generate a OAuth application credentials from your developer account. You can do this by going to the providers developer accounts page and creating a new application.
3. Email [Support@tryvital.io](mailto:Support@tryvital.io) or message us on Slack with the following information:
   * The provider you want to customize
   * The client ID and client secret for the provider
     * Use tools like [Doppler Secret Share](https://share.doppler.com) or [1Password](https://1password.com) to protect your credentials.
   * The redirect URI for the provider
   * The name of your team
   * The logo for your team
4. We will then setup the custom credentials for you and let you know when it's ready to go.

<Note>
  Some Oauth providers are unavailable unless you can <b>Bring Your Own OAuth (BYOO)</b> — you will have to apply directly
  to the provider for an OAuth application, and provide Vital your assigned credentials once the application is accepted.
</Note>


# Sharing Credentials
Source: https://docs.junction.com/wearables/connecting-providers/bring-your-own-oauth/sharing-credentials


## Audience

This guide is dedicated to Vital customers looking to share the usage of their OAuth Client Credentials
between Vital [Bring Your Own OAuth](/wearables/connecting-providers/bring-your-own-oauth/overview) and their
existing production systems.

This guide is not applicable if you:

* do not have existing OAuth Client Credentials; or
* can configure your OAuth Client Credentials to point exclusively at Vital.

## Background

Many providers use OAuth 2.0, in which each partner entity is registered as a confidential application.
Each application is issued one set of OAuth client credentials (client ID + secret).

As a Cross-Site Request Forgery (CSRF) mitigation, they also typically require every application to pre-register
a Redirect URI. The `/authorize` flow would then validate inbound requests against the Redirect URI on record.

## Challenge

Most providers allow **only one** Redirect URI registration per OAuth application.

This means your OAuth application cannot simutaneously support both your own existing OAuth callback endpoint, as well as
[Vital Link](/wearables/connecting-providers/introduction) OAuth callback endpoint.

## Recommended Apporach

To support this credential sharing use case, Vital recommends you to:

1. Continue to point your OAuth application at your existing OAuth callback endpoint;

2. Extend your endpoint to [detect and redirect](#details) callbacks from Vital Link originiated OAuth requests to the
   [Vital Link OAuth callback endpoint](#vital-oauth-callback-endpoint-url).

```mermaid
sequenceDiagram
    participant Vital Link
    participant Your API
    participant BYOO Provider
    actor User Agent
    autonumber
    Vital Link-->>User Agent: OAuth 2.0 Authorization Request URL
    User Agent->>BYOO Provider: Navigate to URL (1)
    BYOO Provider-->>User Agent: Prompt
    User Agent-->>BYOO Provider: Approve or Deny
    BYOO Provider->>Your API: Redirect
    Your API->>Vital Link: Redirect
```

### Details

<Steps>
  <Step title="Keep your current OAuth application settings">
    The Redirect URI in your OAuth application settings should continue to point at your
    existing OAuth callback endpoint.
  </Step>

  <Step title="Extend your existing OAuth callback endpoint with Vital Link awareness">
    Your OAuth callback endpoints can rely on the `state` query parameter to differentiate the request
    origin, i.e., whether it is from Vital or from your own production systems.

    OAuth requests originated from Vital would have the **Vital Link Token** as the `state` query parameter.
    Vital Link Token is a JSON Web Token (JWT), so you can use the *unverified claims* of the JWT as a discriminator.

    When you detect a valid Vital Link Token, perform a `307 Temporary Redirect`
    to the [Vital OAuth callback endpoint](#vital-oauth-callback-endpoint-url) and passing on *all* the URL query parameters.

    The exact JWT structure of the Vital Link Token is as follows:

    <AccordionGroup>
      <Accordion title="Encoding" defaultOpen>
        A JSON Web Token (JWT).

        <Warning>
          You need not verify the signature of this JWT.

          To prevent Cross-Site Request Forgery attacks, you must still check that the `aud` claim matches the
          expected [Vital Link API Base URL](#vital-link-api-base-url).
        </Warning>
      </Accordion>

      <Accordion title="Claim payload schema" defaultOpen>
        | Key       | Value                   |
        | --------- | ----------------------- |
        | `aud`     | Vital Link API Base URL |
        | `sub`     | Vital Link Session ID   |
        | `team_id` | Vital Team ID           |
        | `user_id` | Vital User ID           |
      </Accordion>

      <Accordion title="Vital Link API Base URL" defaultOpen>
        | Environment   | Base URL                                     |
        | ------------- | -------------------------------------------- |
        | Production US | `https://api.tryvital.io/v2/link`            |
        | Production EU | `https://api.eu.tryvital.io/v2/link`         |
        | Sandbox US    | `https://api.sandbox.tryvital.io/v2/link`    |
        | Sandbox EU    | `https://api.sandbox.eu.tryvital.io/v2/link` |
      </Accordion>

      <Accordion title="Vital OAuth callback endpoint URL" defaultOpen>
        | Environment   | Base URL                                                        |
        | ------------- | --------------------------------------------------------------- |
        | Production US | `https://api.tryvital.io/v2/link/connect/{PROVIDER}`            |
        | Production EU | `https://api.eu.tryvital.io/v2/link/connect/{PROVIDER}`         |
        | Sandbox US    | `https://api.sandbox.tryvital.io/v2/link/connect/{PROVIDER}`    |
        | Sandbox EU    | `https://api.sandbox.eu.tryvital.io/v2/link/connect/{PROVIDER}` |
      </Accordion>

      <Accordion title="Example" defaultOpen>
        ```python Python (FastAPI)
        import fastapi
        from urllib.parse import urlencode

        VITAL_LINK_BASE_URL = "https://api.tryvital.io/v2/link"

        @router.get("/oauth_callback/fitbit")
        def handle_oauth_callback(
            request: fastapi.Request,
            state: Annotated[str, fastapi.Query()],
            ...,
        ) -> fastapi.Response:
            state_string = base64.b64decode(state)

            # Test if this is a JWT.
            # If so, try to extract the unverified claim payload, and see if this is
            # a Vital Link JWT.
            if (
                state_string.startswith('{"')
                and (state_parts := state_string.split(".", maxsplit=3))
                and len(state_parts) == 3
                and (unverified_claims := json.loads(state_parts[1]))
                and unverified_claims.get("aud") == VITAL_LINK_BASE_URL
            ):
                query = urlencode(request.query_params)

                return fastapi.RedirectResponse(f"{VITAL_LINK_BASE_URL}/connect/fitbit?{query}")


            # Not a Vital Link JWT. Fallback to existing logic
            return process_oauth_callback(...)

        ```
      </Accordion>
    </AccordionGroup>
  </Step>

  <Step title="Register your OAuth callback endpoint with Vital">
    When you set your OAuth Client Credential through the [Set Team Custom Credentials](api-reference/org-management/team-custom-credentials/upsert-team-custom-credentials)
    endpoint, you must specify a Redirect URI override that points at your your OAuth callback endpoint.

    When a Redirect URI override is present, Vital uses the override value you provided to initiate the OAuth authorization flow.
  </Step>
</Steps>


# Building a Custom Widget
Source: https://docs.junction.com/wearables/connecting-providers/custom_widget


<Warning>
  Vital Link API covers **only** [cloud-based providers](/wearables/providers/introduction#cloud-based-providers).

  Your mobile app has to manage connections with SDK-based providers — such as Apple HealthKit and Android Health
  Connect — through the [Vital Mobile Health SDK](/wearables/sdks/vital-health), separately from Vital Link.
</Warning>

You may want to have your own custom Link widget to match your app's UI. This is useful for customers who don't want to use Vital link but still want to use the Vital API.
It's worthwhile ensuring that you have read the [Auth Types](/docs/auth-types) documentation before proceeding. A full code example in React Native can be seen [here](https://github.com/tryVital/vital-connect-rn).

An overview of the process is as follows:

1. Get a list of all available providers ["/v2/providers"](/docs/api-reference/providers)
2. Build your UI using this list of providers
3. When selecting a provider, generate a link token for that provider ["/v2/link/token"](/docs/api-reference/link/generate-link-token)
4. Use the link token to generate an oauth link, or authorize an email, or email and password.

## 1. List of all available providers

The first step to creating a custom widget is to make a call to the [providers endpoint](/docs/api-reference/providers). This will return a list of all available providers. You can then use this list to build your UI.

<CodeGroup>
  ```javascript Node
  import { VitalClient, VitalEnvironment } from "@tryvital/vital-node";
  import {
    LinkTokenExchange,
    LinkGenerateOauthLinkRequest,
    OAuthProviders,
  } from "@tryvital/vital-node/api";

  const client = new VitalClient({
    apiKey: "<my_api_key>",
    environment: VitalEnvironment.Sandbox,
  });

  const allProviders = await client.providers.getAll();

  // allProviders
  // [
  //   {
  //     "name": "Oura",
  //     "slug": "oura",
  //     "logo": "https://logo_url.com",
  //     "auth_type": "oauth",
  //     "supported_resources": ["workouts", "sleep"]
  //   }
  // ]
  ```

  ```python Python
  from vital.client import Vital
  from vital.environment import VitalEnvironment
  from vital.types.o_auth_providers import OAuthProviders

  client = Vital(
    api_key="YOUR_API_KEY",
    environment=VitalEnvironment.SANDBOX
  )

  all_providers = client.providers.get_all()

  # allProviders
  # [
  #   {
  #     "name": "Oura",
  #     "slug": "oura",
  #     "logo": "https://logo_url.com",
  #     "auth_type": "oauth",
  #     "supported_resources": ["workouts", "sleep"]
  #   }
  # ]
  ```

  ```java Java
  import com.vital.api.Vital;
  import com.vital.api.core.Environment;
  import com.vital.api.resources.link.requests.LinkGenerateOauthLinkRequest;
  import com.vital.api.resources.link.requests.LinkTokenExchange;
  import com.vital.api.types.OAuthProviders;

  Vital vital = Vital.builder()
          .apiKey("YOUR_API_KEY")
          .environment(Environment.SANDBOX)
          .build();

  var all_providers = vital.providers().getAll()
  ```

  ```go Go
  import (
    "context"

    vital "github.com/tryVital/vital-go"
    vitalclient "github.com/tryVital/vital-go/client"
    "github.com/tryVital/vital-go/option"
  )

  client := vitalclient.NewClient(
    option.WithApiKey("<YOUR_API_KEY>"),
    option.WithBaseURL(vital.Environments.Sandbox),
  )

  response, err := client.Providers.getAll(context.TODO())

  if err != nil {
    return err
  }

  fmt.Printf("Received data %s\n", response)
  ```
</CodeGroup>

## 2. Build your UI in your app

Once you have a list of all available providers, you can build your UI. You can use the `logo` field to display the provider's logo. You can use the `name` field to display the provider's name. You can use the `supported_resources` field to display the resources that the provider supports.

<Frame caption="Building a custom UI">
  <img src="https://mintcdn.com/vital/img/custom_ui.gif?maxW=600&auto=format&n=nR1fvAlwouZ87zVb&q=85&s=5b8ff0a1652fa3a7a34c740ac396b4a5" width="50%" alt="Custom UI" className="w-2/5 h-2/5 block mx-auto" width="600" height="1067" data-path="img/custom_ui.gif" srcset="https://mintcdn.com/vital/img/custom_ui.gif?w=280&maxW=600&auto=format&n=nR1fvAlwouZ87zVb&q=85&s=356a20201ce9ae49b15ca05871941ada 280w, https://mintcdn.com/vital/img/custom_ui.gif?w=560&maxW=600&auto=format&n=nR1fvAlwouZ87zVb&q=85&s=a24d79936c86b9152159df4326d27c12 560w, https://mintcdn.com/vital/img/custom_ui.gif?w=840&maxW=600&auto=format&n=nR1fvAlwouZ87zVb&q=85&s=2650eab420e9e86bad7a707d8e3df49c 840w, https://mintcdn.com/vital/img/custom_ui.gif?w=1100&maxW=600&auto=format&n=nR1fvAlwouZ87zVb&q=85&s=0ba3ea60b8a5e66e4d1be6858d7b0e2f 1100w, https://mintcdn.com/vital/img/custom_ui.gif?w=1650&maxW=600&auto=format&n=nR1fvAlwouZ87zVb&q=85&s=8864e6c5a160ff89377b9cda6572073d 1650w, https://mintcdn.com/vital/img/custom_ui.gif?w=2500&maxW=600&auto=format&n=nR1fvAlwouZ87zVb&q=85&s=256f4398588ab5474b18226e48ace098 2500w" data-optimize="true" data-opv="2" />
</Frame>

## 3. Generate a link token

Once a user has selected a provider, you can generate a link token. This link token is used to generate an oauth link, or authorize an email, or email and password. You can read more about the link token [here](/docs/api-reference/link#link-token-exchange).

<CodeGroup>
  ```javascript Node
  import { VitalClient, VitalEnvironment } from "@tryvital/vital-node";
  import {
    LinkTokenExchange,
    LinkGenerateOauthLinkRequest,
    OAuthProviders,
  } from "@tryvital/vital-node/api";

  const client = new VitalClient({
    apiKey: "<my_api_key>",
    environment: VitalEnvironment.Sandbox,
  });

  const request: LinkTokenExchange = {
    userId: "<user_id>",
  };
  const tokenResponse = await client.link.token(request);
  ```

  ```python Python
  from vital.client import Vital
  from vital.environment import VitalEnvironment
  from vital.types.o_auth_providers import OAuthProviders

  client = Vital(
    api_key="YOUR_API_KEY",
    environment=VitalEnvironment.SANDBOX
  )

  token_response = client.link.token(user_id="<user_id>")

  ```

  ```java Java
  import com.vital.api.Vital;
  import com.vital.api.core.Environment;
  import com.vital.api.resources.link.requests.LinkGenerateOauthLinkRequest;
  import com.vital.api.resources.link.requests.LinkTokenExchange;
  import com.vital.api.types.OAuthProviders;

  Vital vital = Vital.builder()
          .apiKey("YOUR_API_KEY")
          .environment(Environment.SANDBOX)
          .build();

  LinkTokenExchange request = LinkTokenExchange
          .builder()
          .userId("<user_id>")
          .build();

  var token_response = vital.link().token(request);

  ```

  ```go Go
  import (
    "context"

    vital "github.com/tryVital/vital-go"
    vitalclient "github.com/tryVital/vital-go/client"
    "github.com/tryVital/vital-go/option"
  )

  client := vitalclient.NewClient(
    option.WithApiKey("<YOUR_API_KEY>"),
    option.WithBaseURL(vital.Environments.Sandbox),
  )
  provider := vital.ProvidersOura
  request := &vital.LinkTokenExchange{
    UserId:   "<user_id>",
    Provider: &provider,
  }

  response, err := client.Link.Token(context.TODO(), request)

  fmt.Printf("Received data %s\n", response)
  ```
</CodeGroup>

## 4. Link the user to the provider

Once you have a link token, you can use it to generate an oauth link, or authorize an email, or email and password. You can read more about the link token [here](/docs/api-reference/link#link-token-exchange).

### Connect an oauth provider

<CodeGroup>
  ```javascript Node
  import { VitalClient, VitalEnvironment } from '@tryvital/vital-node';
  import { LinkTokenExchange, LinkGenerateOauthLinkRequest, OAuthProviders } from '@tryvital/vital-node/api';


  const client = new VitalClient({
      apiKey: '<my_api_key>',
      environment: VitalEnvironment.Sandbox,
  });

  const request: LinkTokenExchange = {
      userId: "<user_id>",
  }
  const tokenResponse = await client.link.token(request)

  const linkRequest: LinkGenerateOauthLinkRequest = {
      vitalLinkToken: tokenResponse.linkToken,
  }

  const auth = await client.link.generateOauthLink(
      OAuthProviders.<provider>,
      linkRequest
  )
  ```

  ```python Python
  from vital.client import Vital
  from vital.environment import VitalEnvironment
  from vital.types.o_auth_providers import OAuthProviders

  client = Vital(
    api_key="YOUR_API_KEY",
    environment=VitalEnvironment.SANDBOX
  )

  token_response = client.link.token(user_id="<user_id>")

  oauth = client.link.generate_oauth_link(
    oauth_provider=OAuthProviders.<provider>,
    vital_link_token=token_response.link_token,
  )
  ```

  ```java Java
  import com.vital.api.Vital;
  import com.vital.api.core.Environment;
  import com.vital.api.resources.link.requests.LinkGenerateOauthLinkRequest;
  import com.vital.api.resources.link.requests.LinkTokenExchange;
  import com.vital.api.types.OAuthProviders;

  Vital vital = Vital.builder()
          .apiKey("YOUR_API_KEY")
          .environment(Environment.SANDBOX)
          .build();

  LinkTokenExchange request = LinkTokenExchange
          .builder()
          .userId("<user_id>")
          .build();

  var token_response = vital.link().token(request);

  LinkGenerateOauthLinkRequest link_request = LinkGenerateOauthLinkRequest
          .builder()
          .vitalLinkToken(token_response.getLinkToken())
          .build();

  var oauth = vital.link().generateOauthLink(OAuthProviders.OURA, link_request);
  ```

  ```go Go
  import (
    "context"

    vital "github.com/tryVital/vital-go"
    vitalclient "github.com/tryVital/vital-go/client"
    "github.com/tryVital/vital-go/option"
  )

  client := vitalclient.NewClient(
    option.WithApiKey("<YOUR_API_KEY>"),
    option.WithBaseURL(vital.Environments.Sandbox),
  )
  provider := vital.ProvidersOura
  request := &vital.LinkTokenExchange{
    UserId:   "<user_id>",
    Provider: &provider,
  }

  response, err := client.Link.Token(context.TODO(), request)

  if err != nil {
    return err
  }

  generateLinkRequest := &vital.LinkGenerateOauthLinkRequest{
    VitalLinkToken: response.LinkToken,
  }

  oauth, err := client.Link.GenerateOauthLink(context.TODO(), vital.OAuthProvidersOura, generateLinkRequest)

  if err != nil {
    return err
  }
  fmt.Printf("Received data %s\n", oauth)
  ```
</CodeGroup>

### Connact an Email/Password provider

<CodeGroup>
  ```javascript Node
  import { VitalClient, VitalEnvironment } from '@tryvital/vital-node';
  import { IndividualProviderData, PasswordProviders } from '@tryvital/vital-node/api';

  const request: IndividualProviderData = {
      username: '<username>',
      password: '<password>',
  }
  const data = await client.link.connectPasswordProvider(PasswordProviders.<provider>, request)
  ```

  ```python Python
  from vital.client import Vital
  from vital.environment import VitalEnvironment
  from vital.types.password_providers import PasswordProviders

  client = Vital(
    api_key="YOUR_API_KEY",
    environment=VitalEnvironment.SANDBOX
  )

  data = client.link.connect_password_provider(
    PasswordProviders.<provider>,
    username="<username>",
    password="<password>"
  )
  ```

  ```java Java
  import com.vital.api.Vital;
  import com.vital.api.core.Environment;
  import com.vital.api.resources.link.requests.IndividualProviderData;
  import com.vital.api.types.PasswordProviders;

  Vital vital = Vital.builder()
          .apiKey("YOUR_API_KEY")
          .environment(Environment.SANDBOX)
          .build();

  IndividualProviderData request = IndividualProviderData
          .builder()
          .username("<username>")
          .password("<password>")
          .build();

  var data = vital.link().connectPasswordProvider(PasswordProviders.<provider>, request);
  ```

  ```go Go
  import (
    "context"

    vital "github.com/tryVital/vital-go"
    vitalclient "github.com/tryVital/vital-go/client"
    "github.com/tryVital/vital-go/option"
  )

  client := vitalclient.NewClient(
    option.WithApiKey("<YOUR_API_KEY>"),
    option.WithBaseURL(vital.Environments.Sandbox),
  )

  request := &vital.IndividualProviderData{
    Username: "<username>",
    Password: "<password>",
  }

  response, err := client.Link.ConnectPasswordProvider(
    context.TODO(),
    vital.PasswordProviders<provider>,
    request
  )
  if err != nil {
    return err
  }
  fmt.Printf("Received data %s\n", response)
  ```
</CodeGroup>

### Bringing this all together

Below is an example of how you can bring all of this together to build your own custom widget. This example is in React Native, but the same principles apply to any language.

```javascript React Native
import React, {useEffect, useState} from 'react';
import {
  SafeAreaView,
  StatusBar,
  Linking,
  View,
  useColorScheme,
  Platform,
} from 'react-native';
import {VitalHealth, VitalResource} from '@tryvital/vital-health-react-native';

const handleOAuth = async (userId: string, item: Provider) => {
  const linkToken = await Client.Link.getLinkToken(
    userId,
    `${AppConfig.slug}://link`,
  );
  const link = await Client.Providers.getOauthUrl(item.slug, linkToken.link_token);

  Linking.openURL(link.oauth_url);
};

const ListItem = ({
  userId,
  item,
  navigation,
}: {
  userId: string;
  item: Provider;
  navigation: any;
}) => {
  const {colors} = useTheme();
  const isDarkMode = useColorScheme() === 'dark';
  const [isLoading, setLoading] = useState(false);

  const handleNativeHealthKit = async () => {
    const providerSlug =
      Platform.OS == 'ios'
        ? ManualProviderSlug.AppleHealthKit
        : ManualProviderSlug.HealthConnect;

    setLoading(true);

    const isHealthSDKAvailable = await VitalHealth.isAvailable();
    if (!isHealthSDKAvailable) {
      console.warn('Health Connect is not available on this device.');
      navigation.navigate('ConnectionCallback', {
        state: 'failed',
        provider: providerSlug,
      });
      return;
    }

    try {
      await VitalHealth.configure({
        logsEnabled: true,
        numberOfDaysToBackFill: 30,
        androidConfig: {syncOnAppStart: true},
        iOSConfig: {
          dataPushMode: 'automatic',
          backgroundDeliveryEnabled: true,
        },
      });
    } catch (e) {
      setLoading(false);
      console.warn(`Failed to configure ${providerSlug}`, e);
      navigation.navigate('ConnectionCallback', {
        state: 'failed',
        provider: providerSlug,
      });
    }
    await VitalHealth.setUserId(userId);
    try {
      await VitalHealth.askForResources([
        VitalResource.Steps,
        VitalResource.Activity,
        VitalResource.HeartRate,
        VitalResource.Sleep,
        VitalResource.Workout,
        VitalResource.BloodPressure,
        VitalResource.Glucose,
        VitalResource.Body,
        VitalResource.Profile,
        VitalResource.ActiveEnergyBurned,
        VitalResource.BasalEnergyBurned,
      ]);
      await VitalCore.createConnectedSourceIfNotExist(providerSlug);
      setLoading(false);
      navigation.navigate('ConnectionCallback', {
        state: 'success',
        provider: providerSlug,
      });
    } catch (e) {
      setLoading(false);
      navigation.navigate('ConnectionCallback', {
        state: 'failed',
        provider: providerSlug,
      });
    }
  };

  const onPress = async () => {
    if (item.auth_type === 'oauth') {
      await handleOAuth(userId, item);
    } else if (
      item.slug === 'apple_health_kit' ||
      item.slug === 'health_connect'
    ) {
      await handleNativeHealthKit();
    }
  };

  return (
    <Pressable onPress={() => onPress()}>
      {({isHovered, isFocused, isPressed}) => {
        return (
        <HStack space={'md'} justifyContent="flex-start">
            <VStack>
            <Text color={colors.text} fontType="medium">
                {item.name}
            </Text>
            <Text
                fontType="regular"
                color={colors.secondary}
                size="xs"
                flexShrink={1}
                flexWrap="wrap">
                {item.description}
            </Text>
            </VStack>
        </HStack>
        );
      }}
    </Pressable>
  );
};

export const LinkDeviceScreen = ({navigation}) => {
  const isDarkMode = useColorScheme() === 'dark';
  const {colors} = useTheme();
  const styles = makeStyles(colors);
  const [providers, setProviders] = React.useState<Provider[]>([]);
  const [devices, setDevices] = React.useState<Provider[]>([]);
  const [loading, setLoading] = React.useState<boolean>(false);
  const [searchText, setSearchText] = React.useState('');
  const [error, setError] = React.useState<string | null>(null);

  const [userId, setUserId] = React.useState('');

  const handleSearch = (text: string) => {
    setSearchText(text);
    if (text === '' && text.length <= 2) {
      setDevices(providers);
    } else {
      const filtered = providers.filter(item =>
        item.name.toLowerCase().includes(text.toLowerCase()),
      );
      setDevices(filtered);
    }
  };
  useEffect(() => {
    const getDevices = async () => {
      setLoading(true);
      setError(null);
      const user_id = await getData('user_id');
      if (user_id) {
        const providers = await Client.Providers.getProviders();
        setLoading(false);
        setUserId(user_id);
        setProviders(providers);
      } else {
        setUserId('');
        setLoading(false);
        console.warn('Failed to get all supported providers');
        setError('Failed to get devices');
      }
    };
  }, [navigation]);

  return (
    <SafeAreaView style={styles.container}>
      <StatusBar
        barStyle={isDarkMode ? 'light-content' : 'dark-content'}
        backgroundColor={styles.container.backgroundColor}
      />
      <View
        style={{
          paddingVertical: 10,
          paddingHorizontal: 16,
          flex: 1,
          width: '100%',
        }}>
        <VStack pb={10}>
          <HStack
            justifyContent={'space-between'}
            py={'$3'}
            alignItems="center">
            <H1>Connect a Device</H1>
            <Button onPress={() => navigation.goBack()} variant="link">
              <Ionicons name="close-outline" size={25} color={colors.text} />
            </Button>
          </HStack>
          <Input
            variant="outline"
            size="lg"
            isDisabled={false}
            isInvalid={false}
            isReadOnly={false}>
            <InputField
              color={colors.text}
              fontFamily={AppConfig.fonts.regular}
              onChangeText={handleSearch}
              value={searchText}
              placeholder="Search"
            />
          </Input>
        </VStack>

        {!loading && error ? (
          <VStack>
            <Text fontType="light">Failed to get supported Providers</Text>
          </VStack>
        ) : (
          <FlatList
            data={devices}
            renderItem={({item}) => (
              <ListItem userId={userId} item={item} navigation={navigation} />
            )}
            keyExtractor={item => item.slug}
          />
        )}
      </View>
    </SafeAreaView>
  );
};

```


# Link Errors
Source: https://docs.junction.com/wearables/connecting-providers/errors


## Error delivery

### URL Query

Vital performs a 307 Temporary Redirect to the `redirect_url` specified in your Link Token in the following scenarios:

* All connections via [the Vital Link widget](/wearables/connecting-providers/introduction)
* [Connect OAuth Provider](/api-reference/link/link-oauth-provider) endpoint used by your [Custom Widget](/wearables/connecting-providers/custom_widget)

Error parameters would be appended to the `redirect_url` before the redirection. For example,
given a redirect\_url of `https://example.com/vital/callback`:

```
https://example.com/vital/callback
?state=error
&error_type=provider_credential_error
&error=Invalid%20username%20or%20password
```

### JSON Response

Vital responds 200 OK with a JSON response in the following scenarios:

* [Connect Password Provider](/api-reference/link/link-password-provider) endpoint used by your [Custom Widget](/wearables/connecting-providers/custom_widget)
* [Connect Email Provider](/api-reference/link/link-email-provider) endpoint used by your [Custom Widget](/wearables/connecting-providers/custom_widget)

Error parameters would be embedded into the JSON response. For example:

```json
{
  "state": "error",
  "error_type": "provider_credential_error",
  "error": "Invalid username or password"
}
```

## Error Parameters

<ResponseField name="state" type="const string">
  Constant: `error`
</ResponseField>

<ResponseField name="error_type" type="string">
  One of the [Link Error Types](#error-types).
</ResponseField>

<ResponseField name="error" type="string">
  A human-readable error explanation for troubleshooting purposes.
  Your application logic should not rely on this message.
</ResponseField>

## Error Types

<Note>
  This list is **non-exhaustive**. Your application logic must gracefully handle any unrecognized error type.
</Note>

| Error Type                    | Description                                                                                                                                                                                                                                                             |
| ----------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `invalid_token`               | The Link Token is invalid or malformed.                                                                                                                                                                                                                                 |
| `token_expired`               | The Link Token has expired.                                                                                                                                                                                                                                             |
| `token_consumed`              | A successful connection establishment had consumed this Link Token.                                                                                                                                                                                                     |
| `provider_credential_error`   | <ul><li>OAuth: An error occurred during the provider authentication flow.</li><li>Password & Email: The supplied user credential is invalid.</li></ul>                                                                                                                  |
| `provider_password_expired`   | The supplied password has expired due to the password rotation policy of the provider. The user must rotate their password directly with the provider before trying to connect again. <Info>Applicable only to the patient-based `abbott_libreview` integration.</Info> |
| `provider_api_error`          | An unexpected error occurred when Junction Link attempts to connect to the provider API.                                                                                                                                                                                |
| `unsupported_region`          | The region you specified is not supported. <Info>Applicable only the practice-based `freestyle_libre` integration.</Info>                                                                                                                                               |
| `duplicate_connection`        | The provider credential has an existing connection to a different user in your team. <Info>Applicable only if you have opted in to the `reject_duplicate_connection` team setting.</Info>                                                                               |
| `required_scopes_not_granted` | User did not grant **all** required scopes, so Vital cannot establish the connection.                                                                                                                                                                                   |
| `incorrect_mfa_code`          | The MFA code entered is incorrect.                                                                                                                                                                                                                                      |


# Introduction to Link
Source: https://docs.junction.com/wearables/connecting-providers/introduction


Vital Link enables your users to connect their accounts with [supported cloud-based providers](https://docs.tryvital.io/wearables/providers/introduction)
to Vital.

Vital Link is offered in two forms:

* [Vital Link Widget](/wearables/connecting-providers/link_flow) is a web flow hosted by Vital, providing a complete
  provider connection wizard UX that is ready to integrate.

* [Vital Link API](/wearables/connecting-providers/custom_widget) allows you to build your own Link Widget like user experience.

<Warning>
  Vital Link API covers **only** [cloud-based providers](/wearables/providers/introduction#cloud-based-providers).

  Your mobile app has to manage connections with SDK-based providers — such as Apple HealthKit and Android Health
  Connect — through the [Vital Mobile Health SDK](/wearables/sdks/vital-health), separately from Vital Link.
</Warning>

![link-gif](https://storage.googleapis.com/vital-assets/vitalLink.gif)


# Launching Link
Source: https://docs.junction.com/wearables/connecting-providers/launching_link


<Warning>
  Vital Link API covers **only** [cloud-based providers](/wearables/providers/introduction#cloud-based-providers).

  Your mobile app has to manage connections with SDK-based providers — such as Apple HealthKit and Android Health
  Connect — through the [Vital Mobile Health SDK](/wearables/sdks/vital-health), separately from Vital Link.
</Warning>

<Steps>
  <Step number="1" title="Your Backend">
    Create a Vital Link Token for a user using the [Create Link Token](/api-reference/link/generate-link-token) endpoint.

    <Note>
      Vital Link Token expires 60 minutes after its creation.
    </Note>

    <br />

    <CodeGroup>
      ```javascript Node
      import { VitalClient, VitalEnvironment } from '@tryvital/vital-node';
      import { LinkTokenExchange } from '@tryvital/vital-node/api';


      const client = new VitalClient({
          apiKey: '<my_api_key>',
          environment: VitalEnvironment.Sandbox,
      });

      const request: LinkTokenExchange = {
          userId: "<user_id>",
          provider: "oura",
      }
      const data = await client.link.token(request)
      ```

      ```python Python
      from vital.client import Vital
      from vital.environment import VitalEnvironment
      from vital.types.providers import Providers

      client = Vital(
        api_key="YOUR_API_KEY",
        environment=VitalEnvironment.SANDBOX
      )

      data = client.link.token(user_id="<user_id>", provider=Providers.OURA)
      ```

      ```java Java
      import com.vital.api.Vital;
      import com.vital.api.core.Environment;
      import com.vital.api.resources.link.requests.LinkTokenExchange;
      import com.vital.api.types.Providers;

      Vital vital = Vital.builder()
           .apiKey("YOUR_API_KEY")
           .environment(Environment.SANDBOX)
           .build();

      LinkTokenExchange request = LinkTokenExchange
           .builder()
           .userId("<user_id>")
           .provider(Providers.OURA)
           .build();

      var data = vital.link().token(request);
      ```

      ```go Go
      import (
        "context"

        vital "github.com/tryVital/vital-go"
        vitalclient "github.com/tryVital/vital-go/client"
        "github.com/tryVital/vital-go/option"
      )

      client := vitalclient.NewClient(
        option.WithApiKey("<YOUR_API_KEY>"),
        option.WithBaseURL(vital.Environments.Sandbox),
      )

      provider := vital.ProvidersOura
      request := &vital.LinkTokenExchange{
           UserId:   "<user_id>",
           Provider: &provider,
      }

      response, err := client.Link.Token(context.TODO(), request)
      if err != nil {
        return err
      }
      fmt.Printf("Received data %s\n", response)
      ```

      ```bash cURL
      curl --request POST \
           --url {{BASE_URL}}/v2/link/token \
           --header 'Accept: application/json' \
           --header 'Content-Type: application/json'
           --header 'x-vital-api-key: <API-KEY>'
      ```
    </CodeGroup>

    <br />
  </Step>

  <Step number="2" title="Your Frontend">
    Use the Link Token to [launch the Link Widget](/wearables/vital-link/link_flow) on your frontend.

    <img src="https://mintcdn.com/vital/img/link_specific.png?maxW=2210&auto=format&n=nR1fvAlwouZ87zVb&q=85&s=4e10f38bffc71e2e54dc685bf6decb69" width={"60%"} width="2210" height="2232" data-path="img/link_specific.png" srcset="https://mintcdn.com/vital/img/link_specific.png?w=280&maxW=2210&auto=format&n=nR1fvAlwouZ87zVb&q=85&s=b6397cdedeb46ecacf54838c8a040cb6 280w, https://mintcdn.com/vital/img/link_specific.png?w=560&maxW=2210&auto=format&n=nR1fvAlwouZ87zVb&q=85&s=d01ad93552f3a0ed32dec2059399e434 560w, https://mintcdn.com/vital/img/link_specific.png?w=840&maxW=2210&auto=format&n=nR1fvAlwouZ87zVb&q=85&s=23eefdd7138bf5edfe4d2c0a14711695 840w, https://mintcdn.com/vital/img/link_specific.png?w=1100&maxW=2210&auto=format&n=nR1fvAlwouZ87zVb&q=85&s=da9047881a8c3be9b31b588906183ac5 1100w, https://mintcdn.com/vital/img/link_specific.png?w=1650&maxW=2210&auto=format&n=nR1fvAlwouZ87zVb&q=85&s=ca0deeb2d563a8cb73a00a97ba29ac8f 1650w, https://mintcdn.com/vital/img/link_specific.png?w=2500&maxW=2210&auto=format&n=nR1fvAlwouZ87zVb&q=85&s=f63d298515ddb1813edf87cae4aa79e1 2500w" data-optimize="true" data-opv="2" />

    {" "}

    <AccordionGroup>
      <Accordion title="Option 1: Opening the Link Widget by URL" icon="link" iconType="sharp-solid" defaultOpen>
        You can launch the Vital Link Widget using the Link Web URL (`link_web_url`) as provided by the
        [Generate a Link Token endpoint](/api-reference/link/generate-link-token):

        * If you have created the Link Token for a specific OAuth provider, Vital Link will dispatch
          the user automatically to the provider's sign-in page.

        * Otherwise, your user will be presented with a list of providers to connect to. You can
          customize the list via the `filter_on_providers` parameter when creating the Link Token.

        When the Link flow completes, the flow will redirect to the `redirect_url` you specified earlier
        when creating the Link Token. We will also append query parameters to the redirection target
        based on the Link flow outcome:

        | Flow state | Query parameters                                                                   |
        | ---------- | ---------------------------------------------------------------------------------- |
        | Success    | `state=success`                                                                    |
        | Error      | See [Link Errors](https://docs.tryvital.io/wearables/connecting-providers/errors). |
      </Accordion>

      <Accordion title="Option 2: Using the `useVitalLink` React hook (`@tryvital/vital-link`)" icon="react" iconType="sharp-solid">
        ```js Launching Vital-Link
        import 'react-app-polyfill/ie11';
        import * as React from 'react';
        import * as ReactDOM from 'react-dom';
        import { useCallback } from 'react';

        import { useVitalLink } from '@tryvital/vital-link';
        import { useState } from 'react';

        const API_URL = process.env.API_URL ? process.env.API_URL : "http://localhost:3001"

        const getTokenFromBackend = async (userKey: string, env: string) => {
          const resp = await fetch(<backend_url>);
          return await resp.json();
        };

        const App = props => {
          const userKey = '560596b9-924b-4af9-a670-cf21870fdac5';
          const [isLoading, setLoading] = useState(false);

          const onSuccess = useCallback(metadata => {
            // Device is now connected.
          }, []);

          const onExit = useCallback(metadata => {
            // User has quit the link flow.
          }, []);

          const onError = useCallback(metadata => {
            // Error encountered in connecting device.
          }, []);

          const config = {
            onSuccess,
            onExit,
            onError,
            env: "sandbox"
          };

          const { open, ready, error } = useVitalLink(config);

          const handleVitalOpen = async () => {
            setLoading(true);
            const token = await getTokenFromBackend(userKey, "sandbox");
            open(token);
            setLoading(false);
          };

          return (
            <button
              type="button"
              className="button"
              onClick={handleVitalOpen}
              disabled={isLoading || !ready}
            >
              Open Vital Link
            </button>
          );
        };

        ReactDOM.render(<App />, document.getElementById('root'));
        ```
      </Accordion>
    </AccordionGroup>
  </Step>
</Steps>


# Link Flow
Source: https://docs.junction.com/wearables/connecting-providers/link_flow


<Warning>
  Vital Link API covers **only** [cloud-based providers](/wearables/providers/introduction#cloud-based-providers).

  Your mobile app has to manage connections with SDK-based providers — such as Apple HealthKit and Android Health
  Connect — through the [Vital Mobile Health SDK](/wearables/sdks/vital-health), separately from Vital Link.
</Warning>

The Vital Link flow starts when a user wants to connect a wearable device with Vital. An overview of the process can be found below.

<Steps>
  <Step title="Pre-requisites">
    Make sure that:

    1. You have your Vital API Key [dashboard](https://app.tryvital.io) ready to use.

    2. You have created a Vital User that corresponds to a user in your domain. [See](/home/quickstart#3-creating-your-first-user) for an example.
  </Step>

  <Step title="Generate a Link Token">
    Call the [Generate a Link Token endpoint](/api-reference/link/generate-link-token) with the target User ID using your Vital API Key.
  </Step>

  <Step title="Initiate the Link Flow">
    The API response provides a short-lived Link Token (`link_token`), as well as a Web URL (`link_web_url`).

    You can use the Web URL to launch the Vital Link Widget directly. Alternatively, you can use the Link Token
    in concert with the Vital Link API to [build your custom Link Widget experience](/wearables/connecting-providers/custom_widget).
  </Step>
</Steps>

<img src="https://storage.googleapis.com/vital-assets/link-flow-explainer.png" width="50%" />


# Abbott LibreView
Source: https://docs.junction.com/wearables/guides/abbott-libreview

For Abbott CGMs, e.g. Freestyle Libre.

## Overview

Vital supports two ways to connect to LibreView for Abbott CGMs:

| Provider Slug      | Remarks                                                                        |
| ------------------ | ------------------------------------------------------------------------------ |
| `abbott_libreview` | Connect via LibreView patient account in any region.                           |
| `freestyle_libre`  | Connect via regional LibreView practices (Vital-managed, or custom practices). |

### `freestyle_libre` for practice-based connections

With the `freestyle_libre` integration, users have to share/connect their LibreView patient account
with either Vital's LibreView practice, or a custom practice of yours.

Vital accesses the patient CGM data as a member of the LibreView practice.

### `abbott_libreview` for patient-based connections

With the `abbott_libreview` integration, users can connect their Abbott CGM devices simply by signing in
with their LibreView patient account. Vital accesses the patient CGM data as their personal account.

* You would not need to maintain any LibreView practices.
* You would not need to instruct your users to connect their account to a LibreView practice, before they can attempt to connect via Vital Link.

#### ⚠️ Prepare for regular disconnection with `abbott_libreview`

Patient-based connections through `abbott_libreview` may **disconnect** at least once a year due to password rotation enforcement.

You can observe the error state through:

1. the [Provider Connection Error](/event-catalog/provider.connection.error) event; and
2. the [Get User Connections endpoint](/api-reference/user/get-users-connected-providers).

The following error types are relevant in this password rotation situation:

| Error Type                  | Remarks                                                                                                                                                    |
| --------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `provider_credential_error` | The patient has changed their password. They need to re-connect with the new password via Junction Link.                                                   |
| `provider_password_expired` | Login is blocked due to password expiration. Once the patient has changed their password, they need to re-connect with the new password via Junction Link. |

When you detect a disconnection, guide your user to:

1. Sign into the LibreLink app or the LibreView web portal.
2. Update their account passwords.
3. Use the Vital Link Widget or your custom widget to re-establish the `abbott_libreview` connection.

## LibreView data use floating time basis

All LibreView (Freestyle Libre) data are in **floating time basis**.

Please go through the [Timestamps and Time Zones](/wearables/providers/timestamps-and-time-zones) guide to understand the
implications, as well as how to properly handle floating time data.

## Libre Notes Timeseries

LibreView, in addition to standard CGM data, provides insights manually added by the user.
This data is available in the following types:

* `note`: A general note added by the user, often providing context for other entries.
* `carbohydrates`: Grams of carbohydrates logged by the user.
* `insulin_injection`: Units of insulin injected by the user, categorized as either `rapid_acting` or `long_acting`.

<Info>
  Timestamps for these events have hourly granularity and are marked with the beginning of the hour.
</Info>

## Connecting a LibreView patient account (`abbott_libreview`)

### Vital Link Widget

Abbott LibreView is automatically available as an option in the [Vital Link Widget](/wearables/connecting-providers/launching_link).

### Vital Link API (custom widget)

If you intend to build a [custom widget on top of the Vital Link API](/wearables/connecting-providers/custom_widget), Abbott LibreView is
exposed as a **password provider**:

<Steps>
  <Step number="1" title="Generate a Link Token">
    Start the linking process by [generating a short-lived Link Token](/api-reference/link/generate-link-token).
  </Step>

  <Step number="2" title="Submit username and password">
    Submit the username and password of the LibreView patient account to the [Link Password Provider](/api-reference/link/link-password-provider) endpoint.

    <Note>
      You need not specify any region in your request. Vital will match the correct LibreView region transparently.
    </Note>
  </Step>

  <Step number="3" title="Handle the multi-factor authentication request">
    The [Link Password Provider](/api-reference/link/link-password-provider) endpoint responds with `state: "pending_provider_mfa"`,
    alongside the MFA method being used, as well as a MFA hint.

    This means the user must complete multi-factor authentication before Vital can establish the connection. You should prompt the user
    to input the verification code they received out-of-band.
  </Step>

  <Step number="4" title="Submit the MFA Code">
    Submit the MFA code to the [Complete Password Provider MFA](/api-reference/link/complete-password-provider-mfa) endpoint.

    <Note>You must use the same Link Token you generated in Step 1.</Note>
  </Step>

  <Step number="5" title="Linking completed">
    The linking process is completed. Historical pulls are scheduled to start as soon as possible.
  </Step>
</Steps>

## Setting up practice-based connections (`freestyle_libre`)

### Adding users to a Practice

When integrating with Vital, you have two options: use Vital's practice, or yours. We call the latter a custom practice. Depending on the approach, you need to instruct your user's to connect their Libre account to a practice.

This allows Vital to start pulling data from their account. This is done through the Libre app:

<img src="https://mintcdn.com/vital/img/connect_libreview.png?maxW=375&auto=format&n=nR1fvAlwouZ87zVb&q=85&s=cee92fed21bfa6eacdd1919bfdde6faa" className="w-2/5 block mx-auto" width="375" height="667" data-path="img/connect_libreview.png" srcset="https://mintcdn.com/vital/img/connect_libreview.png?w=280&maxW=375&auto=format&n=nR1fvAlwouZ87zVb&q=85&s=a40ded210912f5d9c0d405838e4622fa 280w, https://mintcdn.com/vital/img/connect_libreview.png?w=560&maxW=375&auto=format&n=nR1fvAlwouZ87zVb&q=85&s=a97d73b6221b30041213f5170b65c7c3 560w, https://mintcdn.com/vital/img/connect_libreview.png?w=840&maxW=375&auto=format&n=nR1fvAlwouZ87zVb&q=85&s=895d01717c02cdc4afa323fdd3d86e77 840w, https://mintcdn.com/vital/img/connect_libreview.png?w=1100&maxW=375&auto=format&n=nR1fvAlwouZ87zVb&q=85&s=02b97b248531de5ff98907b06f76e3c9 1100w, https://mintcdn.com/vital/img/connect_libreview.png?w=1650&maxW=375&auto=format&n=nR1fvAlwouZ87zVb&q=85&s=d94e4d2b49839050766e37b337c2a700 1650w, https://mintcdn.com/vital/img/connect_libreview.png?w=2500&maxW=375&auto=format&n=nR1fvAlwouZ87zVb&q=85&s=a54306ed52088935f71796564ed0c9b0 2500w" data-optimize="true" data-opv="2" />

### Supported Regions

#### 🇺🇸 Vital US region

| Region Code | Region        |
| ----------- | ------------- |
| `ca`        | Canada        |
| `hk`        | Hong Kong     |
| `in`        | India         |
| `kr`        | South Korea   |
| `ph`        | Philippines   |
| `sg`        | Singapore     |
| `tw`        | Taiwan        |
| `us`\*      | United States |

*(\*) Default if region is unspecified.*

#### 🇪🇺 Vital EU region

| Region Code | Region         |
| ----------- | -------------- |
| `ar`        | Argentina      |
| `at`        | Austria        |
| `au`        | Australia      |
| `be`        | Belgium        |
| `bh`        | Bahrain        |
| `br`        | Brazil         |
| `ch`        | Switzerland    |
| `cl`        | Chile          |
| `co`        | Colombia       |
| `cz`        | Czechia        |
| `de`        | Germany        |
| `dk`        | Denmark        |
| `eg`        | Egypt          |
| `es`        | Spain          |
| `fi`        | Finland        |
| `fr`        | France         |
| `gb`\*      | United Kingdom |
| `gr`        | Greece         |
| `hk`        | Hong Kong      |
| `hr`        | Croatia        |
| `ie`        | Ireland        |
| `il`        | Israel         |
| `in`        | India          |
| `it`        | Italy          |
| `jo`        | Jordan         |
| `kr`        | South Korea    |
| `kw`        | Kuwait         |
| `lb`        | Lebanon        |
| `lu`        | Luxembourg     |
| `mx`        | Mexico         |
| `nl`        | Netherlands    |
| `no`        | Norway         |
| `nz`        | New Zealand    |
| `om`        | Oman           |
| `ph`        | Philippines    |
| `pl`        | Poland         |
| `pt`        | Portugal       |
| `qa`        | Qatar          |
| `sa`        | Saudi Arabia   |
| `se`        | Sweden         |
| `sg`        | Singapore      |
| `si`        | Slovenia       |
| `sk`        | Slovakia       |
| `tr`        | Türkiye        |
| `tw`        | Taiwan         |
| `za`        | South Africa   |

*(\*) Default if region is unspecified.*

### Bring Your Own Practice

<Info>
  `freestyle_libre` custom practice connections is available for [the Scale plan](https://tryvital.io/pricing).
</Info>

<Steps>
  <Step title="Obtain the Vital practice email address">
    Get in touch with [Vital Support](/home/getting-support) to request the region-specific Vital practice email address.
  </Step>

  <Step title="Invite the Vital practice">
    Invite the Vital practice email address to join your LibreView practice as a **Care Team Admin**.
  </Step>

  <Step title="Confirm with Vital support">
    Inform Vital support of the invitation, and wait for the support acknowledgement of successful practice connection.
  </Step>
</Steps>

Once the connection is established, Vital Link would recognize all patient emails having connected to your LibreView practice.
These patients do not need to connect separately to the [Vital practices](#using-vital-practices).

### Using Vital Practices

<Info>
  You can use a Vital practice to test the integration with Freestyle Libre.
  This modality is available to all subscriptions.
</Info>

Vital has two LibreView Practices that are available in all supported regions:

| Environment | Practice Name    |
| ----------- | ---------------- |
| Sandbox     | tryVital-sandbox |
| Production  | tryVital         |

You need to ask your user to add one of the above practices in their Libre App. Once that's done, data will start flowing.

### Vital Link Widget

To connect your user to Vital via the Link Widget you can follow the guide [here](/wearables/connecting-providers/launching_link).

<img src="https://mintcdn.com/vital/img/libre_connect.png?maxW=790&auto=format&n=nR1fvAlwouZ87zVb&q=85&s=6d8623983b8ceda091af0aff8c0e3239" className="w-2/5 block mx-auto" width="790" height="1432" data-path="img/libre_connect.png" srcset="https://mintcdn.com/vital/img/libre_connect.png?w=280&maxW=790&auto=format&n=nR1fvAlwouZ87zVb&q=85&s=a7dc824ec7bbb2ebf02e4de0cd265138 280w, https://mintcdn.com/vital/img/libre_connect.png?w=560&maxW=790&auto=format&n=nR1fvAlwouZ87zVb&q=85&s=ca3523248c034897e514dcba7f3bfe3f 560w, https://mintcdn.com/vital/img/libre_connect.png?w=840&maxW=790&auto=format&n=nR1fvAlwouZ87zVb&q=85&s=5fba32981fbcae103a5a23a67557c438 840w, https://mintcdn.com/vital/img/libre_connect.png?w=1100&maxW=790&auto=format&n=nR1fvAlwouZ87zVb&q=85&s=0cd06b0d37dbd71b55d23cdca6bc3305 1100w, https://mintcdn.com/vital/img/libre_connect.png?w=1650&maxW=790&auto=format&n=nR1fvAlwouZ87zVb&q=85&s=b8c9f96495dd6b1916a4c91878bdfbc1 1650w, https://mintcdn.com/vital/img/libre_connect.png?w=2500&maxW=790&auto=format&n=nR1fvAlwouZ87zVb&q=85&s=65a038286d8e891e9d79ba1557f1d1b2 2500w" data-optimize="true" data-opv="2" />

### Vital Link API (custom widget)

1. To connect to Freestyle Libre, you must create a Vital Link token.

<CodeGroup>
  ```python Python
  token_response = client.link.token(user_id="<user_id>")
  ```

  ```javascript Node
  const request: LinkTokenExchange = {
      userId: "<user_id>
  }
  const data = await client.link.token(request)
  ```

  ```java Java
  LinkTokenExchange request = LinkTokenExchange
       .builder()
       .userId("<user_id>")
       .build();

  var tokenResponse = vital.link().token(request);
  ```

  ```go Go
  request := &vital.LinkTokenExchange{
       UserId:   "<user_id>
  }

  tokenResponse, err := client.Link.Token(context.TODO(), request)
  if err != nil {
    return err
  }
  fmt.Printf("Received data %s\n response)
  ```
</CodeGroup>

2. Libre is an [email](/api-reference/link/link-email-provider) provider.
   This means that when connecting a user we have to use
   the connect email provider method, passing in the email of the user's Libre account and region in short form.

<CodeGroup>
  ```python Python
  linkResponse = client.link.connect_email_auth_provider(
    provider="freestyle_libre
    email="<email>
    vital_link_token=token_response.link_token
  )
  ```

  ```javascript Node
  const linkRequest: EmailProviderAuthLink = {
      vitalLinkToken: tokenResponse.linkToken,
      email: "<email>"
  }

  const connectEmailResponse = await client.link.connectEmailAuthProvider(
      "freestyle_libre
      linkRequest
  )
  ```

  ```java Java
  EmailProviderAuthLink request = EmailProviderAuthLink
          .builder()
          .vitalLinkToken(tokenResponse.getLinkToken())
          .email("<email>")
          .build();

  var data = vital.link().connectEmailAuthProvider("<provider request);
  ```

  ```go Go
  emailAuthRequest := &vital.EmailProviderAuthLink{
    VitalLinkToken: tokenResponse.LinkToken,
    Email:          "<email>
  }

  emailAuth, err := client.Link.ConnectEmailAuthProvider(context.TODO(), "freestyle_libre emailAuthRequest)
  if err != nil {
    return err
  }
  fmt.Printf("Received data %s\n emailAuth)
  ```
</CodeGroup>

Once this is complete we will start syncing data from their [Libre account](/api-details/data_flow).


# Android Health Connect
Source: https://docs.junction.com/wearables/guides/android-health-connect


Android Health Connect is an SDK-based provider. Your Android consumer app would embed the Vital Mobile SDKs on a supported
stack. Data are then pulled from the Health Connect data store on the user's Android device.

Refer to the [Mobile SDK Installation](/wearables/sdks/installation) and [Vital Health SDK](/wearables/sdks/vital-health) guides for SDK installation
instructions and general API usage. This guide contains information on the the behaviour and required configuration
specific to the Android Health Connect integration.

<Card title="Mobile SDK Installation" icon="helmet-safety" href="/wearables/sdks/installation" horizontal>
  Learn about the minimum runtime and build-time requirements of Vital Mobile SDKs, and how to add them into
  your project through your package dependency manager.
</Card>

<Card title="Vital Health SDK" icon="heart" iconType="solid" href="/wearables/sdks/vital-health" horizontal>
  Learn about the initial setup required by Vital Health SDK, and the API exposed by Vital Health SDK
  for managing and inspecting health data permissions and automatic data sync.
</Card>

## Getting Started

To enable this integration, you would need to integrate [Vital Core SDK](/wearables/sdks/vital-core) and
[Vital Health SDK](/wearables/sdks/vital-core) into your Native iOS, React Native or Flutter mobile app.

<Steps>
  <Step title="Add Vital SDKs as dependencies">
    Review the [installation requirements and package installation instructions](/wearables/sdks/installation).
  </Step>

  <Step title="Integrate with Vital Mobile SDK Authentication">
    Follow the [SDK Authentication](/wearables/sdks/authentication) guidance to integrate your app with the authentication
    mechanism of Vital Core SDK.
  </Step>

  <Step title="Configure Health SDK and ask user for read permissions">
    Follow the [Vital Health SDK](/wearables/sdks/vital-health) starting guidance to
    [configure the Health SDK](/wearables/sdks/vital-health#sdk-configuration) and to
    [ask for health data read permissions](/wearables/sdks/vital-health#ask-user-for-health-data-permissions) from your user.

    <Note>
      Health data sync is activated only on `VitalResource`s which you have asked permissions from your user for. If you
      did not ask for permissions, data sync would not occur.
    </Note>
  </Step>

  <Step title="[Optional] Customize the Foreground Service notification">
    Follow the [Running as Foreground Service](#running-as-foreground-service) guidance below to
    customize the Foreground Service notification which may be shown by the Android OS during
    any prolonged health data sync attempts.
  </Step>

  <Step title="[Optional] Configure Background Sync">
    Follow the [Background Sync](#background-sync) guidance below to
    configure regular background sync.
  </Step>
</Steps>

## Review the Google Play Store policy

Apps using Android Health Connect **require prior Google approval** before they can be released on Google Play Store.

Check out the official [Google Play Store policy on Android Health Connect](https://support.google.com/googleplay/android-developer/answer/12991134?hl=en-GB).
Note that the application form is located under the "How do I access data through Health Connect?" section.

## Configure your AndroidManifest.xml

### Health Connect privacy dialogue

<Warning>Missing manifest declarations may result in Health Connect ignoring your app.</Warning>

Check [the Health Connect Getting Started guide](https://developer.android.com/health-and-fitness/guides/health-connect/develop/get-started#show-privacy-policy) for the official requirements.

Here is a minimum declaration example:

```xml
<manifest ...>
    <application ...>
        <!-- BEGIN: Mandatory for Health Connect permission flow (Android 13 or below) -->
        <!-- Must either be your MainActivity, or a separate Activity; cannot be an activity-alias. -->
        <activity android:name=".MainActivity" ...>
            <intent-filter>
                <action android:name="androidx.health.ACTION_SHOW_PERMISSIONS_RATIONALE" />
            </intent-filter>
        </activity>
        <!-- END -->

        <!-- BEGIN: Mandatory for Health Connect permission flow (Android 14 or above) -->
        <!-- Can be an activity or an activity-alias. -->
        <activity-alias
            android:name="ViewPermissionUsageActivity"
            android:exported="true"
            android:targetActivity=".MainActivity"
            android:permission="android.permission.START_VIEW_PERMISSION_USAGE">
            <intent-filter>
                <action android:name="android.intent.action.VIEW_PERMISSION_USAGE" />
                <category android:name="android.intent.category.HEALTH_PERMISSIONS" />
            </intent-filter>
        </activity-alias>
        <!-- END -->
    </application>

    <queries>
        <package android:name="com.google.android.apps.healthdata" />
    </queries>
</manifest>
```

### Health Connect permissions

Your app manifest (`AndroidManifest.xml`) must declare all the read or write permissions for all the data types you intend to sync.

For example, if you intend to sync Blood Pressure records and Blood Glucose reocrds, your app manifest must contain the following
`<uses-permission>` declarations:

```xml
<?xml version="1.0" encoding="utf-8"?>
<manifest xmlns:android="http://schemas.android.com/apk/res/android"
    xmlns:tools="http://schemas.android.com/tools">
    <!-- ... other declarations -->

    <!-- BEGIN: Health Connect permissions -->
    <uses-permission android:name="android.permission.health.READ_BLOOD_GLUCOSE" />
    <uses-permission android:name="android.permission.health.READ_BLOOD_PRESSURE" />
    <!-- END: Health Connect permissions -->
</manifest>
```

| SDK `VitalResource` type | Read permissions required                                                                                                                                                                                                                                                                                                                                                                                                   |
| ------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `Profile`                | `android.permission.health.READ_HEIGHT`                                                                                                                                                                                                                                                                                                                                                                                     |
| `Body`                   | `android.permission.health.READ_BODY_FAT`<br />`android.permission.health.READ_WEIGHT`                                                                                                                                                                                                                                                                                                                                      |
| `Workout`                | `android.permission.health.READ_EXERCISE`<br />`android.permission.health.READ_HEART_RATE`<br />`android.permission.health.READ_RESPIRATORY_RATE`<br />`android.permission.health.READ_DISTANCE`<br />`android.permission.health.READ_ACTIVE_CALORIES_BURNED`<br />`android.permission.health.READ_ELEVATION_GAINED`<br />`android.permission.health.READ_POWER`<br />`android.permission.health.READ_SPEED`                |
| `Activity`               | `android.permission.health.READ_ACTIVE_CALORIES_BURNED`<br />`android.permission.health.READ_BASAL_METABOLIC_RATE`<br />`android.permission.health.READ_TOTAL_CALORIES_BURNED`<br />`android.permission.health.READ_DISTANCE`<br />`android.permission.health.READ_STEPS`<br />`android.permission.health.READ_FLOORS_CLIMBED`<br />`android.permission.health.READ_DISTANCE`<br />`android.permission.health.READ_VO2_MAX` |
| `Sleep`                  | `android.permission.health.READ_SLEEP`<br />`android.permission.health.READ_HEART_RATE`<br />`android.permission.health.READ_RESPIRATORY_RATE`<br />`android.permission.health.READ_HEART_RATE_VARIABILITY`<br />`android.permission.health.READ_OXYGEN_SATURATION`<br />`android.permission.health.READ_RESTING_HEART_RATE`                                                                                                |
| `Glucose`                | `android.permission.health.READ_BLOOD_GLUCOSE`                                                                                                                                                                                                                                                                                                                                                                              |
| `BloodPressure`          | `android.permission.health.READ_BLOOD_PRESSURE`                                                                                                                                                                                                                                                                                                                                                                             |
| `HeartRate`              | `android.permission.health.READ_HEART_RATE`                                                                                                                                                                                                                                                                                                                                                                                 |
| `Steps`                  | `android.permission.health.READ_STEPS`                                                                                                                                                                                                                                                                                                                                                                                      |
| `ActiveEnergyBurned`     | `android.permission.health.READ_ACTIVE_CALORIES_BURNED`                                                                                                                                                                                                                                                                                                                                                                     |
| `BasalEnergyBurned`      | `android.permission.health.READ_ACTIVE_CALORIES_BURNED`<br />`android.permission.health.READ_BASAL_METABOLIC_RATE`<br />`android.permission.health.READ_TOTAL_CALORIES_BURNED`                                                                                                                                                                                                                                              |
| `Water`                  | `android.permission.health.READ_HYDRATION`                                                                                                                                                                                                                                                                                                                                                                                  |

### Foreground Service permissions

Vital Health SDK runs all its data sync workers inside a short-service Foreground Services.

At build time, Vital Health SDK injects all the required `shortService` Foreground Services declarations
into your AndroidManifest.xml. You need not modify your app's Manifest to enable this.

<Info>
  Vital Health SDK can run work inside the [AndroidX WorkManager](https://developer.android.com/develop/background-work/background-tasks/persistent/how-to/long-running#declare-foreground-service-types-manifest)
  foregorund service, as well as our own `SyncOnExactAlarmService`. The merged AndroidManifest.xml of your app
  would include both of them.
</Info>

## Prepare your app architecture

<Warning>Incompliance to the guidelines below may result in Health Connect permission flow failing to launch on specific Android OS versions.</Warning>

<Tabs>
  <Tab title="Native Android">
    When requesting permission using the `ActivityResultContract` created by Vital Health `createPermissionRequestContract()`, you must launch
    the contract using AndroidX Activity Result API.

    Attempts to launch the contract manually via the legacy `Activity.startActivityForResult` API would result in an `android.content.ActivityNotFoundException`
    exception on Android 14 and later.
  </Tab>

  <Tab title="React Native">
    The `MainActivity` of your Android host app project must be augmented with either of the two options below:

    1. Subclassing `VitalHealthReactActivity` provided by the Vital Health SDK `com.vitalhealthreactnative` package, instead of the default `ReactActivity`.

    2. Overriding `onRequestPermissionsResult(...)` so as to manually propagate permission request results to the Vital Health SDK.

    ```kotlin
    // MainActivity in your host app project
    open class MainActivity: ReactActivity() {
      override fun onRequestPermissionsResult(
        requestCode: Int,
        permissions: Array<out String>,
        grantResults: IntArray
      ) {
        super.onRequestPermissionsResult(requestCode, permissions, grantResults)

        // Propagate permission flow results to Vital Health SDK.
        VitalHealthReactNativeModule.onRequestPermissionsResult(
          this.reactInstanceManager,
          requestCode,
          permissions,
          grantResults
        )
      }
    }
    ```

    The argumentation above is a workaround to React Native internals AndroidX-incompatible handling of permission request result callbacks,
    which breaks the AndroidX Activity Result API required by Android Health Connect.
  </Tab>

  <Tab title="Flutter">
    The `MainActivity` of your Android host app project must subclass `FlutterFragmentActivity` instead of `FlutterActivity`.

    This is because `FlutterFragmentActivity` is AndroidX compatible and therefore supports the Activity Result API as required by
    Android Health Connect, whilst `FlutterActivity` is not.
  </Tab>
</Tabs>

## Synchronization

### Sync On App Launch

When your app resumes from background (i.e., having no Activity), Vital Health SDK triggers a data sync on all the resources
to which the user has granted read permission.

The SDK imposes a **2-minute** throttle on automatic data sync. This is to prevent rapid app switching from causing an
excessive amount of data sync work being scheduled.

<Info>
  Vital Health SDK relies on the [AndroidX ProcessLifecycleOwner](https://developer.android.com/reference/androidx/lifecycle/ProcessLifecycleOwner)
  to get notified of your app's resumption.
</Info>

### Running as Foreground Service

<Info>You cannot opt-out of this behaviour.</Info>

Vital Health SDK runs all its data sync workers inside a Foreground Service. Running as a foreground service helps in two ways:

1. It ensures ongoing data sync can run to completion even if the user switches away from your app; and

2. data sync workers have to be **in foreground** to read data from Health Connect. Health Connect prohibits
   reading data from background.

Android requires every Foreground Service to [be associated with a user-visible notification](https://developer.android.com/develop/background-work/services/foreground-services#user-dismiss-notification).
The OS typically grants a grace period of about 10 seconds before making the user aware of this notification. In other words,
if the data sync worker completes within the grace period, no notification would be posted.

Vital Health SDK installs these notification copies by default:

| Item                 | Copy                                                             |
| -------------------- | ---------------------------------------------------------------- |
| Notification Title   | Health Data Sync                                                 |
| Notification Content | `{APP_NAME}` is synchronizing with Health Connect...             |
| Channel Title        | Health Data Sync                                                 |
| Channel Description  | Notifies when `{APP_NAME}` is synchronizing with Health Connect. |

You can customize it through two ways:

<Tabs>
  <Tab title="Native Android">
    Register your custom `SyncNotificationBuilder` through `VitalHealthConnectManager.syncNotificationBuilder`.

    You should register it as soon as your app process is created. One way to ensure this is through the AndroidX Startup
    library. You can define an `Initializer` of your own that depends on the SDK `VitalHealthConnectInitializer`.

    #### An example App Startup Initializer implementation

    ```kotlin
    package com.example.app

    import android.content.Context
    import androidx.startup.Initializer
    import io.tryvital.vitalhealthconnect.VitalHealthConnectManager
    import io.tryvital.vitalhealthconnect.VitalHealthConnectInitializer

    class ExampleSyncNotificationBuilderInitializer: Initializer<Unit> {
        override fun create(context: Context) {
            val manager = VitalHealthConnectManager.getOrCreate(context)
            manager.syncNotificationBuilder = ExampleSyncNotificationBuilder
        }

        override fun dependencies(): MutableList<Class<out Initializer<*>>> = mutableListOf(
            VitalHealthConnectInitializer::class.java,
        )
    }
    ```

    #### An example `SyncNotificationBuilder` implementation

    ```kotlin
    package io.tryvital.sample

    import android.app.Notification
    import android.app.NotificationChannel
    import android.app.NotificationManager
    import android.content.Context
    import android.content.Context.NOTIFICATION_SERVICE
    import androidx.core.app.NotificationCompat
    import io.tryvital.vitalhealthconnect.SyncNotificationBuilder
    import io.tryvital.vitalhealthconnect.model.VitalResource

    object ExampleSyncNotificationBuilder: SyncNotificationBuilder {
        override fun build(context: Context, resources: Set<VitalResource>): Notification {
            return NotificationCompat.Builder(context, createChannel(context))
                .setContentTitle("Example Sync")
                .setContentText("Syncing your data")
                .setOngoing(true)
                .setSmallIcon(android.R.drawable.ic_popup_sync)
                .build()
        }

        fun createChannel(context: Context): String {
            val importance = NotificationManager.IMPORTANCE_MIN
            val mChannel = NotificationChannel("ExampleSyncNotification", "Example Sync", importance)
            mChannel.description = "Notifies when Example is syncing your data"
            val notificationManager = context.getSystemService(NOTIFICATION_SERVICE) as NotificationManager
            notificationManager.createNotificationChannel(mChannel)
            return mChannel.id
        }
    }
    ```
  </Tab>

  <Tab title="React Native">
    Register your custom copies through `VitalHealth.setSyncNotificationContent` as early as possible in
    your React Native root component.

    ```typescript
    import { VitalHealth } from '@tryvital/vital-health-react-native';

    await VitalHealth.setSyncNotificationContent({
        "notificationTitle": "Example Sync",
        "notificationContent": "Syncing your data",
        "channelName": "Example Sync",
        "channelDescription": "Notifies when Example is syncing your data"
    });
    ```
  </Tab>

  <Tab title="Flutter">
    Register your custom copies through `vital_health.setSyncNotificationContent` as early as possible in
    your Flutter app startup logic.

    ```typescript
    import 'package:vital_health/vital_health.dart' as vital_health;

    vital_health.setSyncNotificationContent(vital_health.SyncNotificationContent(
        "Example Sync",
        "Syncing your data",
        "Example Sync",
        "Notifies when Example is syncing your data"));
    ```
  </Tab>
</Tabs>

## Background Sync

Vital Health SDK supports an **opt-in** Android Background Sync feature. It provides a continuous monitoring
experience with Android Health Connect, siimlar to [Background Delivery for Apple HealthKit](/wearables/guides/apple-healthkit#background-delivery) on iOS.

### Sync Frequency

The [Sync On App Launch](#sync-on-app-launch) behaviour is always-on.

When Background Sync is enabled, the SDK additionally schedules hourly sync using the Android [Exact Alarms](https://developer.android.com/develop/background-work/services/alarms/schedule) mechanism.

The OS has full discretion on whether to honour or defer the time as scheduled by the Vital Health SDK. This includes the policies
of the base Android OS, as well as any vendor-specific OS augmentation.

For example, the device may enter [Doze mode](https://developer.android.com/training/monitoring-device-state/doze-standby) during device inactivity. Doze mode
would batch and defer most Exact Alarms and other background work to run at a lower frequency.

<Info>
  Not to be confused with Alarm Clock apps, **Exact Alarm** is the technical name of an Android framework for scheduling
  app wake-ups in background at certain wall clock time. It is the Vital Health SDK being silently "alarmed" in background.

  Your user **will not be alarmed hourly** as a result of enabling Background Sync.

  However, if the data sync took longer than 10 seconds, the OS might nudge them of this occurrence with a user-visible notification.
  The notification content is configurable by you — see the ["Running as Foreground Service"](#running-as-foreground-service) section for more details.
</Info>

### Runtime Permission Request

Since Android 12 (API Level 31), scheduling Exact Alarm (`SCHEDULE_EXACT_ALARM`) requires a runtime permission request from the user.
More specifically:

1. The user must go through an interactive flow to grant the *"Alarms & Reminders"* permission.
   * This flow is also reachable through the *"Alarms & Reminders"* section in Android Settings.
2. The user may refuse to grant the *"Alarms & Reminders"* permission.
3. The user may revoke the *"Alarms & Reminders"* permission through Android Settings at any time.

Since Android 13 (API Level 33), a new mutually exclusive `USE_EXACT_ALARM` permission was introduced. This permits your app to
schedule Exact Alarms without interactive permission requests.

<Warning>
  `USE_EXACT_ALARM` attracts scrutiny during Google Play Store review. Per the Google Play [Exact alarm permission policy](https://support.google.com/googleplay/android-developer/answer/9888170?hl=en-GB):

  > USE\_EXACT\_ALARM is a restricted permission and apps must only declare this permission if their core functionality supports
  > the need for an exact alarm. Apps that request this restricted permission are subject to review, and those that do not meet
  > the acceptable use case criteria will be disallowed from publishing on Google Play.
  >
  > *(excerpted on 20 March 2024)*

  If you choose to incorporate `USE_EXACT_ALARM`, you should prepare to justify to Google Play Store:

  1. Why hourly background sync is quintessential to your product experience; and
  2. Why the interactive permission request required by `SCHEDULE_EXACT_ALARM` is non-optimal to your product experience.
</Warning>

Here is a matrix summarizing the Exact Alarm permission request requirements:

| Android OS           | API Level | Requirements                                                                                                                                                                    |
| -------------------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Android 11 or below  | \<=30     | No interactive permission request.                                                                                                                                              |
| Android 12           | 31, 32    | `SCHEDULE_EXACT_ALARM`: Requires a runtime permission request. Revokable.                                                                                                       |
| Android 13 and above | >=33      | App must declare either:<ul><li>`SCHEDULE_EXACT_ALARM`: Requires runtime permission request. Revokable.</li><li>`USE_EXACT_ALARM`: No interactive permission request.</li></ul> |

### Updating your AndroidManifest.xml

Your app's AndroidManifest.xml must include the following `uses-permission` claims:

<Tabs>
  <Tab title="The SCHEDULE_EXACT_ALARM route">
    <Note>
      Make sure you read and understand [Runtime User Permission](#runtime-user-permission-android-12) before moving forward.
      This option is mutually exclusive with `USE_EXACT_ALARM` in the second tab.
    </Note>

    ```xml
    <?xml version="1.0" encoding="utf-8"?>
    <manifest ...>

        <uses-permission android:name="android.permission.SCHEDULE_EXACT_ALARM" />

    </manifest>
    ```
  </Tab>

  <Tab title="The USE_EXACT_ALARM route">
    <Warning>
      Make sure you read and understand [Runtime User Permission](#runtime-user-permission-android-12) before moving forward,
      especially the Google Play Store review policy surrounding the `USE_EXACT_ALARM` permission.
      This option is mutually exclusive with `SCHEDULE_EXACT_ALARM` in the first tab.
    </Warning>

    ```xml
    <?xml version="1.0" encoding="utf-8"?>
    <manifest ...>

        <uses-permission android:name="android.permission.USE_EXACT_ALARM" android:minSdkVersion="33" />

        <!-- Fallback to SCHEDULE_EXACT_ALARM on API Level 31-32 -->
        <uses-permission android:name="android.permission.SCHEDULE_EXACT_ALARM" android:maxSdkVersion="32" />

    </manifest>
    ```
  </Tab>
</Tabs>

### Enabling Background Sync

<Tabs>
  <Tab title="Native Android">
    You can enable Background Sync through `enableBackgroundSyncContract()` (an AndroidX `ActivityResultContract`).

    If the runtime [requires an interactive permission request](#runtime-user-permission-android-12), this contract will launch
    an Android Intent to request the *"Alarms & Reminders"* permission. The contract result is a boolean, indicating whether
    or not the Background Sync has been enabled successfully. For example, if the user did not grant the permission during the said Android Intent,
    the contract returns `false`.

    Otherwise, the contract returns `true` synchronously when no user interaction is required.

    You must launch this `ActivityResultContract` either through the in-built Android Compose support, or
    through the AndroidX Activity Result API if you do not use Android Compose.

    You can also inspect if Background Sync has been enabled through the `isBackgroundSyncEnabled` property.

    <CodeGroup>
      ```kotlin Android Compose
      import androidx.activity.compose.rememberLauncherForActivityResult
      import androidx.compose.runtime.rememberCoroutineScope
      import androidx.compose.material3.*
      import io.tryvital.vitalhealthconnect.VitalHealthConnectManager

      val manager: VitalHealthConnectManager = ...

      val permissionsLauncher = rememberLauncherForActivityResult(
          manager.enableBackgroundSyncContract()
      ) { success ->
          Log.i("VitalBackgroundSync", "Enabled? $success")

          val enabled = manager.isBackgroundSyncEnabled
          Log.i("VitalBackgroundSync", "Enabled? $enabled")
      }

      Button(onClick = { permissionsLauncher.launch(Unit) }) {
          Text("Enable Background Sync")
      }
      ```

      ```kotlin AndroidX Activity Result API
      import androidx.activity.ComponentActivity
      import io.tryvital.vitalhealthconnect.VitalHealthConnectManager

      val activity: ComponentActivity = ...
      val manager: VitalHealthConnectManager = ...

      activity.registerForActivityResult(contract) { success ->
          Log.i("VitalBackgroundSync", "Enabled? $success")

          val enabled = manager.isBackgroundSyncEnabled
          Log.i("VitalBackgroundSync", "Enabled? $enabled")
      }
      ```
    </CodeGroup>
  </Tab>

  <Tab title="React Native">
    You can enable Background Sync through `enableBackgroundSync()`.

    If the runtime [requires an interactive permission request](#runtime-user-permission-android-12),
    `enableBackgroundSync()` will launch an Android Intent to request the *"Alarms & Reminders"* permission.
    The promise result is a boolean, indicating whether or not the Background Sync has been enabled successfully.
    For example, if the user did not grant the permission during the said Android Intent, the contract returns `false`.

    Otherwise, `enableBackgroundSync()` returns `true` immediately when no user interaction is required.

    You can also inspect if Background Sync has been enabled through the `isBackgroundSyncEnabled` property.

    <Note>
      When running on iOS, both `enableBackgroundSync()` and `isBackgroundSyncEnabled` always return `true` immediately.
    </Note>

    ```typescript
    import { VitalHealth } from "@tryvital/vital-health-react-native";

    const success = await VitalHealth.enableBackgroundSync();
    console.log("background sync enabled?", success);

    const enabled = await VitalHealth.isBackgroundSyncEnabled;
    console.log("background sync enabled?", enabled);
    ```
  </Tab>

  <Tab title="Flutter">
    You can enable Background Sync through `enableBackgroundSync()`.

    If the runtime [requires an interactive permission request](#runtime-user-permission-android-12),
    `enableBackgroundSync()` will launch an Android Intent to request the *"Alarms & Reminders"* permission.
    The promise result is a boolean, indicating whether or not the Background Sync has been enabled successfully.
    For example, if the user did not grant the permission during the said Android Intent, the contract returns `false`.

    Otherwise, `enableBackgroundSync()` returns `true` immediately when no user interaction is required.

    You can also inspect if Background Sync has been enabled through the `isBackgroundSyncEnabled` property.

    <Note>
      When running on iOS, both `enableBackgroundSync()` and `isBackgroundSyncEnabled` always return `true` immediately.
    </Note>

    ```typescript
    import 'package:vital_health/vital_health.dart' as vital_health;

    final success = await vital_health.enableBackgroundSync();
    log("background sync enabled? ${success}")

    final enabled = await vital_health.isBackgroundSyncEnabled;
    log("background sync enabled? ${enabled}")
    ```
  </Tab>
</Tabs>

### Disabling Background Sync

<Tabs>
  <Tab title="Native Android">
    You can disable Background Sync through the `disableBackgroundSync()` method.

    You can also inspect if Background Sync has been disabled through the `isBackgroundSyncEnabled` property.

    ```kotlin
    import io.tryvital.vitalhealthconnect.VitalHealthConnectManager

    val manager: VitalHealthConnectManager = ...
    manager.disableBackgroundSync()

    val enabled = manager.isBackgroundSyncEnabled
    Log.i("VitalBackgroundSync", "Enabled? $enabled")
    ```
  </Tab>

  <Tab title="React Native">
    You can disable Background Sync through the `disableBackgroundSync()` method.

    You can also inspect if Background Sync has been disabled through the `isBackgroundSyncEnabled` property.

    <Note>
      When running on iOS, this API **is a no-op**. HealthKit Background Delivery is always-on
      on iOS.
    </Note>

    ```typescript
    import { VitalHealth } from "@tryvital/vital-health-react-native";

    await VitalHealth.disableBackgroundSync();

    const enabled = await VitalHealth.isBackgroundSyncEnabled;
    console.log("background sync enabled?", enabled);
    ```
  </Tab>

  <Tab title="Flutter">
    You can disable Background Sync through the `disableBackgroundSync()` method.

    You can also inspect if Background Sync has been disabled through the `isBackgroundSyncEnabled` property.

    <Note>
      When running on iOS, this API **is a no-op**. HealthKit Background Delivery is always-on
      on iOS.
    </Note>

    ```dart
    import 'package:vital_health/vital_health.dart' as vital_health;

    await vital_health.disableBackgroundSync();

    final enabled = await vital_health.isBackgroundSyncEnabled;
    log("background sync enabled? ${enabled}")
    ```
  </Tab>
</Tabs>

### Miscellaneous

When you `signOut()` a user, Vital SDK will automatically disable Background Sync.


# Apple HealthKit
Source: https://docs.junction.com/wearables/guides/apple-healthkit


Apple HealthKit is an SDK-based provider. Your iOS consumer app would embed the Vital Mobile SDKs on a supported
stack. Data are then pulled from the Apple HealthKit data store on the user's iOS device.

Refer to the [Mobile SDK Installation](/wearables/sdks/installation) and [Vital Health SDK](/wearables/sdks/vital-health) guides for SDK installation
instructions and general API usage. This guide contains information on the the behaviour and required configuration
specific to the Apple HealthKit integration.

<Card title="Mobile SDK Installation" icon="helmet-safety" href="/wearables/sdks/installation" horizontal>
  Learn about the minimum runtime and build-time requirements of Vital Mobile SDKs, and how to add them into
  your project through your package dependency manager.
</Card>

<Card title="Vital Health SDK" icon="heart" iconType="solid" href="/wearables/sdks/vital-health" horizontal>
  Learn about the initial setup required by Vital Health SDK, and the API exposed by Vital Health SDK
  for managing and inspecting health data permissions and automatic data sync.
</Card>

## Sync Frequency

| App state  | Behaviour                                                                 |
| ---------- | ------------------------------------------------------------------------- |
| Foreground | Apple HealthKit delivers any buffered and new changes immediately.        |
| Background | Hourly batch delivery of changes, subject to operating system throttling. |

While the SDK schedules hourly data sync with Apple HealthKit, iOS has full discretion to defer the scheduled time
based on factors like CPU usage, battery usage, connectivity, and Low Power Mode.

In other words, the Vital SDK — or any third-party HealthKit apps — cannot guarantee the sync to happen on a strict
schedule. The hourly schedule is advisory and non-binding from the persective of iOS. The actual delivery frequency
can therefore fluctuate from hourly, to once a day, or when certain opportunity arises (e.g., when Sleep Mode ends,
or when the phone starts charging).

## Getting Started

To enable this integration, you would need to integrate [Vital Core SDK](/wearables/sdks/vital-core) and
[Vital Health SDK](/wearables/sdks/vital-core) into your Native iOS, React Native or Flutter mobile app.

<Steps>
  <Step title="Add Vital SDKs as dependencies">
    Review the [installation requirements and package installation instructions](/wearables/sdks/installation).
  </Step>

  <Step title="Integrate with Vital Mobile SDK Authentication">
    Follow the [SDK Authentication](/wearables/sdks/authentication) guidance to integrate your app with the authentication
    mechanism of Vital Core SDK.
  </Step>

  <Step title="Configure Health SDK and ask user for read permissions">
    Follow the [Vital Health SDK](/wearables/sdks/vital-health) guidance to
    [configure your App Delegate](/wearables/sdks/vital-health#configure-your-app-delegate-ios-only),
    [configure the Health SDK](/wearables/sdks/vital-health#sdk-configuration) and to
    [ask for health data read permissions](/wearables/sdks/vital-health#ask-user-for-health-data-permissions) from your user.

    <Note>
      Health data sync is activated only on `VitalResource`s which you have asked permissions from your user for. If you
      did not ask for permissions, data sync would not occur.
    </Note>
  </Step>

  <Step title="Configure Background Delivery">
    Follow the [Apple HealthKit Background Delivery guidance](#setting-up-apple-healthkit-background-delivery) below to
    setup your iOS app target as an eligible target for Apple HealthKit Background Delivery.
  </Step>
</Steps>

## Setting up Apple HealthKit Background Delivery

<Warning>
  You **MUST** [configure your App Delegate](/wearables/sdks/vital-health#configure-your-app-delegate-ios-only) for
  Apple HealthKit Background Delivery to function as expected.
</Warning>

Vital Health SDK can subscribe to Apple HealthKit Background Delivery, so that data sync can happen automatically in
background. The subscription persists even when:

1. Your app user does not open your app regularly;
2. Your app user forces quit your app; or
3. The iPhone has been restarted for any reason.

<Note>
  Enabling Apple HealthKit will attract additional scrutiny in the App Store Review process. You should be prepared
  to explain and demonstrate your usage of these health and fitness data.
</Note>

### 1. Setup app entitlements

Enable the "HealthKit > Background Delivery" entitlement:

<img src="https://mintcdn.com/vital/img/iOS/health_kit_permission_background_delivery.png?maxW=692&auto=format&n=nR1fvAlwouZ87zVb&q=85&s=e58d282cb56db269d39d73d5d166cd92" width="692" height="146" data-path="img/iOS/health_kit_permission_background_delivery.png" srcset="https://mintcdn.com/vital/img/iOS/health_kit_permission_background_delivery.png?w=280&maxW=692&auto=format&n=nR1fvAlwouZ87zVb&q=85&s=7f133829fb75c9ce3149deed693f1312 280w, https://mintcdn.com/vital/img/iOS/health_kit_permission_background_delivery.png?w=560&maxW=692&auto=format&n=nR1fvAlwouZ87zVb&q=85&s=9df1ca4201968938989c1de4e62a61ae 560w, https://mintcdn.com/vital/img/iOS/health_kit_permission_background_delivery.png?w=840&maxW=692&auto=format&n=nR1fvAlwouZ87zVb&q=85&s=efa3921903aa47277f8eb795c967aac8 840w, https://mintcdn.com/vital/img/iOS/health_kit_permission_background_delivery.png?w=1100&maxW=692&auto=format&n=nR1fvAlwouZ87zVb&q=85&s=d7e87e20545b2a50d20d0da7efcf69ef 1100w, https://mintcdn.com/vital/img/iOS/health_kit_permission_background_delivery.png?w=1650&maxW=692&auto=format&n=nR1fvAlwouZ87zVb&q=85&s=475a49fcd341de3f97d1e6b7242ae7bb 1650w, https://mintcdn.com/vital/img/iOS/health_kit_permission_background_delivery.png?w=2500&maxW=692&auto=format&n=nR1fvAlwouZ87zVb&q=85&s=fa08ce71f81a974f91c60a20b95f2188 2500w" data-optimize="true" data-opv="2" />

Enable the "Background Modes > Background Processing entitlement:

<img src="https://mintcdn.com/vital/img/iOS/ios_background_processing.png?maxW=405&auto=format&n=nR1fvAlwouZ87zVb&q=85&s=33c59325b37bc5eb16d4d00698a5d36b" width="405" height="265" data-path="img/iOS/ios_background_processing.png" srcset="https://mintcdn.com/vital/img/iOS/ios_background_processing.png?w=280&maxW=405&auto=format&n=nR1fvAlwouZ87zVb&q=85&s=9bd44d0af587d589d4d90bcc529a993a 280w, https://mintcdn.com/vital/img/iOS/ios_background_processing.png?w=560&maxW=405&auto=format&n=nR1fvAlwouZ87zVb&q=85&s=e7418afc1066cd56ad3e4f4c0872d6d9 560w, https://mintcdn.com/vital/img/iOS/ios_background_processing.png?w=840&maxW=405&auto=format&n=nR1fvAlwouZ87zVb&q=85&s=09b29347e7a3d5213cba477cbaa70abe 840w, https://mintcdn.com/vital/img/iOS/ios_background_processing.png?w=1100&maxW=405&auto=format&n=nR1fvAlwouZ87zVb&q=85&s=140ada675991710f94a725c43f8df5a5 1100w, https://mintcdn.com/vital/img/iOS/ios_background_processing.png?w=1650&maxW=405&auto=format&n=nR1fvAlwouZ87zVb&q=85&s=4553ee120eaeb03bc1a28e839cdb1e02 1650w, https://mintcdn.com/vital/img/iOS/ios_background_processing.png?w=2500&maxW=405&auto=format&n=nR1fvAlwouZ87zVb&q=85&s=b50c9024e2d9f6dc6707f4a9182f22b8 2500w" data-optimize="true" data-opv="2" />

### 2. Update your Info.plist

In your "Info > Custom iOS Target Properties" section — also known as the `Info.plist` file — these entries should be
configured:

| Key                                                                                          | Value                                                                                                              |
| -------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------ |
| Privacy - Health Share Usage Description<br />(`NSHealthShareUsageDescription`)              | An explanation of your usage of the user's HealthKit data.                                                         |
| Permitted background task scheduler identifiers<br />(`BGTaskSchedulerPermittedIdentifiers`) | Include `io.tryvital.VitalHealthKit.ProcessingTask` in the array, alongside any other BGTask identifiers of yours. |

If you request write permissions, you must also specify:

| Key                                                                               | Value                                                                           |
| --------------------------------------------------------------------------------- | ------------------------------------------------------------------------------- |
| Privacy - Health Update Usage Description<br />(`NSHealthUpdateUsageDescription`) | An explanation of what user health data your app is writing to Apple HealthKit. |

### 3. Epilogue

You are all set!

Note that there is no need to call `syncData()` manually at all. Once you have asked the user for permission on
resources, sync would automatically starts every app launch, as well as whenever your app is woken up by Apple HealthKit to
respond to newly available data.

<Note>
  As per the [documentation](https://developer.apple.com/documentation/healthkit/hkhealthstore/1614175-enablebackgrounddelivery):

  > HealthKit wakes your app whenever a process saves or deletes samples of the specified type. The system wakes your app at most once per time period defined by the specified frequency. Some sample types have a maximum frequency of `HKUpdateFrequency.hourly`. The system enforces this frequency transparently.
  >
  > For example, on iOS, `stepCount` samples have an hourly maximum frequency.

  This means that although we have background delivery's frequency set to `.hourly`, we cannot guarantee hourly syncing on the dot.
</Note>


# Dexcom (G6 and older)
Source: https://docs.junction.com/wearables/guides/dexcom


<Note>
  `dexcom` is the provider slug for Dexcom (G6 and older).<br />
  For the OAuth-based `dexcom_v3` integration, see [Dexcom (OAuth based)](./dexcom_v3).
</Note>

<Warning>
  This provider is being phased out in favour of the new [OAuth-based Dexcom](./dexcom_v3) integration. Consider migrating to the new API at your earliest convinence.
</Warning>

## Enabling Dexcom Share

Your user needs to enable [Dexcom Share](https://www.dexcom.com/faqs/how-do-i-share-my-dexcom-g6-glucose-data-followers) for this connection to work:

<Steps>
  <Step title="Install Dexcom mobile app">
    They **must** use the Dexcom G6 mobile app ([iOS](https://apps.apple.com/us/app/dexcom-g6/id1209262925), [Android](https://play.google.com/store/apps/details?id=com.dexcom.g6)).

    Note that the Dexcom Clarity app would not work for this integration.
  </Step>

  <Step title="Enable Dexcom Share">
    Please refer to the [official help article on how to enable Dexcom Share](https://www.dexcom.com/faqs/how-do-i-share-my-dexcom-g6-glucose-data-followers).

    They **must** have at least one follower<sup>\[1]</sup> on Dexcom Share to keep the sharing activated. Otherwise, the API would
    stop reporting data to Vital.

    <Info>
      <sup>\[1]</sup> You can setup your own Dexcom account for your user to add as a follower in the Dexcom G6 mobile app.
      Alternatively, your user can invite `support@tryvital.io` as a follower.
    </Info>
  </Step>

  <Step title="Connect via Vital Link">
    They **must** connect to Vital using their *own* Dexcom account — the one which their Dexcom G6 app is signed into.
    This should **not** be the accounts of the followers.
  </Step>
</Steps>

## Vital Widget

To connect your device with the *widget*, follow the link wizard ensuring and enter your username and password.

## Vital Link

You can also connect a Dexcom user to vital using vital client. For additional information please consult the API reference.

<CodeGroup>
  ```python Python
  link_token = client.Link.create(user_id)
  client.Link.password_provider(
      link_token, "dexcom", username, password
  )
  ```

  ```javascript JavaScript
  const { link_token } = await client.Link.create(user_id);
  await client.Link.password_provider(
      link_token, "dexcom", username, password
  );
  ```
</CodeGroup>

## Webhooks

On successful connection, you will receive a [Connection create](/webhooks/data_flow#connection-created) wehbook. [Daily webhooks](/webhooks/data_flow#daily-data-flow) `data.daily.glucose.created` and `data.daily.glucose.updated` will also be issued to your team as new or more up-to-date data becomes available during the day.

For this provider however, Vital will begin to aggregate the data for the last 24 hours and will not go beyond that. As a result, there will be no [Historical webhooks](/webhooks/data_flow#historical-data-flow) issued. If you would like to pull the data immediately after connection, you can use the `user/refresh` endpoint.


# Dexcom (OAuth based)
Source: https://docs.junction.com/wearables/guides/dexcom_v3


<Note>
  `dexcom_v3` is the provider slug for Dexcom (OAuth based).<br />
  For the password-based `dexcom` integration, see [Dexcom (G6 and older)](./dexcom).
</Note>

<Info>
  Bring Your Own OAuth (BYOO) is available for [the Grow and Scale plans](https://tryvital.io/pricing).
  WHOOP BYOO is available for [the Launch, Grow and Scale plans](https://tryvital.io/pricing). See [our WHOOP Guide](/wearables/guides/whoop) for more information.
</Info>

## Connecting Dexcom to Vital

You can connect your dexcom device to vital through Vital Link Widget or programatically like any
other [OAuth](/api-reference/link/link-oauth-provider) provider.
We recommend you obtain custom OAuth credentials from [Dexcom](https://developer.dexcom.com) with production access and follow the guide
for [setting up custom credentials](/wearables/connecting-providers/bring_your_own_oauth) to get started.

## Webhooks

On successful connection, you will receive a [Connection create](/event-catalog/provider.connection.created) webhook,
and subsequently, [Daily](/event-catalog/daily.data.glucose.created) and [Historical](/event-catalog/historical.data.glucose.created) Glucose webhooks.

The histrical webhook informs you that the last **30 days** of data prior to connection is available and the daily webhooks follow the usual semantics
for all vital daily webhooks.


# Fitbit
Source: https://docs.junction.com/wearables/guides/fitbit


## Webhooks

There is one caveat with Fitbit's webhooks. Namely, Fitbit computes the basal metabolic rate (BMR) server-side. This is a fairly static value because it depends on data such as height, weight, gender, age, etc. The fact this is computed value server-side is important to keep in mind, because it means you will always receive `daily.data.activity.updated` webhooks even if you are not wearing the device.

This can be confusing at times, as someone who is not aware of this might wonder why are they getting only this one webhook and not the others.

If you are only getting `daily.data.activity.updated`, the most likely case is that the user is neither wearing the device, or they did not sync their device with the Fitbit app. If you are sure this is not the case, contact us through our support channels.

## Respiratory Rate timeseries

Fitbit does not provide detailed breakdown beyond average breaths-per-minute summary on a per sleep stage basis, i.e.,
REM average, Deep average, Light average and the whole session average.

Given this constraint, Vital constructs a respiratory rate timeseries for Fitbit as follows:

* Vital creates a respiratory rate data point for each hypnogram segment reported.
* The data point value will be one of the four average values mentioned, based on the stage represented by the segment.
* The data point will be timestamped to the **midnpoint** of the segment.

## Time Zone resolution

Fitbit stores all their data in floating time. Moreover, They do not tag most of their data points or summaries with time zone information.

Since Vital uses [UTC time basis](/wearables/providers/timestamps-and-time-zones), Vital has to convert the floating
time basis to the UTC time basis, before we can ingest the data and forward it onwards to you. To facilitate this
conversion, we must make an educated guess on the user's time zone.

Vital makes the best time zone guess in the following precedences:

<Steps>
  <Step number="1" title="Fitbit Profile">
    If the user has granted the Profile scope, Vital uses the timezone offset as provided by their Fitbit Profile.
  </Step>

  <Step number="2" title="Most recent Fitbit activity">
    If the user has granted the Activity scope, Vital uses the timezone offset from the most recently recorded activity (if any).
  </Step>

  <Step number="3" title="User Fallback Time Zone">
    If neither Fitbit data sources are available, Vital would use [User Fallback Time Zone](/wearables/providers/timestamps-and-time-zones#user-fallback-time-zone)
    if it has been set.
  </Step>

  <Step number="4" title="Naively assuming UTC">
    If none of above is available, Vital assumes naively that everything happens in UTC (+00:00).

    <Note>This is usually incorrect, except for users living an all-year UTC (+00:00) region.</Note>
  </Step>
</Steps>

<Warning>
  When your user refuses to grant both the activity and the profile scope, Fitbit data are more likely be timestamped incorrectly
  in UTC time basis due to inaccurate or unavailable time zone information.
</Warning>


# Garmin
Source: https://docs.junction.com/wearables/guides/garmin


## Webhooks & Events

Garmin connections have a non-standard [webhook lifecycle](/webhooks/introduction):

<Steps>
  <Step title="The Connection Created stage">
    You will receive a [Provider Connection Created event](/webhooks/introduction#connection-created-stage) normally.
  </Step>

  <Step title="The Historical Data Backfill stage">
    You would receive a [Historical Pull Completion event](/webhooks/introduction#historical-data-backfill-stage) **immediately** after the connection creation.
    However, if you query Vital API immediately, you would observe **no historical data**.

    <Warning>
      The Historical Pull Completion event for Garmin connections does not indicate availability of historical data through the Vital API.
    </Warning>
  </Step>

  <Step title="The Incremental Data stage">
    All **historical and new data** are delivered incrementally as [Data Events](/webhooks/introduction#incremental-data-stage) (`daily.data.*.*`).
  </Step>
</Steps>

<Note>
  This behaviour is exclusive to Garmin, as a downstream effect of Garmin's unique historical data access mechanism for third-party integrations.
</Note>

## Re-running the historical data backfill stage

Normally, when a user with an existing connection re-authenticates with the provider through [Vital Link](https://docs.tryvital.io/wearables/connecting-providers/introduction), Vital re-runs
the [Historical Data Backfill stage](/webhooks/introduction#historical-data-backfill-stage) automatically.

However, this **does not apply to Garmin** connections — you must first [deregister](/api-reference/user/deregister-a-provider) said users' existing Garmin connection for the re-run to take effect.

<Note>
  This behaviour is exclusive to Garmin, as a downstream effect of Garmin's unique historical data access mechanism for third-party integrations.
</Note>

## Vital Widget

To connect your device with the *widget*, follow the link wizard ensuring and enter your username and password.

<Frame>
  <img src="https://mintcdn.com/vital/img/garmin_link_search.jpg?maxW=476&auto=format&n=nR1fvAlwouZ87zVb&q=85&s=91b0af39297fab0c3c081267567f7a16" className="w-2/5 h-2/5 block mx-auto" width="476" height="704" data-path="img/garmin_link_search.jpg" srcset="https://mintcdn.com/vital/img/garmin_link_search.jpg?w=280&maxW=476&auto=format&n=nR1fvAlwouZ87zVb&q=85&s=2ecfa71aac59d0de0cb3c043b6f0c78f 280w, https://mintcdn.com/vital/img/garmin_link_search.jpg?w=560&maxW=476&auto=format&n=nR1fvAlwouZ87zVb&q=85&s=078e68e0d26b313ca89a5317916ca757 560w, https://mintcdn.com/vital/img/garmin_link_search.jpg?w=840&maxW=476&auto=format&n=nR1fvAlwouZ87zVb&q=85&s=512e3fc3c26a40882d40437c59438bb1 840w, https://mintcdn.com/vital/img/garmin_link_search.jpg?w=1100&maxW=476&auto=format&n=nR1fvAlwouZ87zVb&q=85&s=eb207bfbb87f9f12d4fd8b556e88cead 1100w, https://mintcdn.com/vital/img/garmin_link_search.jpg?w=1650&maxW=476&auto=format&n=nR1fvAlwouZ87zVb&q=85&s=530e18f47d084e5017f5714729c05dd2 1650w, https://mintcdn.com/vital/img/garmin_link_search.jpg?w=2500&maxW=476&auto=format&n=nR1fvAlwouZ87zVb&q=85&s=eb2ea4ac98a53acb797f3ca449351da0 2500w" data-optimize="true" data-opv="2" />

  <img src="https://mintcdn.com/vital/img/garmin_connect.jpg?maxW=457&auto=format&n=nR1fvAlwouZ87zVb&q=85&s=d7e6468bac93696bb1a122fae91641de" className="w-2/5 h-2/5 block mx-auto" width="457" height="895" data-path="img/garmin_connect.jpg" srcset="https://mintcdn.com/vital/img/garmin_connect.jpg?w=280&maxW=457&auto=format&n=nR1fvAlwouZ87zVb&q=85&s=4332dc7629a8aa29bba60afe29d3767c 280w, https://mintcdn.com/vital/img/garmin_connect.jpg?w=560&maxW=457&auto=format&n=nR1fvAlwouZ87zVb&q=85&s=745faf9077da018cd7eac4f874f32af2 560w, https://mintcdn.com/vital/img/garmin_connect.jpg?w=840&maxW=457&auto=format&n=nR1fvAlwouZ87zVb&q=85&s=c24a406f9bda558e457773f4c0d62605 840w, https://mintcdn.com/vital/img/garmin_connect.jpg?w=1100&maxW=457&auto=format&n=nR1fvAlwouZ87zVb&q=85&s=4e7c072ecc924c8925aa24b7863922fc 1100w, https://mintcdn.com/vital/img/garmin_connect.jpg?w=1650&maxW=457&auto=format&n=nR1fvAlwouZ87zVb&q=85&s=b49934910a4f0a23d3b384d058901d71 1650w, https://mintcdn.com/vital/img/garmin_connect.jpg?w=2500&maxW=457&auto=format&n=nR1fvAlwouZ87zVb&q=85&s=e8b275fa397988b4215a80826956d5a9 2500w" data-optimize="true" data-opv="2" />
</Frame>

<br />


# Google Fit
Source: https://docs.junction.com/wearables/guides/google_fit


## Delays in Syncing Data

### Intro

Google Fit via Cloud can have significant delay in data availability, more specifically between Google's Google Fit apps & Google's cloud data store - neither of which Vital has any control over. This is unlike using the Google Fit Android SDK directly, which can serve the latest local data immediately from the Google Fit data store, regardless of whether said local data have been uploaded to the Cloud already.

Vital isn't certain how/when Google Fit decides to upload new local data to cloud, and also whether or not there is additional delay caused by Google's internal data ingestion pipelines in the cloud. But one thing for sure is that it cannot be forced, and it seems to be managed by Android's standard WorkManager framework. This means connectivity, battery usage, Doze mode and App Standby will all dynamically affect the actual upload frequency. At worst case, this can mean uploads only happen when one is sleeping (the typical favourable time for the OS to run background work — the phone is on charger, has been idle extensively, and probably on WiFi).

### Why not use Google Fit Android SDK directly?

One way to avoid data delay is to use the Google Fit native SDK directly. However, Google Fit Android API has been deprecated by Google since May 2022 and support is set to end by end of 2024. For this reason we advise on using its successor: [HealthConnect](https://developer.android.com/guide/health-and-fitness/health-connect). You can find our docs [here](/wearables/sdks/android).

Keep in mind that HealthConnect has its own set of quirks. The most notable one is that Google decided to ban any data access when apps are in background. So it is unlikely to have the same smooth background monitoring experience like Apple HealthKit out of the box.


# Omron
Source: https://docs.junction.com/wearables/guides/omron


## Permissions with Omron

Omron's API does not provide information on what permissions users granted when connecting. Additionally it gives the same error for unauthorized resources and when a user uses one account in multiple environments, so we can't tell these apart.
Because of this, we only accept Omron connections with all permissions granted.


# Polar
Source: https://docs.junction.com/wearables/guides/polar


## Historical backfill with Polar

Polar unlike most other providers doesn't offer historical data for most of their resources.
The only resources that do have it are Sleep and Sleep Stream - 28 days each.


# WHOOP
Source: https://docs.junction.com/wearables/guides/whoop


<Info>
  WHOOP [Bring Your Own OAuth](/wearables/connecting-providers/bring_your_own_oauth) is available for [the Launch, Grow and Scale plans](https://tryvital.io/pricing).
</Info>

## Connecting WHOOP to Vital

WHOOP is a [BYOO](/wearables/connecting-providers/bring_your_own_oauth) only provider, so you will need your own app in [WHOOP's developer dashboard](https://developer-dashboard.WHOOP.com/).

Then, you can configure the WHOOP integration in the Vital dashboard by navigating to the Config > Custom Credentials page and clicking "Setup" next to WHOOP V2.
<img src="https://mintcdn.com/vital/img/whoop_config.png?maxW=1894&auto=format&n=nR1fvAlwouZ87zVb&q=85&s=145166dd3e2b07308913e40053291ae6" alt="WHOOP V2 config" width="1894" height="330" data-path="img/whoop_config.png" srcset="https://mintcdn.com/vital/img/whoop_config.png?w=280&maxW=1894&auto=format&n=nR1fvAlwouZ87zVb&q=85&s=f628900fa89acaca34a35eb55da5149f 280w, https://mintcdn.com/vital/img/whoop_config.png?w=560&maxW=1894&auto=format&n=nR1fvAlwouZ87zVb&q=85&s=7142ce6591064640259d7c3db6a4366a 560w, https://mintcdn.com/vital/img/whoop_config.png?w=840&maxW=1894&auto=format&n=nR1fvAlwouZ87zVb&q=85&s=f93f782d39cace42e0f384fc5daf0d72 840w, https://mintcdn.com/vital/img/whoop_config.png?w=1100&maxW=1894&auto=format&n=nR1fvAlwouZ87zVb&q=85&s=e08b8da80d0ffcc34cefc9a609cdf80d 1100w, https://mintcdn.com/vital/img/whoop_config.png?w=1650&maxW=1894&auto=format&n=nR1fvAlwouZ87zVb&q=85&s=682b8ac5cdc53502345f8e918c3e810a 1650w, https://mintcdn.com/vital/img/whoop_config.png?w=2500&maxW=1894&auto=format&n=nR1fvAlwouZ87zVb&q=85&s=2007c22ce5c2f2ef13a85427fea55212 2500w" data-optimize="true" data-opv="2" />

## Limitations

WHOOP sets forth the following limitation:

> Apps can be used for development immediately with a limit of 10 WHOOP members. To launch your app to all WHOOP members, you must first submit your app for approval.

Learn more about app approval in the [WHOOP developer documentation](https://developer.whoop.com/docs/developing/app-approval/). WHOOP reviews apps on a monthly cadence.


# Data Attributions
Source: https://docs.junction.com/wearables/providers/data-attributions


## Source Type

For summary data types, you can identify the Source Type through `source.type`. This is available in both summary data events and API responses.

For timeseries data types:

* You can identify the Source Type through `$.data.source.type` in timeseries data events you received.
* You can request timeseries data grouped by their Source Type through [the Grouped Timeseries Data API](/api-reference/timeseries-grouped/steps).

### Common

| Source Type        | Description                                                                 |
| ------------------ | --------------------------------------------------------------------------- |
| `unknown`          | The default value. Vital does not know how the provider collects this data. |
| `app`              | The user manually enters this data through an app.                          |
| `multiple_sources` | This data is derived from multiple sources.                                 |

### Wearables

| Source Type   | Description                                           |
| ------------- | ----------------------------------------------------- |
| `watch`       | A smart watch collects this data automatically.       |
| `phone`       | A smart phone collects this data automatically.       |
| `ring`        | A smart ring collects this data automatically.        |
| `chest_strap` | A smart chest strap collects this data automatically. |

### Health devices

| Source Type   | Description                                                        |
| ------------- | ------------------------------------------------------------------ |
| `manual_scan` | A biosensor that needs to be manually scanned.                     |
| `automatic`   | A biosensor that uploads data continuously in background.          |
| `fingerprick` | A glucose testing device which analyzes fingerprick blood samples. |
| `cuff`        | A blood pressure cuff.                                             |

### Supported providers

The following provider integrations would tag data with Source Type:

| Provider        | Source Types                                                |
| --------------- | ----------------------------------------------------------- |
| Apple HealthKit | `phone`, `watch`, `app`, `multiple_sources`, `unknown` \[1] |
| Fitbit          | `watch`, `scale`, `app`, `multiple_sources`                 |
| Oura            | `ring`, `app`, `multiple_sources`                           |
| Garmin          | `watch`, `scale`, `cuff`, `app`, `multiple_sources`         |
| Freestyle Libre | `automatic`, `manual_scan`                                  |

<sup>\[1]</sup> Only data from Apple Watch, iPhone and Apple Health app are tagged. Data from third-party apps
(like the Oura iOS app) are tagged as `unknown` currently.

## Device ID

Device ID indicates the specific device that collected the data, when this information is available with certainty.

For both summary and timeseries data types, it is available at `source.device_id`. When the originating device cannot be determined, this field is `null`.

### Device Attribution Coverage

Device attribution is available when Junction can confidently identify the originating device:

| Provider                          | Coverage                                            | Notes                                                                |
| --------------------------------- | --------------------------------------------------- | -------------------------------------------------------------------- |
| Withings                          | All resources except Body, Body Fat and Body Weight | Regardless of the number of reported devices                         |
| Polar                             | Workout and Sleep resources                         | Regardless of the number of reported devices                         |
| All other providers and resources | All resources                                       | When exactly one device is reported for the user-provider connection |

For connections with multiple devices where the provider doesn't embed device metadata, `source.device_id` remains `null` to avoid incorrect attribution.

### Supported providers

The following provider integrations can provide Device ID attribution:

| Provider                           |
| ---------------------------------- |
| Withings                           |
| Polar                              |
| Fitbit                             |
| Oura                               |
| Garmin                             |
| Renpho                             |
| Omron                              |
| Peloton                            |
| Dexcom v3                          |
| EightSleep                         |
| Freestyle Libre / Abbott Libreview |
| Apple HealthKit                    |
| Android Health Connect             |

## App ID

App ID indicates the origin application of the data.

For summary data types, it is available at `source.app_id`. Note that App ID is unavailable on timeseries data at this time.

### Supported providers

The following provider integrations would tag data with App ID:

| Provider               | Remarks                                                                                   |
| ---------------------- | ----------------------------------------------------------------------------------------- |
| Apple HealthKit        | App Store Bundle ID, or Unique Device ID (`com.apple.health.{UUID}`) for first-party data |
| Android Health Connect | Android Application Package Name                                                          |

## Workout ID

If a Workout ID is present, the data are associated with the referenced Junction [Workout](/api-reference/data/workouts/get-summary) summary.

Workout ID is only available in the following Workout Stream timeseries resources (`workout_*`):

| Resource                  | Remarks                                                |
| ------------------------- | ------------------------------------------------------ |
| `workout_distance`        | All data must have an associated Workout ID and Sport. |
| `workout_swimming_stroke` | All data must have an associated Workout ID and Sport. |

### Supported providers

The following provider integrations would tag data with Workout ID:

| Provider        |
| --------------- |
| Apple HealthKit |

## Sport

If a sport slug is present, the data are known to be measuring the referenced Sport type.

Sport slug is only available in the following timeseries resources:

| Resource                  | Remarks                                                                                                      |
| ------------------------- | ------------------------------------------------------------------------------------------------------------ |
| `workout_distance`        | All data must have an associated Workout ID and Sport.                                                       |
| `workout_swimming_stroke` | All data must have an associated Workout ID and Sport.                                                       |
| `distance`                | All-day wheelchair distance data are tagged with `sport = wheelchair_push`. Otherwise, sport is unspecified. |

### Supported providers

The following provider integrations would tag data with Sport:

| Provider        |
| --------------- |
| Apple HealthKit |


# Data Ingestion Bounds
Source: https://docs.junction.com/wearables/providers/data-ingestion-bounds


## Overview

By default, Vital:

* pulls historical data as far back as indicated by the [pull preferences](/wearables/providers/introduction#customizing-historical-data-pull-range)
  you specified (if any), or the [default historical pull range](/wearables/providers/introduction#historical-data-pull-range).

* accepts **all** new and changed data discovered through polling, incoming provider webhooks and Vital Mobile SDK integrations.

If you need to impose a date bounds on the data being collected, you can set **data ingestion bounds** on a per-user basis:

* The data ingestion bounds restricts the historical pull range of any new connections of the user.

* The data ingestion bounds restricts data ingestion from any connections of the user — out of bound data are dropped.

* When the user ingestion end date is reached, a 7-day late delivery catchment period starts. Once the catchment
  period expires, all connections of the user are automatically de-registered and marked as *paused*.

<Note>
  Because *dates* are in floating time, you should expect an error margin of ±1 days on ingestion bound enforcement.
  If you cannot tolerate an error margin, offset the user data ingestion bounds you set accordingly.
</Note>

## Setting Ingestion Start and End Dates

You can specify the user data ingestion bounds (`ingestion_start` and `ingestion_end`) when you:

* [Create a new user](/api-reference/user/create-user); or

* [Update an existing user](/api-reference/user/patch-user)

```json Example
{
  "user_id": "409d9870-21fb-443a-8daa-c5222659f40e",
  "team_id": "3aac677c-557f-40b7-9251-0315c1f48e77",
  "client_user_id": "d734e32e-dd43-4b77-ab56-692524279531",
  /** snipped **/
  "ingestion_start": "2024-01-01",
  "ingestion_end": "2024-12-15",
}
```

## Changing Ingestion Bounds

You can change the ingestion bounds at any time.

However, do note that it has no retrospective effect on data already ingested — Vital does not delete collected data
in response to ingestion bound changes.

As long as the connection has not been marked as *paused*, you can change the ingestion end date to extend the ingestion
bounds at any time, even during the (post ingestion end) 7-day late delivery catchment period.

Otherwise, the ingestion end date has no effect on any *paused* cloud-based connections — since these connections have been
deregistered with the data provider, the end user needs to go through the Vital Link flow to re-connect.


# Primary Key
Source: https://docs.junction.com/wearables/providers/data-primary-key


## Summary types

Each summary is uniquely identified by its ID (`$.id`).

Given the same ID, the latest version of a summary you received **replaces** all its previous versions.

## Timeseries types

Each timeseries sample is uniquely identified by a compound key of:

* the timeseries resource type;
* the source provider;
* the [Source Type](/wearables/providers/data-attributions#source-type); and
* the sample timestamp.

Given the same compound key, the latest value of a sample you received **replaces** all the previous values.


# Heart Rate Zones
Source: https://docs.junction.com/wearables/providers/heart-rate-zones


## Heart Rate Zones Calculation

Heart rate zones are segments in a workout session. They are based on the percentage brackets of the user's maximum heart rate. \[under 50%, 50-60%, 60-70%, 70-80%, 80-90%, above 90%]

The maximum heart rate for a person is calculated with a straightforward formula: `220 - age`.

## Fallback Birth Date

Some providers may not share the user's birth date, making it impossible for Vital to know the user's age. To solve this, users can provide a Fallback Birth Date as an alternative option.

You can specify the Fallback Birth Date when:

* [Creating a new user](/api-reference/user/create-user); or

* [Patching an existing user](/api-reference/user/patch-user)

You will also get information about the source (by slug) and the last updated time of the Fallback Birth Date [when getting an existing user](/api-reference/user/get-user).

Fallback Birth Date supplied via the REST API would always have a source slug of `manual`.

<Info>
  If no birth date information is available, the assumed age of 30 is used in the calculations.
</Info>

```json Example
{
  "user_id": "409d9870-21fb-443a-8daa-c5222659f40e",
  "team_id": "3aac677c-557f-40b7-9251-0315c1f48e77",
  "client_user_id": "d734e32e-dd43-4b77-ab56-692524279531",
  /** snipped **/
  "fallback_birth_date": {
    "value": "1980-09-12",
    "source_slug": "manual",
    "updated_at": "2022-09-11T13:45:56+00:00"
  }
}
```


# Supported providers
Source: https://docs.junction.com/wearables/providers/introduction


We currently Support over 300+ devices, a full list can be seen below.

## Cloud Based Providers

<Note>
  Some OAuth providers are unavailable unless you can <b>[Bring Your Own OAuth (BYOO)](/wearables/connecting-providers/bring_your_own_oauth)</b>.
  You will have to apply directly to the provider for an OAuth application, and
  provide Vital your assigned credentials once the application is accepted.
</Note>

### Generally Available

| Provider (Slug)                                                           | Description                                 | Availability                          | Remarks                                                                |
| ------------------------------------------------------------------------- | ------------------------------------------- | ------------------------------------- | ---------------------------------------------------------------------- |
| [Beurer](https://www.beurer.com/web/gb/)         <br />`beurer_api`       | Beurer Blood Pressure monitors              | All Vital Teams                       | Password Auth                                                          |
| [Dexcom (G6 And Older)](https://www.dexcom.com)  <br />`dexcom`           | Dexcom CGM Glucose monitors                 | All Vital Teams                       | Password Auth<br />[↗️ Guide](/wearables/guides/dexcom)                |
| [8Sleep](https://www.eightsleep.com)             <br />`eight_sleep`      | Smart Mattress                              | All Vital Teams                       | Password Auth                                                          |
| [Abbott LibreView](https://www.libreview.com/)   <br />`abbott_libreview` | Abbott CGM Glucose monitor                  | All Vital Teams                       | Password Auth<br />[↗️ Guide](/wearables/guides/abbott-libreview)      |
| [Freestyle Libre](https://www.libreview.com/)    <br />`freestyle_libre`  | Abbott CGM Glucose monitor                  | All Vital Teams                       | LibreView Practice<br />[↗️ Guide](/wearables/guides/abbott-libreview) |
| [Fitbit](https://www.fitbit.com/global/uk/home)  <br />`fitbit`           | Activity Trackers (all devices)             | All Vital Teams                       | OAuth<br />[↗️ Guide](/wearables/guides/fitbit)                        |
| [Garmin](https://www.garmin.com)                 <br />`garmin`           | Fitness watches (all devices)               | All Vital Teams                       | OAuth<br />[↗️ Guide](/wearables/guides/garmin)                        |
| [Hammerhead](https://www.hammerhead.io)          <br />`hammerhead`       | Cycling computers                           | All Vital Teams                       | Password Auth                                                          |
| [Oura](https://ouraring.com)                     <br />`oura`             | Smart Sleep tracking ring                   | All Vital Teams                       | OAuth                                                                  |
| [Peloton](https://www.onepeloton.com)            <br />`peloton`          | Popular Indoor Exercise bike                | All Vital Teams                       | Password Auth                                                          |
| [Strava](https://www.strava.com)                 <br />`strava`           | Running & Cycling Social Network            | All Vital Teams                       | OAuth                                                                  |
| [Wahoo](https://wahoofitness.com)                <br />`wahoo`            | Cycling Equipment                           | All Vital Teams                       | OAuth                                                                  |
| [Withings](https://www.withings.com)             <br />`withings`         | Fitness scales, watches and health monitors | All Vital Teams                       | OAuth                                                                  |
| [Zwift](https://zwift.com)                       <br />`zwift`            | Virtual cycling and running                 | All Vital Teams                       | Password Auth                                                          |
| [Polar](https://www.polar.com/accesslink-api/)   <br />`polar`            | Finnish sports tech pioneer                 | All Vital Teams                       | OAuth<br />[↗️ Guide](/wearables/guides/polar)                         |
| [Cronometer](https://www.cronometer.com)         <br />`cronometer`       | Nutrition data                              | All Vital Teams                       | OAuth                                                                  |
| [Ultrahuman](https://www.cronometer.com)         <br />`ultrahuman`       | Real-time nutrition and fitness tracking    | 🧪 **Open Beta**<br />All Vital Teams | OAuth                                                                  |

### BYOO-only

<Info>
  Bring Your Own OAuth (BYOO) is available for [the Grow and Scale plans](https://tryvital.io/pricing).
  WHOOP BYOO is available for [the Launch, Grow and Scale plans](https://tryvital.io/pricing). See [our WHOOP Guide](/wearables/guides/whoop) for more information.
</Info>

<Warning>
  Some BYOO providers do not have a developer program with open sign-up.
</Warning>

| Provider (Slug)                                                                   | Description                                                   | Availability                                                          | Remarks                                                    |
| --------------------------------------------------------------------------------- | ------------------------------------------------------------- | --------------------------------------------------------------------- | ---------------------------------------------------------- |
| [Dexcom](https://www.dexcom.com)                 <br />`dexcom_v3`                | Dexcom CGM Glucose monitors                                   | ⚠️ [BYOO only](/wearables/connecting-providers/bring_your_own_oauth)  | Password Auth<br />[↗️ Guide](/wearables/guides/dexcom_v3) |
| [iHealth](https://ihealthlabs.com)               <br />`ihealth`                  | Blood pressure, Fitness scales, Glucometers & Fitness watches | ⚠️  [BYOO only](/wearables/connecting-providers/bring_your_own_oauth) | OAuth                                                      |
| [WHOOP](https://www.whoop.com)                   <br />`whoop_v2`                 | Your Personal Digital Fitness and Health Coach                | ⚠️  [BYOO](/wearables/connecting-providers/bring_your_own_oauth) only | OAuth<br />[↗️ Guide](/wearables/guides/whoop)             |
| [MyFitnessPal API](https://www.myfitnesspalapi.com) <br />`my_fitness_pal_v2`     | Nutrition data                                                | ⚠️  [BYOO](/wearables/connecting-providers/bring_your_own_oauth) only | OAuth                                                      |
| [MapMyFitness](https://developer.mapmyfitness.com)         <br />`map_my_fitness` | Technology for all atheletes                                  | ⚠️  [BYOO](/wearables/connecting-providers/bring_your_own_oauth) only | OAuth                                                      |

### Deprecated providers

| Provider (Slug)                                                         | Status                                                                                      | Availability    | Remarks                                                                        |
| ----------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- | --------------- | ------------------------------------------------------------------------------ |
| [Google Fit](https://www.google.com/fit/)           <br /> `google_fit` | Google will shut down Google Fit on June 30, 2025. Android Health Connect is the successor. | All Vital Teams | OAuth<br />[↗️ Guide](/wearables/guides/google_fit)                            |
| [MyFitnessPal](https://www.myfitnesspal.com)     <br />`my_fitness_pal` | Deprecated                                                                                  | All Vital Teams | MyFitnessPal Diary Share Key<br />[↗️ Guide](/wearables/guides/my_fitness_pal) |

## SDK Based Providers

| Provider (Slug)                                                                                  | Description                                       | Guide                                                |
| ------------------------------------------------------------------------------------------------ | ------------------------------------------------- | ---------------------------------------------------- |
| [Accu-Chek](https://www.accu-chek.com) (Bluetooth)                   <br />`accuchek_ble`        | Glucose Strips/MySugr App                         |                                                      |
| [Apple HealthKit](https://www.apple.com/uk/ios/health/)              <br />`apple_health_kit`    | Health and fitness data on iPhone and Apple Watch | [↗️ Guide](/wearables/guides/apple-healthkit)        |
| [Beurer](https://www.beurer.com/web/gb/) (Bluetooth)                 <br />`beurer_ble`          | Beurer Blood Pressure monitors                    |                                                      |
| [Contour](https://www.diabetes.ascensia.com) (Bluetooth)             <br />`contour_ble`         | Glucometers                                       |                                                      |
| [Freestyle Libre BLE](https://www.freestylelibre.co.uk/libre/) (NFC) <br />`freestyle_libre_ble` | Abbott CGM Glucose monitor readings via SDK       |                                                      |
| [Omron](https://www.omron-healthcare.com) (Bluetooth)                <br />`omron_ble`           | Blood Pressure monitors and scales                |                                                      |
| [Android Health Connect](https://developer.android.com/health-connect)<br />`health_connect`     | Health and fitness data on Android devices        | [↗️ Guide](/wearables/guides/android-health-connect) |

## Providers under beta

**Beta**: Providers under beta, these are providers that have been recently added. All providers here are available in sandbox, any feedback you have is greatly appreciated!

| Provider                                          | Slug     | Description                        |
| ------------------------------------------------- | -------- | ---------------------------------- |
| [Omron](https://www.omron-healthcare.com) (Cloud) | `omron`  | Blood Pressure monitors and scales |
| [Kardia](https://kardia.com/)                     | `kardia` | Electrocardiogram readings         |

**Planned**: On our roadmap

| Provider                                        | Slug       | Description               | Stage   |
| ----------------------------------------------- | ---------- | ------------------------- | ------- |
| [Xiaomi](https://www.xiaomi.com)                | `xiaomi`   | All data                  | Enquire |
| [Suunto](https://www.suunto.com)                | `suunto`   | Fitness Watch             | Planned |
| [iGlucose](https://smartmeterrpm.com/iglucose/) | `iglucose` | Glucose Strips            | Planned |
| [KetoMojo](https://keto-mojo.com)               | TBD        | Glucose, Ketones and more | Planned |

## Full Device Support List

<iframe src="https://airtable.com/embed/shrnlG3Z7tunKuUwh/tblRcat09AWv1Aj7L/viwgVLLG0uqKB0vbi" frameborder="0" allowfullscreen="true" width="100%" height="533" loading="lazy">
  {" "}
</iframe>

## Data Frequency

Whenever Vital detects that new data is available, [data events](/event-catalog) are always sent to your configured endpoints, regardless of the provider being push-based or polling-based.

### Cloud Based Providers

Cloud Based Providers can be divided in two main categories:

* Push-based

  * When a cloud-based provider supports a push notify mechanism (typically webhooks), Vital would prefer to use it to drive data fetches. In other words, as soon as the provider notifies Vital of new data through the said mechanism, Vital fetches the latest data.

* Polling-based

  * For providers and/or resources without any push notify mechanism, Vital polls these resources at a regular schedule, typically every 15 minutes or so.

| Provider                                                        | Description |
| --------------------------------------------------------------- | ----------- |
| [Fitbit](https://www.fitbit.com/global/uk/home)                 | Push        |
| [Garmin](https://www.garmin.com)                                | Push        |
| [Strava](https://www.strava.com)                                | Push        |
| [Wahoo](https://wahoofitness.com)                               | Push        |
| [Withings](https://www.withings.com)                            | Push        |
| [iHealth](https://ihealthlabs.com)                              | Push        |
| [Freestyle](https://www.freestylelibre.co.uk/libre/)(API + SDK) | Polling     |
| [Google Fit](https://www.google.com/fit/)                       | Polling     |
| [Oura](https://ouraring.com)                                    | Polling     |
| [Peloton](https://www.onepeloton.com)                           | Polling     |
| [WHOOP](https://www.whoop.com)                                  | Push        |
| [Zwift](https://zwift.com)                                      | Polling     |
| [8Sleep](https://www.eightsleep.com)                            | Polling     |
| [Hammerhead](https://www.hammerhead.io)                         | Polling     |
| [Dexcom](https://www.dexcom.com)                                | Polling     |
| [MyFitnessPal](https://www.myfitnesspal.com)                    | Polling     |
| [Cronometer](https://www.cronometer.com)                        | Push        |

### SDK Based Providers

SDK Based Providers are all push-based, where data are pushed from the Vital SDK embedded inside your Android or iOS app.

| Provider                                                               | Description                                                                                                          |
| ---------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------- |
| [Apple HealthKit](https://www.apple.com/uk/ios/health/)                | <ul><li>Auto sync on app launch and in foreground</li><li>Hourly Background Sync, subject to OS throttling</li></ul> |
| [Android Health Connect](https://developer.android.com/health-connect) | <ul><li>Sync On App Launch</li><li>Opt-in Hourly Background Sync, subject to OS throttling</li></ul>                 |
| [Omron](https://www.omron-healthcare.com)                              | Manual Post                                                                                                          |
| [Contour](https://www.diabetes.ascensia.com)                           | Manual Post                                                                                                          |
| [Accu-Chek](https://www.accu-chek.com)                                 | Manual Post                                                                                                          |

For more information on Apple HealthKit and Android Health Connect, please refer to the specific guides:

* [Vital Health SDK: Automatic Data Sync](/wearables/sdks/vital-health#automatic-data-sync)
* [Apple HealthKit: Sync Frequency](/wearables/guides/apple-healthkit#sync-frequency)
* [Android Health Connect: Sync Frequency](/wearables/guides/android-health-connect#sync-frequency)

## Historical Data Pull Range

Vital fetches the historical data immediately when the connection is established. The pull range
can be estimated by `[now - days_to_pull, now]`.

| Provider                                                                     | Default  | Configurable | Remarks                                                                                                                                                                                                                       |
| ---------------------------------------------------------------------------- | -------- | ------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [Abbott LibreView](https://www.libreview.com)                                | 90 days  | ❌            | -                                                                                                                                                                                                                             |
| [Fitbit](https://www.fitbit.com/global/uk/home)                              | 90 days  | ⚠️           | Activity and heartrate timeseries data are fixed to 14 days.                                                                                                                                                                  |
| [Garmin](https://www.garmin.com)                                             | 90 days  | ✅            | -                                                                                                                                                                                                                             |
| [Google Fit](https://www.google.com/fit/)                                    | 90 days  | ✅            | -                                                                                                                                                                                                                             |
| [Oura](https://ouraring.com)                                                 | 180 days | ✅            | -                                                                                                                                                                                                                             |
| [Peloton](https://www.onepeloton.com)                                        | 180 days | ✅            | -                                                                                                                                                                                                                             |
| [Strava](https://www.strava.com)                                             | 14 days  | ✅            | -                                                                                                                                                                                                                             |
| [Wahoo](https://wahoofitness.com)                                            | 180 days | ✅            | -                                                                                                                                                                                                                             |
| [WHOOP](https://www.whoop.com)                                               | 180 days | ✅            | -                                                                                                                                                                                                                             |
| [Zwift](https://zwift.com)                                                   | 270 days | ✅            | -                                                                                                                                                                                                                             |
| [Withings](https://www.withings.com)                                         | 90 days  | ✅            | -                                                                                                                                                                                                                             |
| [8Sleep](https://www.eightsleep.com)                                         | 90 days  | ✅            | -                                                                                                                                                                                                                             |
| [Apple HealthKit](https://www.apple.com/uk/ios/health/) (SDK)                | 30 days  | ✅            | -                                                                                                                                                                                                                             |
| [Android Health Connect](https://developer.android.com/health-connect) (SDK) | 30 days  | ❌            | Google restricts access to historical data to [30 days before the first successful permission request](https://developer.android.com/health-and-fitness/guides/health-connect/develop/frequently-asked-questions#time-range). |
| [Hammerhead](https://www.hammerhead.io)                                      | 30 days  | ✅            | -                                                                                                                                                                                                                             |
| [Dexcom](https://www.dexcom.com)                                             | 30 days  | ✅            | -                                                                                                                                                                                                                             |
| [Dexcom (G6 And Older)](https://www.dexcom.com)                              | 1 day    | ❌            | -                                                                                                                                                                                                                             |
| [MyFitnessPal](https://www.myfitnesspal.com)                                 | 14 days  | ✅            | -                                                                                                                                                                                                                             |
| [Polar](https://www.polar.com/accesslink-api/#polar-accesslink-api)          | 28 days  | ❌            | Polar only supports historical backfill for Sleep and Sleep Stream resources.                                                                                                                                                 |
| [Cronometer](https://www.cronometer.com)                                     | 28 days  | ✅            | -                                                                                                                                                                                                                             |

<Note>
  The configurable maximum is 365 days at this time.
</Note>

### Customizing historical data pull range

<Info>
  Org Management API is available for [the Scale plan](https://tryvital.io/pricing).
</Info>

You can configure the historical pull range using the [Team Data Pull Preferences](/api-reference/org-management/team-data-pull-preferences/upsert-team-data-pull-preferences)
feature of the Org Management API.

You can specify a number of days to backfill that uniformly applies to all resources of a provider, as well as overriding the
the number of days to backfill for specific resources.

<Info>
  The Team Data Pull Preferences you specified is *advisory*. There are scenarios in which Vital systems
  may not adhere strictly to your stated preferences.
</Info>


# Resources
Source: https://docs.junction.com/wearables/providers/resources


## Overview

There are two broad resource categories provided by Vital:

* A **Summary** type is a summarization of a specific calendar day or a session.
* A **Timeseries** type is a time-ordered collection of data samples.

There is no relation in resource availability among these two categories. Some providers do offer both,
while some providers offer only one category. For example:

* Fitbit provides daily activity summaries, as well as **some** high-frequency activity timeseries data.
* Oura provides only daily activity summary, without any complementary high-frequency activity timeseries data.

There is also no strict relation between a field in a *Summary* type and a *Timeseries* type.
For example:

* The existence of a `sleep_efficiency` summary field does not imply that there is a corresponding `sleep_efficiency` timeseries.
* The existence of a Glucose Timeseries type does not imply that there is a corresponding `glucose` summary field.
* A *Timeseries* type could derive multiple summary fields, e.g., heart rate statistics and HR zones.

### Summary types

| Granularity | Resources                                                                                                    |
| ----------- | ------------------------------------------------------------------------------------------------------------ |
| Daily       | `activity`                                                                                                   |
| Session     | `sleep`, `sleep_cycle`, `workouts`, `body`, `meal`, `menstrual_cycle`, `electrocardiogram`, `workout_stream` |
| Single      | `profile`                                                                                                    |

### Discrete Timeseries types

Each value is associated with a single point in time.

| Category          | Resources                                                                                    |
| ----------------- | -------------------------------------------------------------------------------------------- |
| Cardiorespiratory | `respiratory_rate`                                                                           |
| Vitals            | `blood_oxygen`, `blood_pressure`, `glucose`, `heartrate`, `hrv`, `electrocardiogram_voltage` |
| Wellness          | `stress_level`                                                                               |
| Body              | `fat`, `weight`                                                                              |

### Interval Timeseries types

Each value is associated with a half-open time interval (`[start, end[`).

| Category          | Resources                                                                                                                                                                 |
| ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Activity          | `calories_active`, `calories_basal`, `distance`, `floors_climbed`, `steps`, `workout_duration`, `fall`, `wheelchair_push`, `stand_duration`, `stand_hour`                 |
| Body              | `body_temperature`, `body_temperature_delta`, `insulin_injection`, `waist_circumference`, `body_mass_index`, `lean_body_mass`, `basal_body_temperature`                   |
| Vitals            | `afib_burden`, `heart_rate_alert`, `forced_expiratory_volume_1`, `forced_vital_capacity`, `peak_expiratory_flow_rate`,  `inhaler_usage`, `heart_rate_recovery_one_minute` |
| Cardiorespiratory | `vo2_max`                                                                                                                                                                 |
| Nutrition         | `carbohydrates`, `caffeine`, `water`                                                                                                                                      |
| Wellness          | `mindfulness_minutes`, `sleep_apnea_alert`, `sleep_breathing_disturbance`, `uv_exposure`, `daylight_exposure`, `handwashing`                                              |
| Workout Stream    | `workout_distance`, `workout_swimming_stroke`                                                                                                                             |
| Diary             | `note`                                                                                                                                                                    |

## Timeseries Data Sampling Rates

Junction records and forwards timeseries data from the data provider, without any upsampling or downsampling applied.
Even within the same data provider, these data may come from different devices or data sources with varying sampling rates.

Because of this, you should not make assumptions of any particular timeseries resource having a fixed sampling rate.

For technical design and capacity planning purposes, you may model after the following three categories of timeseries resources:

### Very High Frequency Timeseries

Second-level peak sampling rate; typically 1000s to low 10000s samples per day.

| Peak rate                  | Example Scenario     |
| -------------------------- | -------------------- |
| 1 sample every 3 seconds   | Apple Watch workouts |
| 1 sample every 15 seconds  | Garmin               |
| 1 sample every 1-15 minute | Apple Watch, Fitbit  |

Resources that fall into this category:

| Resource          | Events                         | Notable Providers     |
| ----------------- | ------------------------------ | --------------------- |
| `heartrate`       | `daily.data.heartrate.*`       | Apple, Fitbit, Garmin |
| `calories_active` | `daily.data.calories_active.*` | Apple, Fitbit, Garmin |

### High frequency Timeseries

Minute-level peak sampling rate; typically 100s samples per day.

| Peak rate                 | Example Scenario                                   |
| ------------------------- | -------------------------------------------------- |
| 1 sample every 1 minute   | Fitbit Intraday timeseries data                    |
| 1 sample every 15 minutes | Garmin all-day activity timeseries data ("epochs") |

Resources that fall into this category:

| Resource            | Events                           | Notable Providers     |
| ------------------- | -------------------------------- | --------------------- |
| `steps`             | `daily.data.steps.*`             | Apple, Fitbit, Garmin |
| `calories_basal`    | `daily.data.calories_basal.*`    | Apple                 |
| `distance`          | `daily.data.distance.*`          | Apple, Fitbit, Garmin |
| `glucose`           | `daily.data.glucose.*`           | LibreView, Dexcom     |
| `stress_level`      | `daily.data.stress_level.*`      | Garmin                |
| `hrv`               | `daily.data.hrv.*`               | Garmin, Fitbit        |
| `respiratory_rate`  | `daily.data.respiratory_rate.*`  | Garmin, Fitbit        |
| `blood_oxygen`      | `daily.data.blood_oxygen.*`      | Fitbit                |
| `daylight_exposure` | `daily.data.daylight_exposure.*` | Apple                 |
| `stand_duration`    | `daily.data.stand_duration.*`    | Apple                 |

### Sparse Timeseries

<Info>
  All timeseries resources not specified as (Very) High Frequency fall into this category.
</Info>

Day-level peak sampling rate; typically no more than 5 per day.

| Peak rate                 | Example Scenario                                   |
| ------------------------- | -------------------------------------------------- |
| 1 sample every day        | Apple Watch wrist temperature delta                |
| 1 sample every 15 minutes | Garmin all-day activity timeseries data ("epochs") |
| Unpredictable / Never     | Heart Rate Alerts, Sleep Apnea Alerts              |

## Summary types by providers

<iframe src="https://airtable.com/embed/shrYd0PGVhx5lTemu?backgroundColor=gray&layout=card" frameborder="0" allowfullscreen="true" width="100%" height="1200" loading="lazy">
  {" "}
</iframe>

## Timeseries types by providers

<iframe src="https://airtable.com/embed/shrtq9mZDz6BRXuz2?backgroundColor=gray&layout=card" frameborder="0" allowfullscreen="true" width="100%" height="1200" loading="lazy">
  {" "}
</iframe>

## Fetching via the API

<Tip>
  Summary resources can be fetched from our `/summary/<resource>/<user_id>` API, while everything else via `/timeseries/<user_id>/<resource>`.
</Tip>

For example, `Workouts` is made up of fields specific to an workout, like calories, distance and duration. When you make a request to `/summary/workouts/<user_id>` you get the following fields:

```json
{
  "workouts": [
    {
      "user_id": "a6fea8eb-402f-4578-96ba-189df1a8ca75",
      "user_key": "a6fea8eb-402f-4578-96ba-189df1a8ca75",
      "id": "12398c74-ea41-4d9c-a1b7-8c529ee67e46",
      "title": null,
      "timezone_offset": 3600,
      "average_hr": 147,
      "max_hr": 178,
      "distance": 31557.85,
      "time_start": "2022-07-29T12:05:49+00:00",
      "time_end": "2022-07-29T13:26:08+00:00",
      "calories": 729.0,
      "sport": {
        "id": 108,
        "name": "Road Biking",
        "slug": "road_biking"
      },
      "hr_zones": [
        5,
        76,
        288,
        1467,
        2148,
        835
      ],
      "moving_time": 4819,
      "total_elevation_gain": 374.0,
      "elev_high": null,
      "elev_low": null,
      "average_speed": 6.548,
      "max_speed": 17.448,
      "average_watts": null,
      "device_watts": null,
      "max_watts": null,
      "weighted_average_watts": null,
      "map": null,
      "provider_id": "9297103021",
      "source": {
        "name": "Garmin",
        "slug": "garmin",
        "logo": "https://storage.googleapis.com/vital-assets/garmin.png"
      }
    }
}
```

`Heartrate` on the other hand, is a timeseries resources. You can fetch it via `timeseries/<user_id>/heartrate` and looks like this:

```json
[
  {
    "timestamp": "2022-04-29T08:35:57+00:00",
    "timezone_offset": 3600,
    "value": 174.0,
    "type": null,
    "unit": "bpm"
  },
  {
    "timestamp": "2022-04-30T11:22:38+00:00",
    "timezone_offset": 3600,
    "value": 79.0,
    "type": null,
    "unit": "bpm"
  },
  {
    "timestamp": "2022-04-30T11:22:39+00:00",
    "timezone_offset": 3600,
    "value": 80.0,
    "type": null,
    "unit": "bpm"
  },
  {
    "timestamp": "2022-04-30T11:22:40+00:00",
    "timezone_offset": 3600,
    "value": 78.0,
    "type": null,
    "unit": "bpm"
  },
  {
    "timestamp": "2022-04-30T11:22:41+00:00",
    "timezone_offset": 3600,
    "value": 78.0,
    "type": null,
    "unit": "bpm"
  }
]
```

Different providers (e.g. Garmin), have different resources available. As an example, Garmin doesn't have `Glucose` as a resource.

## Fields by Provider

Resources alone are not the whole story. Depending on the provider, a field might not be available. For example both Garmin and Strava provide `Workouts`, yet the former doesn't have `ele_high` nor `ele_low`.

<Note>
  Providers mark with `*` means that Vital calculates the field's value. In some cases, they might came as `null`, since we weren't able to make the calculation.
</Note>

<Warning>
  Even if a field is available for a provider, it doesn't mean it's available. For example, Fitbit is capable of generating HRV data. However HRV data is only available for specific high-end devices. Another common scenario is Apple HealthKit data. If the user doesn't give permission to a particular field, it won't be available. **Be mindful of these situations and similar ones**.
</Warning>

### Activity

<iframe src="https://airtable.com/embed/shrD7PACtmC22z1am?backgroundColor=gray&layout=card" frameborder="0" allowfullscreen="true" width="100%" height="1200" loading="lazy">
  {" "}
</iframe>

### Body

<iframe src="https://airtable.com/embed/shrcmdPTp4rOx0mBp?backgroundColor=gray&layout=card" frameborder="0" allowfullscreen="true" width="100%" height="1200" loading="lazy">
  {" "}
</iframe>

### Sleep

<iframe src="https://airtable.com/embed/shr6TCkBRAtQMza6v?backgroundColor=gray&layout=card" frameborder="0" allowfullscreen="true" width="100%" height="1200" loading="lazy">
  {" "}
</iframe>

### Workout

<iframe src="https://airtable.com/embed/shrUXlA77h6Leg7tD?backgroundColor=gray&layout=card" frameborder="0" allowfullscreen="true" width="100%" height="1200" loading="lazy">
  {" "}
</iframe>


# Synthetic Data (Sandbox)
Source: https://docs.junction.com/wearables/providers/test_data

Using demo users to build and test your Vital integration

<Note>
  This feature is currently available for the following providers:

  * Apple Health Kit
  * Fitbit
  * Oura
  * Freestyle Libre

  The others will be coming soon. If there is a particular provider you would like us to add
  please do not hesitate to contact us at [support@tryvital.io](mailto:support@tryvital.io)!
</Note>

When integrating with Vital, you may not own a physical device for each provider you're planning to support. For this, we provide demo users with test data so you can build and test the whole integration without touching a real device.

A demo user gives you the same experience as using a real one, the only difference is that you won't go through the [Vital Link](/wearables/vital-link/introduction) flow.

<Warning>
  Demo users have certain limitations to keep in mind:

  * Only available in sandbox.
  * A demo user cannot have connections to a real device. If you already have a user with real data, you need to create a new one to connect a demo account.
  * There is no limitation on the number of demo users you can create, but they do count towards the overall users limit in sandbox. Up to date limits can be found [on this page](/home/environments).
  * Demo users expire after 7 days, meaning the user and its data will be deleted.
</Warning>

## Usage

First, you need a Vital user. You can create one either through the [dashboard](https://app.tryvital.io) or through the [API](/api-reference/user/create-user).

After creating the user, the `Users` page of your dashboard will look like this:

<img src="https://mintcdn.com/vital/img/test_data_dashboard_before_connection.png?maxW=2418&auto=format&n=nR1fvAlwouZ87zVb&q=85&s=4934cfc110677c45dea2704839d82c43" width={"100%"} width="2418" height="924" data-path="img/test_data_dashboard_before_connection.png" srcset="https://mintcdn.com/vital/img/test_data_dashboard_before_connection.png?w=280&maxW=2418&auto=format&n=nR1fvAlwouZ87zVb&q=85&s=d135d19c06f8f82dddbe96090bd47c8c 280w, https://mintcdn.com/vital/img/test_data_dashboard_before_connection.png?w=560&maxW=2418&auto=format&n=nR1fvAlwouZ87zVb&q=85&s=30a65c8ec19adab4cdeebeba42585f1a 560w, https://mintcdn.com/vital/img/test_data_dashboard_before_connection.png?w=840&maxW=2418&auto=format&n=nR1fvAlwouZ87zVb&q=85&s=3a1f3b9f8ebadb0a3da4458c237fc343 840w, https://mintcdn.com/vital/img/test_data_dashboard_before_connection.png?w=1100&maxW=2418&auto=format&n=nR1fvAlwouZ87zVb&q=85&s=a27a162fba66dca5f71429e0660f05d1 1100w, https://mintcdn.com/vital/img/test_data_dashboard_before_connection.png?w=1650&maxW=2418&auto=format&n=nR1fvAlwouZ87zVb&q=85&s=9079b62ef632ccb33d739b31579c99bd 1650w, https://mintcdn.com/vital/img/test_data_dashboard_before_connection.png?w=2500&maxW=2418&auto=format&n=nR1fvAlwouZ87zVb&q=85&s=8b48241125baf90c97e46032b73216f9 2500w" data-optimize="true" data-opv="2" />

Now you can create a demo connection for the Vital user you just created, in this case `150db84c-537c-4cad-a6e9-24dc589d7fa2`. You can directly hit the [API endpoint](/api-reference/link/link-demo-provider) or using one of our client libraries, as shown below:

<CodeGroup>
  ```bash Creating a demo connection
  curl --request POST \
       --url https://api.sandbox.tryvital.io/v2/link/connect/demo \
       --header 'Accept: application/json' \
       --header 'Content-Type: application/json' \
       --header 'x-vital-api-key: <your_api_key>' \
       --data '{"user_id": "<user_id>", "provider": "<provider>"}'
  ```

  ```javascript Node
  import { VitalClient, VitalEnvironment } from '@tryvital/vital-node';
  import { DemoConnectionCreationPayload, DemoProviders } from '@tryvital/vital-node/api';


  const client = new VitalClient({
      apiKey: '<my_api_key>',
      environment: VitalEnvironment.Sandbox,
  });

  const request: DemoConnectionCreationPayload = {
      userId: "<user_id>",
      provider: DemoProviders.<provider>,
  }
  const data = await client.link.connectDemoProvider(request);
  ```

  ```python Python
  from vital.client import Vital
  from vital.environment import VitalEnvironment

  client = Vital(
    api_key="YOUR_API_KEY",
    environment=VitalEnvironment.SANDBOX
  )

  data = client.link.connect_demo_provider(user_id="<user_id>", provider=DemoProviders.<provider>)
  ```

  ```java Java
  import com.vital.api.Vital;
  import com.vital.api.core.Environment;
  import com.vital.api.resources.link.requests.DemoConnectionCreationPayload;
  import com.vital.api.types.DemoProviders;

  Vital vital = Vital.builder()
          .apiKey("YOUR_API_KEY")
          .environment(Environment.SANDBOX)
          .build();

  DemoConnectionCreationPayload request = DemoConnectionCreationPayload
          .builder()
          .userId("<user_id>")
          .provider(DemoProviders.<provider>)
          .build();

  var data = vital.link().connectDemoProvider(request);
  ```

  ```go Go
  import (
    "context"

    vital "github.com/tryVital/vital-go"
    vitalclient "github.com/tryVital/vital-go/client"
    "github.com/tryVital/vital-go/option"
  )

  client := vitalclient.NewClient(
    option.WithApiKey("<YOUR_API_KEY>"),
    option.WithBaseURL(vital.Environments.Sandbox),
  )
  request := &vital.DemoConnectionCreationPayload{
    UserId:   "<user_id>",
    Provider: vital.DemoProviders<provider_name>,
  }

  response, err := client.Link.ConnectDemoProvider(context.TODO(), request)
  if err != nil {
    return err
  }
  fmt.Printf("Received data %s\n", response)
  ```
</CodeGroup>

After the demo connection is created, a Fitbit logo will appear beside your user.

<img src="https://mintcdn.com/vital/img/test_data_dashboard_after_connection.png?maxW=2418&auto=format&n=nR1fvAlwouZ87zVb&q=85&s=704c3d174609baed940b8522491fd526" width={"100%"} width="2418" height="924" data-path="img/test_data_dashboard_after_connection.png" srcset="https://mintcdn.com/vital/img/test_data_dashboard_after_connection.png?w=280&maxW=2418&auto=format&n=nR1fvAlwouZ87zVb&q=85&s=ad4e5ca7ce7a24f68f5e48e867f27396 280w, https://mintcdn.com/vital/img/test_data_dashboard_after_connection.png?w=560&maxW=2418&auto=format&n=nR1fvAlwouZ87zVb&q=85&s=94a62a47f5d8ff139baa3500cf2cc1fd 560w, https://mintcdn.com/vital/img/test_data_dashboard_after_connection.png?w=840&maxW=2418&auto=format&n=nR1fvAlwouZ87zVb&q=85&s=b9b4c3c68b66948f84eed3ad5c898638 840w, https://mintcdn.com/vital/img/test_data_dashboard_after_connection.png?w=1100&maxW=2418&auto=format&n=nR1fvAlwouZ87zVb&q=85&s=233f94e21d8cd55b1931ee185fcdb0cb 1100w, https://mintcdn.com/vital/img/test_data_dashboard_after_connection.png?w=1650&maxW=2418&auto=format&n=nR1fvAlwouZ87zVb&q=85&s=634ad33d1af77148c1f94811ec4eedb7 1650w, https://mintcdn.com/vital/img/test_data_dashboard_after_connection.png?w=2500&maxW=2418&auto=format&n=nR1fvAlwouZ87zVb&q=85&s=74f0c03eea3f48664d369fd11e898791 2500w" data-optimize="true" data-opv="2" />

From here, everything works exactly the same as if you connected a real device. This means you will receive the following webhook updates:

* [Connection created](/webhooks/data_flow#connection-created), as soon as the connection is created.
* [Historical webhooks](/webhooks/data_flow#historical-data-flow). We simulate historical data for the demo device and send the corresponding webhook updates, as in the real-world scenario.
* [Daily webhooks](/webhooks/data_flow#daily-data-flow). We also simulate updates to the device data every couple of hours so you can test receiving the data when a user recorded a workout or other activity.
* [Refresh user data](/api-reference/user/refresh-user-data). You can also instantaneously refresh a user's data through this endpoint.

## Backfill Data

For demo connections there will be 30 days of historic data backfilled. This is in contrast with data backfill for non demo providers,
where the number of days data backfilled varies according to the provider. You can find out more [here](/wearables/providers/introduction#historical-days-retrieved)

## Data Format

When connecting to the live Vital client, there are three data response structures available for data.
Raw, Stream and Summary

When connecting to the demo Vital client data is only available in the Summary structure.

Summary restructures provider data fields, to have a consistent response structure across all providers.
This is the easiest way to use provider data across an application which connects to multiple providers.


# Timestamps and Time Zones
Source: https://docs.junction.com/wearables/providers/timestamps-and-time-zones


## Timestamps

All Vital data timestamps are ISO 8601 formatted as follows:

| Providers                                                 | Time Basis                    | Pattern                                                                                           |
| --------------------------------------------------------- | ----------------------------- | ------------------------------------------------------------------------------------------------- |
| `abbott_libreview`<br />`freestyle_libre` <sup>\[1]</sup> | Floating Time <sup>\[2]</sup> | `YYYY-mm-ddTHH:mm:ss+00:00`<br />The `+00:00` TZ specifier should be **ignored** <sup>\[3]</sup>. |
| *Everyone else*                                           | UTC                           | `YYYY-mm-ddTHH:mm:ss+00:00`<br />Always specified as `+00:00` (UTC).                              |

<Info>
  <sup>\[1]</sup>
  `freestyle_libre` specific:
  Some older teams may see floating time data (Freestyle Libre) without the `+00:00` TZ specifier,
  as part of an earlier iteration of the feature. Contact Vital support if you wish to disable this
  behaviour, or if you intend to adopt the Vital backend SDKs.
</Info>

<Info>
  <sup>\[2]</sup> [Floating time](https://www.w3.org/International/wiki/FloatingTime) is not affixed to any time zone.
  This is not the same as time relative to a local time zone, i.e., a known UTC offset or geographical location.
</Info>

<Warning>
  <sup>\[3]</sup> Vital sends timestamps in floating time with `+00:00` for OpenAPI 3.x interoperability. OAS 3
  requires all timestamps to be [RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339), which in turn requires
  TZ specifier to be mandatory.

  When processing data from Freestyle Libre, you should [**reinterpret literally**](#data-point-in-floating-time-freestyle-libre)
  the date and time components as local date-time in the desired time zone. Do not convert from UTC/Zulu.
</Warning>

## Time Zones

Vital formats time zones in data as a *nullable* integer offset to UTC:

* A positive offset indicates east of UTC.
* A negative offset indicates west of UTC.
* `null` indicates the time zone information is absent.

Each provider has their own affinity of time zone information:

| Affinity                 | Time Basis    | Time Zone                                                                                                                                            |
| ------------------------ | ------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
| ✅                        | UTC           | The data comes with time zone information.                                                                                                           |
| User Fallback, or UTC    | UTC           | We assume the data were captured in the [User Fallback Time Zone](#user-fallback-time-zone). We fallback to UTC if the former is not set.            |
| User Fallback, or Absent | UTC           | We assume the data were captured in the [User Fallback Time Zone](#user-fallback-time-zone). Mark as no time zone (`null`) if the former is not set. |
| Inferred, or Absent      | UTC           | We infer the time zone from the data. Mark as no time zone (`null`) if the inferrence fails.                                                         |
| Absent                   | UTC           | We do not know the exact time zone the recording took place in. Mark as no time zone (`null`).                                                       |
| Floating Time            | Floating Time | We do not know the exact time zone the recording took place in. Mark as no time zone (`null`).                                                       |

### Cloud-based Providers

| Provider                                                                     | Activity Summary (Daily) | Session Summary (e.g. Sleep) | Timeseries Sample   | Remarks                                                        |
| ---------------------------------------------------------------------------- | ------------------------ | ---------------------------- | ------------------- | -------------------------------------------------------------- |
| [Freestyle Libre](https://www.freestylelibre.co.uk/libre/) `freestyle_libre` | *N/A*                    | *N/A*                        | Floating Time       |                                                                |
| [Abbott LibreView](https://www.libreview.com/) `abbott_libreview`            | *N/A*                    | *N/A*                        | Floating Time       |                                                                |
| [Fitbit](https://www.fitbit.com/global/uk/home)          `fitbit`            | ✅                        | ✅                            | ✅                   | ⚠️ [Time Zones](/wearables/guides/fitbit#time-zone-resolution) |
| [Garmin](https://www.garmin.com)                         `garmin`            | ✅                        | ✅                            | ✅                   |                                                                |
| [Google Fit](https://www.google.com/fit/)                `google_fit`        | User Fallback, or UTC    | User Fallback, or Absent     | Absent              |                                                                |
| [Oura](https://ouraring.com)                             `oura`              | ✅                        | ✅                            | ✅                   |                                                                |
| [Peloton](https://www.onepeloton.com)                    `peloton`           | *N/A*                    | ✅                            | *N/A*               |                                                                |
| [Strava](https://www.strava.com)                         `strava`            | *N/A*                    | ✅                            | ✅                   |                                                                |
| [Wahoo](https://wahoofitness.com)                        `wahoo`             | *N/A*                    | Absent                       | *N/A*               |                                                                |
| [WHOOP](https://www.whoop.com)                           `whoop_v2`          | ✅                        | ✅                            | *N/A*               |                                                                |
| [Zwift](https://zwift.com)                               `zwift`             | *N/A*                    | User Fallback, or Absent     | *N/A*               |                                                                |
| [Withings](https://www.withings.com)                     `withings`          | ✅                        | ✅                            | ✅                   |                                                                |
| [iHealth](https://ihealthlabs.com)                       `ihealth`           | *N/A*                    | ✅                            | Absent              |                                                                |
| [8Sleep](https://www.eightsleep.com)                     `eight_sleep`       | *N/A*                    | ✅                            | ✅                   |                                                                |
| [Hammerhead](https://www.hammerhead.io)                  `hammerhead`        | *N/A*                    | Inferred, or Absent          | Inferred, or Absent |                                                                |
| [Dexcom](https://www.dexcom.com)                         `dexcom_v3`         | *N/A*                    | *N/A*                        | ✅                   |                                                                |
| [Polar](https://www.polar.com)                           `polar`             | ✅                        | ✅                            | ✅                   |                                                                |
| [Kardia](https://kardia.com/)                            `kardia`            | *N/A*                    | *N/A*                        | ✅                   |                                                                |
| [Omron](https://www.omron-healthcare.com)                `omron`             | ✅                        | *N/A*                        | ✅                   |                                                                |

### SDK-based Providers

<Info>
  On-device data often do not capture the time zone at recording time.
  Vital SDK uses the device's current time zone as the fallback of closest approximation.
</Info>

| Provider                                                                                            | Activity Summary (Daily) | Session Summary | Timeseries Samples |
| --------------------------------------------------------------------------------------------------- | ------------------------ | --------------- | ------------------ |
| [Apple HealthKit](https://www.apple.com/uk/ios/health/)                       `apple_health_kit`    | ✅                        | ✅               | ✅                  |
| [Android Health Connect](https://developer.android.com/health-connect)        `health_connect`      | ✅                        | ✅               | ✅                  |
| [Omron](https://www.omron-healthcare.com)                                     `omron_ble`           | *N/A*                    | N/A             | ✅                  |
| [Contour](https://www.diabetes.ascensia.com)                                  `contour_ble`         | *N/A*                    | N/A             | ✅                  |
| [Accu-Chek](https://www.accu-chek.com)                                        `accuchek_ble`        | *N/A*                    | N/A             | ✅                  |
| [Freestyle Libre BLE](https://www.freestylelibre.co.uk/libre/)                `freestyle_libre_ble` | N/A                      | N/A             | ✅                  |

## Examples

### Data point with time zone offset

The data point was recorded on July 7, 2023 at 1:00 PM in UTC-07:00.

```json
{
  "source": {
    "provider": "apple_health_kit",
  },
  "data": [
    {
      "timestamp": "2023-07-07T20:00:00+00:00",
      "timezone_offset": -25200
    }
  ]
}
```

### Data point with no time zone offset (`null`)

The data point was timestamped to Aug 13, 2023 at 8:12 AM in UTC+00:00 (Zulu).
We do not know the exact time zone the recording took place in.

```json
{
  "source": {
    "provider": "apple_health_kit",
  },
  "data": [
    {
      "timestamp": "2023-08-13T08:12:00+00:00",
      "timezone_offset": null
    }
  ]
}
```

### Data point in floating time (Abbott Libreview & Freestyle Libre)

This Freestyle Libre data point was recorded on Sep 27, 2023 at 7:48 AM in floating time
(whichever time zone the user was in). We do not know the exact time zone the recording took place in.

You can display the date and time components literally to the user, e.g., `2023/09/27 07:48 AM`, as they
are relative to their perception of local time.

If you need to convert it to UTC for persistence, you need to pick a time zone based on your understanding
of the user. Then you should reinterpret the date and time components **literally** in said time zone.

For example, we knew that this example user is based in `America/New_York`. So we would interpret this data
point to be in `2023/09/27 07:48 AM ET`. We then finally convert this to UTC, resulting in `2023/09/27 11:48 AM UTC`.

```json
{
  "source": {
    "provider": "freestyle_libre",
  },
  "data": [
    {
      "timestamp": "2023-09-27T07:48:00+00:00",
      "timezone_offset": null
    }
  ]
}
```

## User Fallback Time Zone

Some providers neither expose nor even capture time zone information at source. So Vital can only request data and interpret them strictly in UTC.

If you prefer the data to be contextualize to the geographical location of a user, a Fallback Time Zone (denoted by an [IANA tz database identifier](https://data.iana.org/time-zones/tz-link.html))
can be specified on a per-user basis. Once specified, Vital would use the time zone to pull data and interpret timestamps from any time zone unware providers from that point onwards.

You can specify the Fallback Time Zone when:

* [Creating a new user](/api-reference/user/create-user); or
* [Patching an existing user](/api-reference/user/patch-user)

You will also get information about the source (by slug) and the last updated time of the Fallback Time Zone [when getting an existing user](/api-reference/user/get-user). Fallback Time Zone manually supplied via the REST API would always have a source slug of `manual`.

```json Example
{
  "user_id": "409d9870-21fb-443a-8daa-c5222659f40e",
  "team_id": "3aac677c-557f-40b7-9251-0315c1f48e77",
  "client_user_id": "d734e32e-dd43-4b77-ab56-692524279531",
  /** snipped **/
  "fallback_time_zone": {
    "id": "Europe/London",
    "source_slug": "manual",
    "updated_at": "2022-09-11T13:45:56+00:00"
  }
}
```


# Mobile SDK Authentication
Source: https://docs.junction.com/wearables/sdks/authentication


## Vital Sign-In Token

In the *Vital Sign-In Token* scheme, each mobile app installation signs in with Vital Mobile SDK
as an individual user in your Team. The app installation would be granted only Vital API access
scoped to that specific user.

Instead of hardcoding a [Vital API Key](#vital-api-keys), your app would request your own backend to generate
a **Vital Sign-In Token** for the user, through your own API authentication and authorization systems.

In this model, your Vital API Keys are kept strictly as a server-side secret.

<CardGroup cols={2}>
  <Card title="Persistence" icon="hand-wave">
    The signed-in user is persistent across app relaunch and device reboots.
  </Card>

  <Card title="Access Scope" icon="lock">
    Only user-level resources of the signed-in user can be accessed.
  </Card>
</CardGroup>

### Overview

<AccordionGroup>
  <Accordion title="Sign in once" icon="right-to-bracket" iconType="sharp-solid" defaultOpen>
    In typical circumstances, within each app installation, you would sign in your authenticated user only once
    with the Vital Mobile SDK. You would do so as part of your app's user lifecycle.

    There are some known circumstances where you would have to sign in the user again:

    * You have signed out your user in response to your app's user lifecycle changes; or
    * The Vital SDK sign-in state is out of sync with your app's user lifecycle; or
    * The SDK automatically signed out, because it had detected the deletion of the Vital User.

    <Note>
      It is unnecessary to request and sign-in with the Vital Sign-In Token every time your app launches.
    </Note>
  </Accordion>

  <Accordion title="Integrating into your app's user lifecycle" icon="arrows-spin" iconType="sharp-solid" defaultOpen>
    You should sign-in and sign-out of the Vital Mobile SDK as an integral part of your app's user lifecycle:

    1. When the user signs in to your app, you would request the Vital Sign-In Token from your backend, and then sign in with the Vital Mobile SDK.

    2. When the user signs out from your app, you would also sign out from the Vital Mobile SDK.

    Vital Mobile SDK persists the signed-in Vital User — as well as any settings and sync state — across app relaunches and device reboot.
  </Accordion>

  <Accordion title="A recommendation to perform regular reconciliation" icon="merge" iconType="sharp-solid" defaultOpen>
    We recommend regularly reconciling the state of the Vital Mobile SDK and your app's user lifecycle. This is because:

    1. The SDK sign-in process involves remote API calls, which can fail due to Internet connectivity;

    2. Unknown edge cases in your integration of Vital Core SDK into your app's user lifecycle may result in
       the state being out of sync; and

    3. If you are integrating Vital Mobile SDK into an existing production app, this reconciliation can serve
       as a one-off migration for app installations upgrading from an older version of your app.

    You can achieve this through the [Core SDK](/wearables/sdks/vital-core#core-sdk-status) API in three steps:

    1. Query the [Core SDK](/wearables/sdks/vital-core#core-sdk-status) Status and the Current User ID;
    2. Compare these against your app's user state; and
    3. Only if a discrepancy is detected, perform a Vital SDK sign-in or sign-out in accordance to the discrepancy.

    You would typically schedule this as an asynchronous task that spawns when your application process launches.

    <Warning>
      Do not sign in and sign out every time your application process launches.
    </Warning>
  </Accordion>

  <Accordion title="Technical details" icon="circle-info" iconType="sharp-solid" defaultOpen>
    **Vital Sign-In Token** is a short-lived bearer token issued for a specific Vital User.
    Vital Mobile SDK uses it to sign in with Vital's Identity Provider as the Vital User represented by the
    token.

    Each app installation can only have one active signed-in Vital User.

    Internally, the Vital Mobile SDK:

    1. **exchanges** the short-lived Vital Sign-In Token for a permanent sign-in, which is in the form of
       an OAuth 2.0 access token and an OAuth 2.0 refresh token.
    2. discards the Vital Sign-In Token upon a successful exchange.
    3. stores these token secrets securely in the device persistent storage.
    4. calls the Vital API using the OAuth 2.0 access token.
    5. transparently manages the OAuth 2.0 refresh token flow to keep the access token fresh and valid.

    This is why the documentation emphasizes the "sign in once" expectation. The SDK does not rely on
    the Vital Sign-In Token for day-to-day operation and API calls. It only needs this artifact once upfront
    to exchange for the token secrets it needs.
  </Accordion>
</AccordionGroup>

### Case Study: A typical Backend - Mobile App flow

<Steps>
  <Step title="Your app -> Your identity provider">
    ```mermaid
    sequenceDiagram
        participant Your App
        actor Your Identity Provider
        autonumber
        Your App->>Your Identity Provider: User authentication
        Your Identity Provider-->>Your App: Token Secret for authenticating to your Backend API
    ```

    Your end user signs in with your Identity Provider — a separate IdP, or your own API acting as one — through password authentication,
    Social Login, Single Sign-On (SSO) or any other authentication methods.
  </Step>

  <Step title="Your app -> Your backend API">
    ```mermaid
    sequenceDiagram
        participant Your App
        actor Your Backend
        autonumber
        Your App->>Your Backend: Request the user profile
        Your Backend-->>Your App: User profile
        Your App->>Your Backend: Request a Vital Sign-In Token for the user
    ```

    Once your user has successfully authenticated, your app is issued with token secrets for accessing your backend API.
    Your app stores these token secrets securely.

    It then makes some API requests to your backend API, in order to gather all information required to setup your app
    into an authenticated state.

    Among these API requests, one would be requesting your backend API to issue a Vital Sign-In Token for your authenticated user.
  </Step>

  <Step title="Your backend service <-> Vital API">
    ```mermaid
    sequenceDiagram
        actor Your Backend
        actor Vital API
        autonumber
        Your Backend->>Vital API: Token Request via API Key
        Vital API-->>Your Backend: Issued a Vital Sign-In Token
    ```

    Your backend API receives and validates the token issuance request. Once validated, your backend service:

    * Look up the Vital User associated with this authenticated user;

    * If one does not yet exist, call the [Create User](/api-reference/user/create-user) endpoint to create a Vital User; and

    * Call the [Create Sign-In Token](/api-reference/user/create-sign-in-token) endpoint to obtain a Vital Sign-In Token for
      this Vital user.

    <Note>
      Only this step would use a [Vital API Key](/api-details/authentication). Because this step happens in your
      backend service, this enables you to keep the Vital API Key strictly as a server-side secret.
    </Note>

    ```bash
    curl --request POST
      --url '{{BASE_URL}}/v2/user/{{USER_ID}}/sign_in_token'
      --header 'X-Vital-API-Key: <YOUR-API-KEY>'
    ```

    Your backend API then responds to your app with the obtained Vital Sign-In Token:

    ```json
    {
      "user_id": "e209947b-323e-4108-8e18-1518b80da0bd",
      "sign_in_token": "XYZ=="
    }
    ```
  </Step>

  <Step title="Your backend API -> Your app">
    ```mermaid
    sequenceDiagram
        participant Your App
        participant Vital Mobile SDK
        actor Your Backend
        autonumber
        Your Backend-->>Your App: The Vital Sign-In Token
        Your App->>Vital Mobile SDK: Sign in with Vital Sign-In Token
    ```

    Your app receives a response from your backend API, which includes the Vital Sign-In Token for the authenticated
    user.

    Your app then calls the Vital Mobile SDK `signIn` method with the Vital Sign-In Token:

    <CodeGroup>
      ```swift Native iOS
      import VitalCore

      let response: MyAPIResponse = // ....

      do {
        try await VitalClient.signIn(withRawToken: response.signInToken)

        print("Signed in with Vital successfully")
      } catch let error {
        print("Error signing in with Vital", error)
      }
      ```

      ```kotlin Native Android
      import io.tryvital.client.VitalClient
      import android.content.Context
      import android.util.Log

      val response: MyAPIResponse
      val applicationContext: Context

      try {
        VitalClient.signIn(applicationContext, response.signInToken)

        Log.i("vital_sdk", "Signed in with Vital successfully")
      } catch (e: Throwable) {
        Log.e("vital_sdk", "Error signing in with Vital", e)
      }
      ```

      ```typescript React Native
      import { VitalCore } from "@tryvital/vital-core-react-native";

      const response: MyAPIResponse

      do {
        await VitalCore.signIn(response.signInToken)

        console.log("Signed in with Vital successfully")
      } catch let error {
        console.error("Error signing in with Vital", error)
      }
      ```

      ```dart Flutter
      import 'package:vital_core/vital_core.dart' as vital_core;

      MyAPIResponse response;

      try {
        await vital_core.signIn(response.signInToken)

        Fimble.i("Signed in with Vital successfully")
      } catch (error) {
        Fimble.e("Error signing in with Vital", error)
      }
      ```
    </CodeGroup>

    <br />

    <Warning>
      `signIn()` throws an error when you have already signed in with the Vital SDK.

      You can [inspect the Core SDK status](/wearables/sdks/vital-core#core-sdk-status) at any time for troubleshooting. You can
      also rely on the Core SDK status to reconcile differences between your own user session state and Vital SDK sign-in.
    </Warning>
  </Step>

  <Step title="Voila!">
    The Vital Mobile SDK is now signed-in with the Vital User associated with your authenticated user.
    You can now proceed to use all the Vital SDK features.
  </Step>
</Steps>

## Vital API Keys

<Warning>
  API Key is **discouraged** for production mobile apps, since it would be distributed as cleartext.
  API Key support is intended only for customer early evaluation in Sandbox.

  Use [Vital Sign-In Token](#vital-sign-in-token) whenever possible.
</Warning>

Vital Mobile SDK can be configured to authenticate using API Key alongside a target user ID.

<CodeGroup>
  ```swift Native iOS
  import VitalCore

  VitalClient.configure(
    apiKey: "sk_us_...",
    environment: .sandbox(.us)
  )
  VitalClient.setUserId(UUID(uuidString: "ccd6f98d-3a2a-433b-a114-8fe064f301ed")!)
  ```

  ```kotlin Native Android
  import io.tryvital.client.VitalClient
  import android.content.Context

  val applicationContext: Context

  VitalClient.configure(
    applicationContext,
    Region.US,
    Environment.Sandbox,
    "sk_us_..."
  )
  VitalClient.setUserId(applicationContext, "ccd6f98d-3a2a-433b-a114-8fe064f301ed")
  ```

  ```typescript React Native
  import { VitalCore } from "@tryvital/vital-core-react-native";

  await VitalCore.configure(
      "sk_us_...",
      "sandbox",
      "us",
      true,
  );
  await VitalCore.setUserId("ccd6f98d-3a2a-433b-a114-8fe064f301ed");
  ```

  ```dart Flutter
  import 'package:vital_core/vital_core.dart' as vital_core;

  await vital_core.configure(
    "sk_us_...",
    vital_core.Environment.sandbox,
    vital_core.Region.us
  );
  await vital_core.setUserId("ccd6f98d-3a2a-433b-a114-8fe064f301ed");
  ```
</CodeGroup>

<br />

<Info>
  When running on iOS, the SDK must be **explicitly** configured before other SDK methods can be invoked.

  Alternatively, follow the [Apple HealthKit guide](https://docs.tryvital.io/wearables/guides/apple-healthkit#2-integrate-with-ios-system-callbacks)
  to enable SDK Automatic Configuration during app launch. This auto-configures the SDK using the last known configuration you supplied — including but
  not limited to the API Key, the environment and the target User ID. Not only is this a prerequisite to enable HealthKit Background Delivery, this
  allows you also to only call `configure(...)` and `setUserId(...)` once to "sign-in" the user persistently when using the Vital API Key scheme.
</Info>

## Sign Out

Regardless of the authentication scheme you used, you can sign out with the Vital SDK using `signOut()`.
This erases any persistent user session and configuration stored by the Vital Core and Health SDKs.

<CodeGroup>
  ```swift Native iOS
  import VitalCore

  await VitalClient.shared.signOut()
  ```

  ```kotlin Native Android
  import io.tryvital.client.VitalClient
  import android.content.Context

  val applicationContext: Context

  VitalClient.getOrCreate(applicationContext).signOut()
  ```

  ```typescript React Native
  import { VitalCore } from "@tryvital/vital-core-react-native";

  await VitalCore.signOut();
  ```

  ```dart Flutter
  import 'package:vital_core/vital_core.dart' as vital_core;

  await vital_core.signOut();
  ```
</CodeGroup>

## Migrate from Vital API Keys to Vital Sign-In Tokens

<Warning>
  Always use [Vital Sign-In Token](#vital-sign-in-tokens) for your production mobile apps.
</Warning>

An existing app installation signed-in with Vital API Key + User ID can be seamlessly migrated to
use Vital Sign-In Tokens.

It is as simple as performing a one-off migration logic during app launch:

<Steps>
  <Step title="Condition to migrate">
    Check whether the Vital SDK status includes `useApiKey` (i.e., the user is signed in using Vital API Key).
  </Step>

  <Step title="Obtain a Vital Sign-In Token">
    Similar to the new user sign-in flow, your app needs to obtain a Vital Sign-In Token through your backend service.
  </Step>

  <Step title="Sign-in with the token">
    Your app can simply sign-in with the Vital Sign-In Token.

    Note that it is **unnecessary to reset** the SDK beforehand — the SDK `signIn` method would automatically migrate, as
    long as the supplied Sign-In Token is compatible with the existing API Key sign-in (i.e., having the same Vital user ID,
    same Vital environment, and same Vital region).
  </Step>
</Steps>

<CodeGroup>
  ```swift Native iOS
  import VitalCore

  if VitalClient.status.contains(.useApiKey) {
    do {
      let response = await callBackend(...)
      try await VitalClient.signIn(withToken: response.signInToken)
    }

      print("Signed in with Vital successfully")
    } catch let error {
      print("Error signing in with Vital", error)
    }
  }
  ```

  ```kotlin Native Android
  import io.tryvital.client.VitalClient
  import android.content.Context
  import android.util.Log

  val applicationContext: Context

  VitalClient.getOrCreate(applicationContext)

  if (VitalClient.Status.useApiKey in VitalClient.status) {
    try {
        val response = callBackend(...)
        VitalClient.signIn(applicationContext, response.signInToken)

        Log.i("vital_sdk", "Signed in with Vital successfully")
    } catch (e: Throwable) {
        Log.e("vital_sdk", "Error signing in with Vital", e)
    }
  }
  ```

  ```typescript React Native
  import { VitalCore } from "@tryvital/vital-core-react-native";

  const status = await VitalCore.status();

  if (status.includes("useApiKey")) {
    do {
        const response = await callBackend(...);
        await VitalCore.signIn(response.signInToken);

        console.log("Signed in with Vital successfully");
    } catch let error {
        console.error("Error signing in with Vital", error);
    }
  }
  ```

  ```dart Flutter
  import 'package:vital_core/vital_core.dart' as vital_core;

  Set<vital_core.ClientStatus> status = await vital_core.clientStatus();

  if (status.contains(vital_core.ClientStatus.useApiKey)) {
    try {
        MyAPIResponse response = await callBackend(...);
        await vital_core.signIn(response.signInToken)

        Fimble.i("Signed in with Vital successfully")
    } catch (error) {
        Fimble.e("Error signing in with Vital", error)
    }
  }
  ```
</CodeGroup>


# Installation
Source: https://docs.junction.com/wearables/sdks/installation


## Project requirements

### iOS

<Info>Applies also to Flutter and React Native projects.</Info>

| Parameter                 | Requirement |
| ------------------------- | ----------- |
| Minimum deployment target | iOS 14.0    |

<Note>
  If you are integrating on React Native or Flutter, or integrating on Native iOS via CocoaPods,
  make sure you have updated the minimum iOS deployment target in:

  * your `Podfile`; and
  * your iOS App Target.

  ```diff Podfile
  # e.g., React Native default
  -platform :ios, min_ios_version_supported

  # Set minimum deployment target to be iOS 14.0.
  +platform :ios, '14.0'
  ```
</Note>

### Android

<Info>Applies also to Flutter and React Native projects.</Info>

| Parameter                     | Requirement     |
| ----------------------------- | --------------- |
| Minimum SDK Level             | 26              |
| Compile SDK Level             | 34              |
| Kotlin compiler version       | 1.8.22 or above |
| Android Gradle Plugin version | 8.2.0 or above  |
| Gradle version                | 8.2.0 or above  |

### Flutter

| Parameter   | Requirement   |
| ----------- | ------------- |
| Flutter SDK | 3.13 or above |

### React Native

| Parameter         | Requirement     |
| ----------------- | --------------- |
| React Native Core | 0.72.0 or above |
| Node.js           | 18.0 or above   |

## Setup package dependencies

## iOS

Vital Mobile SDKs are available through both Swift Package Manager and CocoaPods.

### Swift Package Manager

Add the vital-ios package (`https://github.com/tryVital/vital-ios`) as a dependency of your project.

Link `VitalHealthKit` and `VitalDevices` as appropriate. Note that `VitalCore` is mandatory.

<iframe src="https://www.loom.com/embed/fa091653aab24feeb52253a584c69512" frameborder="0" allowfullscreen="true" width="100%" height="533" loading="lazy">
  {" "}
</iframe>

### CocoaPods

Add the following declarations to your app target in your Podfile:

```ruby
pod 'VitalCore'
pod 'VitalDevices'
pod 'VitalHealthKit'
```

## Android

Make sure Maven Central is included in the list of repositories in your `build.gradle`.

```groovy
repositories {
  mavenCentral()
}
```

Then include our Android SDK artifacts as dependencies of your modules as needed:

```groovy
def vital_version = '3.2.1'

implementation 'io.tryvital:vital-client:$vital_version'
implementation 'io.tryvital:vital-health-connect:$vital_version'
implementation 'io.tryvital:vital-devices:$vital_version'
```

## React Native

Install Vital SDK packages through NPM or Yarn:

```commandline
npm install @tryvital/vital-core-react-native
npm install @tryvital/vital-health-react-native
npm install @tryvital/vital-devices-react-native
```

Pull all dependencies for your React Native iOS project:

```commandline
cd ios
pod install
```

<Info>
  `pod install` on your iOS project might error due to version lock conflicts on the Vital iOS libraries.
  This usually happens after you have bumped the React Native SDK package versions.

  Use `pod update` to resolve the conflict:

  ```commandline
  pod update VitalCore VitalDevices VitalHealthKit --repo-update
  ```
</Info>

## Flutter

Add Vital SDK packages to your `pubspec.yaml`:

```yaml
dependencies:
  vital_core: ^3.1.1
  vital_health: ^3.1.1
  vital_devices: ^3.1.1
```

<Info>
  `pod install` on your iOS project might error due to version lock conflicts on the Vital iOS libraries.
  This usually happens after you have bumped the Flutter SDK package versions.

  Use `pod update` to resolve the conflict:

  ```commandline
  pod update VitalCore VitalDevices VitalHealthKit --repo-update
  ```
</Info>


# Vital Core SDK
Source: https://docs.junction.com/wearables/sdks/vital-core


## Overview

Check out the [SDK Authentication guide](/wearables/sdks/authentication) on the available SDK authentication
schemes, and how to authenticate with the Vital Mobile SDK.

<Card title="Mobile SDK Authentication" icon="id-card" href="/wearables/sdks/authentication" horizontal>
  Learn how to authenticate your mobile app user with Vital Mobile SDK.
</Card>

## Accessing Vital API

You can access Vital API through `VitalClient` with typed request methods and response models.

<CodeGroup>
  ```swift Native iOS
  // e.g. Link Service
  let linkService = VitalClient.shared.link
  ```

  ```kotlin Native Android
  // e.g. Link Service
  val linkService = VitalClient.getOrCreate(context).linkService
  ```

  ```dart Flutter
  import 'package:vital_core/vital_core.dart' as vital_core;

  vital_core.VitalClient client;

  // For customers using Vital API Keys for early evaluation.
  client = vital_core.VitalClient()
    ..init(region: Region.eu, environment: Environment.sandbox, apiKey: 'sk_eu_...');

  // For customers using the Vital Sign-In Tokens scheme
  client = vital_core.VitalClient.forSignedInUser(environment: Environment.sandbox, region: Region.eu);

  // e.g. Link Service
  final linkService = client.linkService;
  ```
</CodeGroup>

<br />

<Info>Typed API access is not yet available in React Native.</Info>

## Generating Vital Link URL

You can obtain an URL to the Vital Link Widget through `VitalClient.linkWidgetUrl`. Note that the URL contains
a short-lived token with 10-minute expiry.

For the `redirectUrl`, you should set it to a URL with a custom URL scheme which your app would register to handle.

<CodeGroup>
  ```swift Native iOS
  let widgetUrl = await VitalClient.shared.link.createProviderLink(
    redirectURL: "x-vital-app://"
  )
  ```

  ```dart Flutter
  Uri widgetUrl = await client.linkWidgetUrl(redirectUrl: "x-vital-app://");
  ```
</CodeGroup>

## Core SDK Status

You can inspect the status of the Core SDK for troubleshooting, as well as for your own business logic.
For example, you may reconcile your user session and the Vital SDK sign-in based on the Core SDK status.

The SDK normally reports one of the following status combinations:

| Combinations                                | Auth Scheme         | Remarks                                                                       |
| ------------------------------------------- | ------------------- | ----------------------------------------------------------------------------- |
| *Empty*                                     | N/A                 | The SDK has neither been configured nor an active sign-in.                    |
| `Configured`                                | API Key             | The SDK has been configured, but does not have an active sign-in.             |
| `Configured`, `SignedIn` & `UseApiKey`      | API Key             | The active sign-in was done by setting an API Key and a target Vital User ID. |
| `Configured`, `SignedIn` & `UseSignInToken` | Vital Sign-In Token | The active sign-in was done by consuming a Vital Sign-In Token.               |

### Get the current status

<CodeGroup>
  ```swift Native iOS
  import VitalCore

  let status: VitalClient.Status = VitalClient.status
  ```

  ```kotlin Native Android
  import io.tryvital.client.VitalClient
  import android.content.Context

  val applicationContext: Context

  VitalClient.getOrCreate(applicationContext)
  val status = VitalClient.status
  ```

  ```typescript React Native
  import { VitalCore } from "@tryvital/vital-core-react-native";

  await VitalCore.status();
  ```

  ```dart Flutter
  import 'package:vital_core/vital_core.dart' as vital_core;

  await vital_core.clientStatus();
  ```
</CodeGroup>

### Observe status changes over time

<CodeGroup>
  ```swift Native iOS
  import VitalCore

  // Combine Publisher
  let cancellable = VitalClient.statusDidChange.sink { _ in }

  // AsyncStream
  Task {
    for status in VitalClient.statuses {
      // ...
    }
  }
  ```

  ```kotlin Native Android
  import io.tryvital.client.VitalClient
  import android.content.Context

  val applicationContext: Context

  val statuses: Flow<Set<VitalClient.Status>>
  statuses = VitalClient.statuses(applicationContext)

  val job = statuses
    .onEach { /** ... **/ }
    .launchIn(...)
  ```

  ```typescript React Native
  import { VitalCore } from "@tryvital/vital-core-react-native";

  VitalCore.observeStatusChange((statuses) => {
    // ...
  });
  ```

  ```dart Flutter
  import 'package:vital_core/vital_core.dart' as vital_core;

  // NOTE: This stream does not yield the current statuses on listen.
  Stream<Set<ClientStatus>> statuses;
  statuses = vital_core.clientStatusStream;
  ```
</CodeGroup>

## Get Current Vital User ID

Aside from the Core SDK Status, you can also query the Vital User ID of the signed-in user:

<CodeGroup>
  ```swift Native iOS
  import VitalCore

  let userId: String? = VitalClient.currentUserId
  ```

  ```kotlin Native Android
  import io.tryvital.client.VitalClient
  import android.content.Context

  val applicationContext: Context

  VitalClient.getOrCreate(applicationContext)
  val userId = VitalClient.currentUserId
  ```

  ```typescript React Native
  import { VitalCore } from "@tryvital/vital-core-react-native";

  const userId = await VitalCore.currentUserId();
  ```

  ```dart Flutter
  import 'package:vital_core/vital_core.dart' as vital_core;

  final userId = await vital_core.currentUserId();
  ```
</CodeGroup>

## Reset the SDK (Sign Out)

Refer to [the Sign Out section in the SDK Authentication guide](/wearables/sdks/authentication#sign-out).

## Verbose Logging to Console/Logcat

You can enable verbose logging to have a deeper look into how Vital Mobile SDK is reacting to your calls, as well as
all the automatic behaviours that the SDK is performing in background.

To avoid any missing log entry, you should enable verbose logging as early as possible — preferably before any usage of
any Vital Mobile SDKs.

<Note>
  On Android, verbose logging is enabled by default when running as a debuggable build
  (i.e., with `ApplicationInfo.FLAG_DEBUGGABLE`).
</Note>

<CodeGroup>
  ```swift Native iOS (Swift)
  import VitalCore

  class AppDelegate: NSObject, UIApplicationDelegate {
    func application(
      _ application: UIApplication,
      didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey : Any]? = nil
    ) -> Bool {

      VitalLogger.stdOutEnabled = true

      // ...

      return true
    }
  }
  ```

  ```objc Native iOS (Objective-C)
  #import "AppDelegate.h"

  @import VitalCore

  - (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {

    VitalLoggerObjC.stdOutEnabled = YES;

    // ...

    return YES;
  }
  ```

  ```kotlin Native Android
  import io.tryvital.client.utils.VitalLogger

  VitalLogger.getOrCreate().enabled = true
  ```
</CodeGroup>


# Vital Devices SDK
Source: https://docs.junction.com/wearables/sdks/vital-devices


## Prerequisites

Your app project must declare the required permission usage. This applies equally to both native,
Flutter and React Native app projects.

<AccordionGroup>
  <Accordion title="iOS projects">
    Add the following to your `Info.plist` file:

    ```xml
    <key>NSBluetoothAlwaysUsageDescription</key>
    <string>Our app uses bluetooth to find, connect and transfer data between different devices</string>
    ```

    Bluetooth permission on iOS is automatically requested on the first scanning attempt.
  </Accordion>

  <Accordion title="Android projects">
    Add the following to your `AndroidManifest.xml`:

    ```xml
    <uses-permission android:name="android.permission.BLUETOOTH_SCAN" android:usesPermissionFlags="neverForLocation"/>
    <uses-permission android:name="android.permission.BLUETOOTH_CONNECT"/>

    <!-- Request legacy Bluetooth permissions on older devices. -->
    <uses-permission android:name="android.permission.BLUETOOTH" android:maxSdkVersion="30"/>
    <uses-permission android:name="android.permission.BLUETOOTH_ADMIN" android:maxSdkVersion="30"/>
    <uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" android:maxSdkVersion="30"/>
    ```

    You will have to request the appropriate permissions at in your app before you can call the Vital Devices SDK.
  </Accordion>
</AccordionGroup>

## Bluetooth devices

### Choose Device Model

The SDK provides a list of supported Bluetooth devices. Select the matching instance to prepare for scanning.

<CodeGroup>
  ```swift Native iOS
  import VitalDevices

  let devicesManager = DevicesManager()

  /// Get the brands
  let brands = DevicesManager.brands()

  /// Each brand has devices
  let devices = DevicesManager.devices(for: brands[0])
  ```

  ```kotlin Native Android
  import io.tryvital.vitaldevices.*

  val deviceManager = VitalDeviceManager.create(context)

  val deviceModels = devices(Brand.AccuChek)
  val deviceModel = deviceModels[0]
  ```

  ```typescript React Native
  import { VitalDevicesManager } from "@tryvital/vital-devices-react-native";

  const devicesManager = new VitalDevicesManager();

  let deviceModels = VitalDevicesManager.supportedDevices;
  let deviceModel = deviceModels[0];
  ```

  ```dart Flutter
  import 'package:vital_devices/vital_devices.dart';

  final deviceManager = DeviceManager();

  final deviceModels = await deviceManager.getDevices(Brand.accuChek);
  final deviceModel = deviceModels[0];
  ```
</CodeGroup>

### Scanning for devices

First you have to scan for one of the supported devices.

<CodeGroup>
  ```swift Native iOS
  let cancellable = devicesManager
    .search(for: state.device)
    .sink { scannedDevice in
      print("Discovered: \(scannedDevice)")
    }

  // Stop scanning
  cancellable.cancel()
  ```

  ```kotlin Native Android
  val job = deviceManager
    .search(deviceModel)
    .catch {
        Log.i("Devices", "Error scanning ${it.message}", it.cause)
    }
    .onEach { scannedDevice ->
        Log.i("Devices", "Discovered ${scannedDevice}")
    }
    .launchIn(Dispatchers.Main)

  // Stop scanning
  job.cancel()
  ```

  ```typescript React Native
  let scanner = deviceManager.scanForDevice(deviceModel, {
      onDiscovered: (device) => {
          console.log("Discovered: " + device)
      },
      onError: (error) => console.log(error)
  })

  // Stop scanning
  scanner.cancel()
  ```

  ```dart Flutter
  deviceManager.scanForDevices(deviceModel).listen((newDevice) {
    Fimber.i("Discovered: $newDevice");
  });

  // Stop scanning
  await deviceManager.stopScan();
  ```
</CodeGroup>

Depending on the type of device you are connecting to, you will have to call different methods to connect to it.

### Blood Pressure Monitor

<CodeGroup>
  ```swift Native iOS
  let scannedDevice: ScannedDevice
  let reader = deviceManager.bloodPressureReader(for: scannedDevice)

  reader.read(device: scannedDevice).sink { samples in
    print("Read samples: \(samples)")
  }
  ```

  ```kotlin Native Android
  val scannedDevice: ScannedDevice

  val samples = deviceManager.bloodPressure(context, scannedDevice).read()
  ```

  ```typescript React Native
  let scannedDevice: ScannedDevice

  let samples = await devicesManager.readBloodPressure(scannedDevice.id)
  ```

  ```dart Flutter
  List<BloodPressureSample> bloodPressureSamples;
  bloodPressureSamples = await deviceManager.readBloodPressureData(scannedDevice);
  ```
</CodeGroup>

### Glucose Meter

<CodeGroup>
  ```swift Native iOS
  let scannedDevice: ScannedDevice
  let reader = deviceManager.glucoseMeter(for: scannedDevice)

  reader.read(device: scannedDevice).sink { samples in
    print("Read samples: \(samples)")
  }
  ```

  ```kotlin Native Android
  val scannedDevice: ScannedDevice

  val samples = deviceManager.glucoseMeter(context, scannedDevice).read()
  ```

  ```typescript React Native
  let scannedDevice: ScannedDevice

  let samples = await devicesManager.readGlucoseMeter(scannedDevice.id)
  ```

  ```dart Flutter
  List<QuantitySample> glucoseSamples;
  glucoseSamples = await deviceManager.readGlucoseMeterData(scannedDevice);
  ```
</CodeGroup>

After you have received samples depending on the type of device you might need to star scanning again to receive the
next set of samples.

## Freestyle Libre 1

<Warning>
  Readings taken with the SDK are not guaranteed to match the official Freestyle
  Libre app. This mismatch happens due to the algorithm difference used by us,
  compared to the official Freestyle Libre.
</Warning>

We currently support Libre 1 sensors via NFC readings. Please make sure you add NFC capabilities in your app:

<img src="https://mintcdn.com/vital/img/iOS/nfc_permission.png?maxW=662&auto=format&n=nR1fvAlwouZ87zVb&q=85&s=cf03d154eda0b2394c41d2b5c48794dd" width="662" height="525" data-path="img/iOS/nfc_permission.png" srcset="https://mintcdn.com/vital/img/iOS/nfc_permission.png?w=280&maxW=662&auto=format&n=nR1fvAlwouZ87zVb&q=85&s=fb31d11db65c544d1ef767e6e51042ce 280w, https://mintcdn.com/vital/img/iOS/nfc_permission.png?w=560&maxW=662&auto=format&n=nR1fvAlwouZ87zVb&q=85&s=93a0e8c158cb76ef49cae4262bdd8f63 560w, https://mintcdn.com/vital/img/iOS/nfc_permission.png?w=840&maxW=662&auto=format&n=nR1fvAlwouZ87zVb&q=85&s=46a3d5833cd72e4aabf54127d548f615 840w, https://mintcdn.com/vital/img/iOS/nfc_permission.png?w=1100&maxW=662&auto=format&n=nR1fvAlwouZ87zVb&q=85&s=b2d6b6a4dc4d78c94cb31736eb95b12a 1100w, https://mintcdn.com/vital/img/iOS/nfc_permission.png?w=1650&maxW=662&auto=format&n=nR1fvAlwouZ87zVb&q=85&s=6209d93d3640b1a9290eda7f4d7b3601 1650w, https://mintcdn.com/vital/img/iOS/nfc_permission.png?w=2500&maxW=662&auto=format&n=nR1fvAlwouZ87zVb&q=85&s=1d8254354c97ba63af800c89c08e2123 2500w" data-optimize="true" data-opv="2" />

Also add the key `NFCReaderUsageDescription` in your info.plist. This key should explain why your app needs to use NFC.

To use the reader:

<CodeGroup>
  ```swift Native iOS
  let reader = Libre1Reader(
      readingMessage: "Ready for reading",
      errorMessage: "Failed reading from sensor",
      completionMessage: "Completed successfully!",
      queue: mainQueue
  )

  let reading = try await reader.read()
  ```

  ```kotlin Native Android
  import android.app.Activity
  import io.tryvital.vitaldevices.devices.Libre1Reader

  let currentActivity: Activity

  val reading = Libre1Reader.create(currentActivity).read()
  ```

  ```typescript React Native
  import { VitalDevicesManager } from "@tryvital/vital-devices-react-native";

  let devicesManager: VitalDeviceManager

  let result = await devicesManager.readLibre1("reading", "errored", "completed")
  ```
</CodeGroup>

`read()` returns a result object with two fields:

1. the sensor information; and
2. a list of glucose samples.

## Upload device samples to Vital

<Note>
  This automatic behaviour is available since Vital iOS 1.0.0, Vital Android 3.0.0, Vital Flutter SDK 4.0.0
  and Vital React Native 4.0.0.
</Note>

Vital Devices SDK automatically uploads any blood pressure and glucose samples discovered during
the read operation, provided that the Vital Core SDK [has a signed-in user](/wearables/sdks/vital-core#core-sdk-status).

The SDK does not currently buffer samples that fail to upload. You might want to ensure that the
device has Internet connectivity before initiating the read operation.


# Vital Health SDK
Source: https://docs.junction.com/wearables/sdks/vital-health


## Overview

<Note>
  Make sure you have successfully integrated with a Vital Mobile SDK authentication scheme, before you proceed
  to try out Vital Health SDK.

  <Card title="Mobile SDK Authentication" icon="id-card" href="/wearables/sdks/authentication" horizontal>
    Learn how to authenticate your mobile app user with Vital Mobile SDK.
  </Card>
</Note>

This Vital Health SDK guidance page focuses on the inital setup and API usage of the Health SDK that is common to both
the Apple HealthKit and Android Health Connect integration.

Please consult the following guides on requirements and restrictions of Apple HealthKit and Android Health Connect:

<Card title="Apple HealthKit" icon="apple" href="/wearables/guides/apple-healthkit" horizontal>
  Learn how to integrate with Apple HealthKit through Vital Mobile SDKs, available in
  Native iOS, React Native and Flutter.
</Card>

<Card title="Android Health Connect" icon="android" href="/wearables/guides/android-health-connect" horizontal>
  Learn how to integrate with Android Health Connect through Vital Mobile SDKs, available in
  Native Android, React Native and Flutter.
</Card>

## Initial Setup

### iOS apps: Configure your App Delegate

This section applies to:

* 🔘 Native iOS apps
* 🔘 React Native iOS apps

This section does not apply to:

* ❌ Fluter iOS apps (using Vital Flutter SDK 4.3.8 or later).

<Note>
  Vital **Flutter** SDK (4.3.8 and later) automatically integrates with your App Delegate through the Flutter Plugin machinery.
  You need not manual edit your AppDelegate in **Flutter** iOS projects.
</Note>

<Warning>
  You must configure your App Delegate as instructed if you use Vital Health SDK on iOS. Not doing so
  may result in missing background delivery, or app process termination by the operating system.
</Warning>

In your AppDelegate's `application(_:didFinishLaunchingWithOptions:)` implementation, it **must** call Vital Health SDK
`automaticConfiguration()` synchronously before it returns.

<Accordion title="Details" icon="apple" defaultOpen>
  Vital needs to register various handlers with the system frameworks like Apple HealthKit and BackgroundTasks. These frameworks
  require said registrations to be completed **before** the "app finished launching" moment [\[1\]](https://developer.apple.com/documentation/healthkit/hkhealthstore/1614175-enablebackgrounddelivery#3801028)
  [\[2\]](https://developer.apple.com/documentation/backgroundtasks/bgtaskscheduler/register\(fortaskwithidentifier:using:launchhandler:\)#Discussion).

  For React Native apps, the AppDelegate is part of the template Swift or Objective-C code in your generated Xcode project.

  <CodeGroup>
    ```swift Swift
    import VitalHealthKit

    class AppDelegate: NSObject, UIApplicationDelegate {
      func application(
        _ application: UIApplication,
        didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey : Any]? = nil
      ) -> Bool {

        VitalHealthKitClient.automaticConfiguration()

        // ...

        return true
      }
    }
    ```

    ```objc Objective-C / React Native
    #import "AppDelegate.h"
    #import "VitalHealthKitConfiguration.h"

    - (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {

      [VitalHealthKitConfiguration automaticConfiguration];

      // ...

      return YES;
    }
    ```
  </CodeGroup>
</Accordion>

### Configure the Vital Health SDK

The Health SDK must be configured before use. The configuration is persistent, so
you can do this only once, immediately after [a successful authentication with the Core SDK](/wearables/sdks/authentication).

<CodeGroup>
  ```swift Native iOS
  import VitalHealthKit

  VitalHealthKitClient.configure(
    backgroundDeliveryEnabled: true
  )
  ```

  ```kotlin Native Android
  import io.tryvital.vitalhealthconnect.VitalHealthConnectManager

  val manager = VitalHealthConnectManager.configure(context)
  manager.configureHealthConnectClient(
    syncNotificationBuilder = null
  )
  ```

  ```typescript React Native
  import { VitalHealth, HealthConfig } from "@tryvital/vital-health-react-native";

  let config = new HealthConfig();
  config.iOSConfig.backgroundDeliveryEnabled = true;
  await VitalHealth.configure(config);
  ```

  ```dart Flutter
  import 'package:vital_health/vital_health.dart' as vital_health;

  await vital_health.configure(
    config: const vital_health.HealthConfig(
      iosConfig: vital_health.IosHealthConfig(
        backgroundDeliveryEnabled: true,
      ),
    ),
  );
  ```
</CodeGroup>

## Health Data Permissions

### Ask user for health data permissions

Before the SDK can read any data, you need to ask the end user to grant health data permissions.

<CodeGroup>
  ```swift Native iOS
  import VitalHealthKit

  await VitalHealthKitClient.shared.ask(
    readPermissions: [.activity, .workout, .sleep],
    writePermissions: []
  )
  ```

  ```kotlin Native Android

  //
  // Android Compose
  //

  import androidx.activity.compose.rememberLauncherForActivityResult
  import androidx.compose.runtime.rememberCoroutineScope
  import androidx.compose.material3.*
  import io.tryvital.vitalhealthconnect.VitalHealthConnectManager

  val manager: VitalHealthConnectManager = ...
  val contract = manager.createPermissionRequestContract(
    readResources = set(
      VitalResource.Activity,
      VitalResource.Workout,
      VitalResource.Sleep,
    ),
    writeResources = emptySet(),
  )

  val coroutineScope = rememberCoroutineScope()
  val permissionsLauncher = rememberLauncherForActivityResult(contract) { outcomeAsync ->
    coroutineScope.launch {
      val outcome = outcomeAsync.await()
      Log.i("VitalPermissionOutcome", outcome.toString())
    }
  }

  Button(onClick = { permissionsLauncher.launch(Unit) }) {
    Text("Ask for permission")
  }

  //
  // AndroidX Activity Result API
  //
  import androidx.activity.ComponentActivity
  import io.tryvital.vitalhealthconnect.VitalHealthConnectManager

  val activity: ComponentActivity = ...
  val manager: VitalHealthConnectManager = ...

  activity.registerForActivityResult(contract) { outcomeAsync ->
    CoroutineScope(Dispatchers.Main).launch {
      val outcome = outcomeAsync.await()
      Log.i("VitalPermissionOutcome", outcome.toString())
    }
  }
  ```

  ```typescript React Native
  import { VitalHealth, VitalResource } from "@tryvital/vital-health-react-native";

  await VitalHealth.ask(
      [VitalResource.Activity, VitalResource.Workout, VitalResource.Sleep],
      []
  )
  ```

  ```dart Flutter
  import 'package:vital_health/vital_health.dart' as vital_health;

  final List<vital_health.HealthResource> readResources = [
    vital_health.HealthResource.activity,
    vital_health.HealthResource.sleep,
    vital_health.HealthResource.workout,
  ];
  await vital_health.askForPermission(readResources, []);
  ```
</CodeGroup>

Regardless of whether the user has granted or denied the permissions, any subsequent re-request would
be non-interactive and returns instantly. This is because the operating system only prompts the end user
once for each resource type.

If you wish
to provide a way for users to review their permission grants or denials, you can
[inform them of the system app location where they can do so](#check-if-a-read-permission-was-granted-or-denied-spoiler-you-cant).

<Warning>
  The health data read permission prompted is managed by the operating system. Vital cannot customize or
  alter its behaviour.
</Warning>

### Check if your app has asked for permissions before

You can check if your app has already asked the user *at least once* before, for permissions on a specific `VitalResource`.

Because [Ask for Permission](#ask-user-for-health-data-permissions) are gracefully ignored by the operating system beyond
the first time, checking before asking can help you skip the parts of your UX journey that only makes sense to users
going through [Ask for Permission](#ask-user-for-health-data-permissions) for the first time.

The only exception to this behaviour is when a `VitalResource` pulls a new data type introduced in a new OS release.
In this scenario, calling [Ask for Permission](#ask-user-for-health-data-permissions) would result in a OS permission
prompt that asks for permissions on *specifically* those new data types.

If you wish
to provide a way for users to review their permission grants or denials, you can
[inform them of the system app location where they can do so](#check-if-a-read-permission-was-granted-or-denied-spoiler-you-cant).

<CodeGroup>
  ```swift Native iOS
  import VitalHealthKit

  VitalHealthKitClient.shared.hasAskedForPermission(resource: .activity)
  ```

  ```kotlin Native Android
  import io.tryvital.vitalhealthconnect.VitalHealthConnectManager

  val manager = VitalHealthConnectManager.configure(context)
  manager.hasAskedForPermission(VitalResource.Activity)
  ```

  ```typescript React Native
  import { VitalHealth, VitalResource } from "@tryvital/vital-health-react-native";

  await VitalHealth.hasAskedForPermission(VitalResource.Activity);
  ```

  ```dart Flutter
  import 'package:vital_health/vital_health.dart' as vital_health;

  await vital_health.hasAskedForPermission(vital_health.HealthResource.Activity);
  ```
</CodeGroup>

### Check if a read permission was granted or denied (⚠️ Spoiler: You can't)

Vital Health SDK allows you to [ask for permission](#ask-user-for-health-data-permissions) and
[check if your app has asked for permission before](#check-if-your-app-has-asked-for-permissions-before).

However, Vital Health SDK **cannot** tell you:

1. Whether or not a user has granted or denied a read permission after the [Ask for Permission](#ask-user-for-health-data-permissions) has concluded.
2. The state of a read permission at any exact moment — granted or denied.

Apple made a deliberate choice to conceal the state of HealthKit data type read permissions from third-party apps.
Quoting [Apple's own words](https://developer.apple.com/documentation/healthkit/hkhealthstore/1614154-authorizationstatus) (as at 27 September 2024):

> To help prevent possible leaks of sensitive health information, your app cannot determine whether or not a user has granted permission to read data.
>
> If you are not given permission, it simply appears as if there is no data of the requested type in the HealthKit store.
>
> \[...]

In other words, all third-party apps — including anyone using the Vital Health SDK — would:

1. not be able to determine if a particular read permission has been granted or denied by the user;

2. not be able to manage or review read permissions inside their app.

The best course of action out of this is to inform your users of the location where they can review and manage their health data read permissions:

| Operating System     | System App         | Location                              |
| -------------------- | ------------------ | ------------------------------------- |
| iOS 8.0 and above    | Health app         | Sharing > Apps and Services           |
| iOS 15.0 and above   | Settings app       | Privacy & Security > Health           |
| Android 13 or below  | Health Connect app | Apps and Permissions                  |
| Android 14 and above | Settings app       | Health Connect > Apps and Permissions |

<Note>
  When designing your user experience, **assume** you would have zero knowledge of
  permission grants and denials after the user has gone through the [Ask for Permission](#ask-user-for-health-data-permissions) flow.
</Note>

## Automatic Data Sync

Vital Health SDK automates data sync for you on both Android and iOS. Please first consult
the provider-specific guides for the requirements and setup instructions:

* [Apple HealthKit guide](/wearables/guides/apple-healthkit)
* [Android Health Connect guide](/wearables/guides/android-health-connect)

### iOS

| Sync is automatically... |                                                                                                                                                                                              |
| ------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Activated on             | All resource types you have [asked permission for](#ask-user-for-health-data-permissions).                                                                                                   |
| Triggered by             | Two behaviours: <ul><li>Foreground: Apple HealthKit immediately delivers buffered and new changes.</li><li>Background: Hourly batch delivery of changes, subject to OS throttling.</li></ul> |

<Note>
  HealthKit change notification is an always-on behaviour.

  If you did not configure [Apple HealthKit Background Delivery](/wearables/guides/apple-healthkit)
  as instructed, your app will not receive any HealthKit change notification while it is in background.
  In turn, background sync would not occur.
</Note>

### Android

| Sync is automatically... |                                                                                                                                                                                                                           |
| ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Activated on             | All resource types you have [asked permission for](#ask-user-for-health-data-permissions).                                                                                                                                |
| Triggered by             | Two mechanisms: <ul><li>[Sync On App Launch](/wearables/guides/android-health-connect#sync-on-app-launch)</li><li>[Background Sync](/wearables/guides/android-health-connect#background-sync) if it is enabled.</li></ul> |

<Note>
  Sync On App Launch is an always-on behaviour. Background Sync is an **opt-in** behaviour.

  Please refer to the [Android Health Connect guide](/wearables/guides/android-health-connect) for the full context
  and required configuration of these two behaviours.
</Note>

### Background Sync Frequency

Vital Health SDK schedules hourly background sync with both Apple HealthKit and Android Health Connect, provided that you have:

1. Configured [Apple HealthKit Background Delivery](/wearables/guides/apple-healthkit) as per instruction; and
2. Configured [Health Connect Background Sync](/wearables/guides/android-health-connect#background-sync) and request user permissions (when necessary) as per instruction.

However, this schedule is only advisory. The OS has full discretion to defer the scheduled time based on runtime
constraints like battery power, as well as platform background execution policies. For more detailed explanation, please refer to:

* [Apple HealthKit: Sync Frequency](/wearables/guides/apple-healthkit#sync-frequency)
* [Android Health Connect: Sync Frequency](/wearables/guides/android-health-connect#sync-frequency)

In other words, your product experience should not assume near real-time availability of wearable data, since the norm
is a variable delay ranging from an hour to a day. Longer delay is also possible due to the lack of Internet
connectivity, e.g.,  a long-haul flight, or an off-the-grid trip.

The only possible exception is when your product experience does involve
**active usage** of your consumer app with an active Internet connection. For example, iOS 17+ supports third-party
apps initiating an Apple Watch workout session that would be live synced with your iPhone app.

### Pausing Data Synchronization

You can pause and unpause data sync at any time, without having to sign-out the user from the Vital Mobile SDK.
Note that pausing data sync does not reset the incremental sync progress and does not trigger a historical stage
upon unpause. It only "freezes" the sync progress.

<CodeGroup>
  ```swift Native iOS
  import VitalHealthKit

  // Pause Synchronization
  VitalHealthKitClient.shared.pauseSynchronization = true

  // Unpause Synchronization
  VitalHealthKitClient.shared.pauseSynchronization = false

  // Check if synchronization is paused
  print("Paused? \(VitalHealthKitClient.shared.pauseSynchronization)")
  ```

  ```kotlin Native Android
  import io.tryvital.vitalhealthconnect.VitalHealthConnectManager

  val manager = VitalHealthConnectManager.getOrCreate(context)

  // Pause Synchronization
  manager.pauseSynchronization = true

  // Unpause Synchronization
  manager.pauseSynchronization = false

  // Check if synchronization is paused
  Log.i("sync", "Paused? ${manager.pauseSynchronization}")
  ```

  ```typescript React Native
  import { VitalHealth } from "@tryvital/vital-health-react-native";

  // Pause Synchronization
  await VitalHealth.setPauseSynchronization(true);

  // Unpause Synchronization
  await VitalHealth.setPauseSynchronization(false);

  // Check if synchronization is paused
  const isPaused = await VitalHealth.pauseSynchronization;
  ```

  ```dart Flutter
  import 'package:vital_health/vital_health.dart' as vital_health;

  // Pause Synchronization
  await vital_health.setPauseSynchronization(true);

  // Unpause Synchronization
  await vital_health.setPauseSynchronization(false);

  // Check if synchronization is paused
  final isPaused = await vital_health.pauseSynchronization;
  ```
</CodeGroup>

## Manually start data sync

You can force data sync to start with `syncData()`.

<CodeGroup>
  ```swift Native iOS
  import VitalHealthKit

  VitalHealthKitClient.shared.syncData()
  ```

  ```kotlin Native Android
  import io.tryvital.vitalhealthconnect.VitalHealthConnectManager

  val manager = VitalHealthConnectManager.getOrCreate(context)

  manager.syncData()
  ```

  ```typescript React Native
  import { VitalHealth } from "@tryvital/vital-health-react-native";

  await VitalHealth.syncData();
  ```

  ```dart Flutter
  import 'package:vital_health/vital_health.dart' as vital_health;

  await vital_health.syncData();
  ```
</CodeGroup>

## Writing data

You can also write data back to Apple HealthKit and Android Health Connect:

<CodeGroup>
  ```swift Native iOS
  import VitalHealthKit

  try await VitalHealthKitClient.shared.write(
    input: .water(milliliters: 1000),
    startDate: Date(),
    endDate: Date()
  )
  ```

  ```kotlin Native Android
  import io.tryvital.vitalhealthconnect.VitalHealthConnectManager
  import io.tryvital.vitalhealthconnect.model.WritableVitalResource

  val manager = VitalHealthConnectManager.getOrCreate(context)

  manager.writeRecord(
      WritableVitalResource.Water,
      Instant.now(),
      Instant.now(),
      100.0
  )
  ```

  ```typescript React Native
  await VitalHealth.writeHealthData(
      VitalWriteResource.Water,
      100.0,
      new Date(),
      new Date(),
  )
  ```

  ```dart Flutter
  import 'package:vital_health/vital_health.dart' as vital_health;

  await vital_health.writeHealthData(vital_health.HealthResourceWrite.water, startDate, endDate, 1000);
  ```
</CodeGroup>

<Tip>
  Not all resources are writable in both iOS and Android. Please refer to the
  `health_resource.dart` file.
</Tip>

## Sync Status

You can observe the `syncStatus` stream for continuous updates on the health data sync status.

<CodeGroup>
  ```swift Native iOS
  import VitalHealthKit

  VitalHealthKitClient.shared.status.sink { status in
    print("Sync Status: \(status)")
  }
  ```

  ```kotlin Native Android
  import io.tryvital.vitalhealthconnect.VitalHealthConnectManager
  import kotlinx.coroutines.*
  import kotlinx.coroutines.flow.*

  val coroutineScope: CoroutineScope
  val manager = VitalHealthConnectManager.getOrCreate(context)

  manager.status
    .onEach { status -> Log.i("HealthDataSync", "$status") }
    .launchIn(coroutineScope)
  ```

  ```typescript React Native
  import { VitalHealthEvents, VitalHealthReactNativeModule } from "@tryvital/vital-health-react-native";

  const healthEventEmitter = new NativeEventEmitter(VitalHealthReactNativeModule);

  healthEventEmitter.addListener(VitalHealthEvents.statusEvent, (event: any) => {
    console.log(VitalHealthEvents.statusEvent, event);
  });
  ```

  ```dart Flutter
  import 'package:vital_health/vital_health.dart' as vital_health;

  Stream<SyncStatus> status = vital_health.syncStatus;
  ```
</CodeGroup>

## Sync Progress Debugging UI (iOS only)

<AccordionGroup>
  <Accordion title="Sync Progress View on Native iOS" defaultOpen>
    Vital Health SDK for iOS includes a `ForEachVitalResource` — a pre-baked SwiftUI View providing a
    live-updated sync progress feed of all the `VitalResource`s whose permissions have been asked for.

    You can use `ForEachVitalResource()` in any position which you would use `ForEach`. For example,
    you can use it inside a `Section` of a `List`:

    ```swift Native iOS
    import VitalHealthKit

    struct SyncProgressView: View {
      var view: some View {
        List {
          Section(header: Text("Sync Progress")) {
            ForEachVitalResource()
          }
        }
      }
    }
    ```

    If you are using UIKit, you can still access it through `UIHostingController`:

    ```swift Native iOS
    let viewController: UIViewController

    let hostingController = UIHostingController(rootView: SyncProgressView())
    viewController.present(hostingController, animated: true, completion: nil)
    ```
  </Accordion>

  <Accordion title="Sync Progress UI on Flutter / React Native" defaultOpen>
    You can open the Apple HealthKit Sync Progress Inspector UI through a simple call:

    <CodeGroup>
      ```dart Flutter
      import 'package:vital_health/vital_health.dart' as vital_health;

      unawaited(vital_health.openSyncProgressView());
      ```

      ```typescript React Native
      import { VitalHealth } from "@tryvital/vital-health-react-native";

      await VitalHealth.openSyncProgressView();
      ```
    </CodeGroup>

    This Sync Progress Inspector UI provides a live-updated sync progress feed of all the VitalResources whose permissions have been asked for.

    <Note>
      Note that it is currently a no-op on Android.
    </Note>
  </Accordion>
</AccordionGroup>


# Introduction
Source: https://docs.junction.com/wearables/vital-app/introduction


<Info>
  Vital Connect iOS app is available for [the Grow and Scale plans](https://tryvital.io/pricing).
</Info>

<Note>
  The app is available on the App Store, and you can download it
  [here](https://apps.apple.com/us/app/vital-connect/6444167196).
</Note>

The Vital iOS app allows your customers to quickly sync their Apple HealthKit data with you. This is quite handy if you don't have an iOS app, but you still want to analyse the data stored in the Apple Health app.

<div className="flex flex-row justify-between">
  <img noZoom src="https://mintcdn.com/vital/img/activity_small.png?maxW=1656&auto=format&n=nR1fvAlwouZ87zVb&q=85&s=0b8feb5b1458c1132df348657bef8c9c" width={"45%"} width="1656" height="3456" data-path="img/activity_small.png" srcset="https://mintcdn.com/vital/img/activity_small.png?w=280&maxW=1656&auto=format&n=nR1fvAlwouZ87zVb&q=85&s=3117ec6e46a92f3f083f2674177da03c 280w, https://mintcdn.com/vital/img/activity_small.png?w=560&maxW=1656&auto=format&n=nR1fvAlwouZ87zVb&q=85&s=47339e6fc2cbfaa0810c05860ec53873 560w, https://mintcdn.com/vital/img/activity_small.png?w=840&maxW=1656&auto=format&n=nR1fvAlwouZ87zVb&q=85&s=e45fb0e2bbd29fde6b8e443a1e1bd973 840w, https://mintcdn.com/vital/img/activity_small.png?w=1100&maxW=1656&auto=format&n=nR1fvAlwouZ87zVb&q=85&s=c6e353fa829d1bbe0c9b3d6af8460d69 1100w, https://mintcdn.com/vital/img/activity_small.png?w=1650&maxW=1656&auto=format&n=nR1fvAlwouZ87zVb&q=85&s=3a1c18edfd3db35a5abeb9aefcdd6ad0 1650w, https://mintcdn.com/vital/img/activity_small.png?w=2500&maxW=1656&auto=format&n=nR1fvAlwouZ87zVb&q=85&s=5016c488a41e8d4d149fcd12132f9a4b 2500w" data-optimize="true" data-opv="2" />

  <img noZoom src="https://mintcdn.com/vital/img/sleep_small.png?maxW=1656&auto=format&n=nR1fvAlwouZ87zVb&q=85&s=3f41531e4b23b892e76722f9030b37b5" width={"45%"} width="1656" height="3456" data-path="img/sleep_small.png" srcset="https://mintcdn.com/vital/img/sleep_small.png?w=280&maxW=1656&auto=format&n=nR1fvAlwouZ87zVb&q=85&s=1755bedecfdbd5cc1611ffe4a865567e 280w, https://mintcdn.com/vital/img/sleep_small.png?w=560&maxW=1656&auto=format&n=nR1fvAlwouZ87zVb&q=85&s=ae673f682c8b58aa250a7a4fe5f9bc73 560w, https://mintcdn.com/vital/img/sleep_small.png?w=840&maxW=1656&auto=format&n=nR1fvAlwouZ87zVb&q=85&s=db30e6b09473e87fc379bf4b767580fb 840w, https://mintcdn.com/vital/img/sleep_small.png?w=1100&maxW=1656&auto=format&n=nR1fvAlwouZ87zVb&q=85&s=ad77ac16f0edd9aae5b371260e5d63fe 1100w, https://mintcdn.com/vital/img/sleep_small.png?w=1650&maxW=1656&auto=format&n=nR1fvAlwouZ87zVb&q=85&s=4b0ca0bc252befd8c421227f8229e1b9 1650w, https://mintcdn.com/vital/img/sleep_small.png?w=2500&maxW=1656&auto=format&n=nR1fvAlwouZ87zVb&q=85&s=9fdba93ff28add78dc2944565cb0abb3 2500w" data-optimize="true" data-opv="2" />
</div>

## How does it work?

The flow is quite straighforward:

1. Your user, is already part of our system (e.g. they have a `userId`). If they aren't, you can create one by using our [Create User](/api-reference/user/create-user) endpoint.
2. You create a code, against a `userId`. You can use our [Create Code](/api-reference/link/create-code) endpoint for this.
3. You provide this code to your user. They will then go to the Settings and input this code. Once succesfully, their data will be synced.

<Warning>
  A Vital code can only be used once. If your user is facing issues, please ask
  them if they tried the code multiple times.
</Warning>

## Stop sharing data

After the user enters the code successfully they will have the option to:

1. Stop sharing data.
2. Add other providers (e.g. Garmin, Oura).

If the user stops sharing data, the app will clean the user's credentials stored locally. It will also reset the SDK. However it won't delete the connection between that user and Apple HealthKit on our servers. This means that even if the user stops sharing data, the already collected data won't be deleted. This is true for both Apple HealthKit but also for any other provider the user might be connected to (e.g. Garmin, Oura).

If you want to disconnect your user from a provider, you need to call the [deregister provider endpoint](/api-reference/user/deregister-a-provider).


# Debugging
Source: https://docs.junction.com/webhooks/debugging


You can debug webhook events in one of two ways: the Dashboard or using the Svix API.

### [Vital Dashboard](https://app.tryvital.io)

The Vital [Dashboard](https://app.tryvital.io)
has a Webhooks section that allows you to test and observe webhook events.

<img src="https://mintcdn.com/vital/img/webhook_logs.png?maxW=991&auto=format&n=nR1fvAlwouZ87zVb&q=85&s=16cc91ffcaacb72194ae885e7d378eec" width="100%" width="991" height="712" data-path="img/webhook_logs.png" srcset="https://mintcdn.com/vital/img/webhook_logs.png?w=280&maxW=991&auto=format&n=nR1fvAlwouZ87zVb&q=85&s=9786d6d2daae2c1a4c860fdb733bc23e 280w, https://mintcdn.com/vital/img/webhook_logs.png?w=560&maxW=991&auto=format&n=nR1fvAlwouZ87zVb&q=85&s=7b92d5c2c9e5937020310e66317c2320 560w, https://mintcdn.com/vital/img/webhook_logs.png?w=840&maxW=991&auto=format&n=nR1fvAlwouZ87zVb&q=85&s=bb03155d219c96b6176fb594eba494ce 840w, https://mintcdn.com/vital/img/webhook_logs.png?w=1100&maxW=991&auto=format&n=nR1fvAlwouZ87zVb&q=85&s=54c815847fcd48fe6ae15c70f546d7fb 1100w, https://mintcdn.com/vital/img/webhook_logs.png?w=1650&maxW=991&auto=format&n=nR1fvAlwouZ87zVb&q=85&s=13cc66576f0036cb1f709de075987a0e 1650w, https://mintcdn.com/vital/img/webhook_logs.png?w=2500&maxW=991&auto=format&n=nR1fvAlwouZ87zVb&q=85&s=ad7e8ff74eadcfeb9a7cdc6489ded02b 2500w" data-optimize="true" data-opv="2" />


# Azure Event Hubs
Source: https://docs.junction.com/webhooks/etl-pipelines/azure-event-hubs


<Info>
  ETL Pipelines integration is available for [the Scale plan](https://tryvital.io/pricing).
</Info>

## Event Structure

Each event is published with these [Azure EventData Properties](https://learn.microsoft.com/en-us/dotnet/api/azure.messaging.eventhubs.eventdata.properties?view=azure-dotnet#azure-messaging-eventhubs-eventdata-properties):

| Type          | Key              | Value                                                                                                |
| ------------- | ---------------- | ---------------------------------------------------------------------------------------------------- |
| Property      | event-type       | Vital event type, e.g., `daily.data.activity.created`                                                |
| Property      | user-id          | Vital User ID of the event subject                                                                   |
| Property      | team-id          | Vital Team ID of the event subject                                                                   |
| Property      | content-encoding | `gzip`: The blob is compressed by gzip. absent: The blob is uncompressed.                            |
| Property      | idempotency-key  | The event delivery ID; only unique amongst all events from the same user and of the same event type. |
| Partition Key | -                | Vital User ID                                                                                        |
| Data          | -                | The JSON blob. This may or may not be compressed — see `content-encoding`.                           |

<Info>
  By default, payload smaller than 1KiB would not be compressed. You must check `content-encoding` to identify if
  decompression of the event payload blob is necessary.

  To force Vital to always compress the payload, set `compression: always` on your
  [Team ETL Pipeline](https://docs.tryvital.io/api-reference/org-management/team-etl-pipeline/upsert-team-etl-pipelines) configuration.
</Info>

<Info>
  At this time, Vital publishes exclusively JSON blobs (`blob_type == json`).

  Having said that, you are strongly encouraged to check for and drop any events with unrecognized `Content-Type` and `Content-Encoding`.
</Info>

## Broker authentication

Vital connects to your Azure Event Hub namespace through a connection URL you supplied in your
[Team ETL Pipeline](https://docs.tryvital.io/api-reference/org-management/team-etl-pipeline/upsert-team-etl-pipelines) configuration:

* It must embed a Event Hub Shared Access Signature (SAS); and
* It must **not** specify an Event Hub — the default Event Hub should be declared separately as part of your
  [Team ETL Pipeline](https://docs.tryvital.io/api-reference/org-management/team-etl-pipeline/upsert-team-etl-pipelines) configuration.

## Configuration

<Info>
  Org Management API is available for [the Scale plan](https://tryvital.io/pricing).
</Info>

You can manage your Azure Event Hub destination through the Org Management API
[Team ETL Pipeline](https://docs.tryvital.io/api-reference/org-management/team-etl-pipeline/upsert-team-etl-pipelines) endpoints.

A basic configuration would look as such:

```json
{
  "team_id": "TEAM_ID",
  "preferences": {
    "enabled": ["azure_amqp"],
    "preferred": "azure_amqp",
  },
  "azure_amqp": {
    "connection_string": "Endpoint://...;...",
    "default_event_hub": "vital_event_ingestion"
  },
  "push_historical_data": true
}
```

### Multiple Event Hubs

You can [configure your Azure Event Hub destination](https://docs.tryvital.io/api-reference/org-management/team-etl-pipeline/upsert-team-etl-pipelines)
to route certain events to designated Event Hubs that are *not* the default Event Hub.

You can do so by declaring a list of Event Hub Matchers (JSON Path: `$.azure_amqp.event_hub_matchers`) . For every outbound event,
Vital sends it to the first ever Event Hub which has a matching Event Type prefix, or the default Event Hub if none matches.

```json Example
"azure_amqp": {
  ...,

  "event_hub_matchers": [
    {
      "event_type_prefix": "labtest.",
      "event_hub": "labtest-events"
    },
    {
      "event_type_prefix": "daily.",
      "event_hub": "wearable-events"
    },
    {
      "event_type_prefix": "historical.",
      "event_hub": "wearable-events"
    },
    {
      "event_type_prefix": "provider.",
      "event_hub": "wearable-events"
    }
  ]
}
```

### Azure Blob Storage

You can [configure your Azure Event Hub destination](https://docs.tryvital.io/api-reference/org-management/team-etl-pipeline/upsert-team-etl-pipelines)
to route certain events to an Azure Blob Storage container. This is useful if you have enabled the Provider Raw Data firehose, which may
publish raw data events beyond the 1 MiB size limit of Azure Event Hub.

Vital writes each matched event as a Block Blob. The blob name follows the standard format of:

```
# uncompressed
{team-id}/{user-id}/{timestamp_rfc3339}#{event-type}#{idempotency-key}.json

# gzip compressed
{team-id}/{user-id}/{timestamp_rfc3339}#{event-type}#{idempotency-key}.json.gz
```

You can do so by declaring an Event Hub Matcher that targets a Blob Storage container instead of an Event Hub:

```json Example
"azure_amqp": {
  ...,

  "event_hub_matchers": [
    {
      "event_type_prefix": "raw.garmin.",
      "blob_storage": {
        "connection_string": "Endpoint://...;...",
        "container": "garmin-raw-data"
      }
    },
    {
      "event_type_prefix": "raw.",
      "blob_storage": {
        "connection_string": "Endpoint://...;...",
        "container": "provider-raw-data"
      }
    },
    {
      "event_type_prefix": "daily.",
      "event_hub": "wearable-events"
    },
    ...
  ]
}
```

<Warning>
  Some polling-based providers can write 96 writes per day per user on certain event types, e.g., like `daily.data.activity.*` and
  `raw.fitbit.daily_activity_summary`. Azure Blob Storage typically charges based on volume and classes of operations, in addition
  to the retention cost.
</Warning>


# Google Cloud Pub/Sub
Source: https://docs.junction.com/webhooks/etl-pipelines/google-cloud-pubsub


<Info>
  ETL Pipelines integration is available for [the Scale plan](https://tryvital.io/pricing).
</Info>

# Event Structure

Each event is published with these Cloud Pub/Sub message attributes:

| Type         | Key               | Value                                                                                                |
| ------------ | ----------------- | ---------------------------------------------------------------------------------------------------- |
| Attribute    | `event-type`      | Vital event type, e.g., `daily.data.activity.created`                                                |
| Attribute    | `blob-type`       | `json` : UTF8 JSON document                                                                          |
| Attribute    | `blob-codec`      | `gzip`: The blob is compressed by gzip. `null` or absent: The blob is uncompressed.                  |
| Attribute    | `idempotency-key` | The event delivery ID; only unique amongst all events from the same user and of the same event type. |
| Ordering Key | -                 | Vital User ID (If you have enabled Event Ordering)                                                   |

<Info>
  Payload smaller than 1KiB would not be compressed. You must check `blob_codec` to identify if decompression of
  the message payload blob is necessary.
</Info>

<Info>
  At this time, Vital publishes exclusively JSON blobs (`blob-type == json`).

  Having said that, you are strongly encouraged to check for and drop any events with unrecognized `blob-type` and `blob-codec`.
</Info>

## Pub/Sub event ordering

If you wish to receive event for each Vital user in their publication order, Vital supports Pub/Sub Event Ordering, and uses the Vital User ID as the event ordering key.

Vital publishes all events through the `us-central1` and `europe-west1` PubSub regional endpoints.

<Warning>
  Pub/Sub Exactly Once Delivery is **discouraged** to be used together with Event Ordering. Our own trial suggested that the combination would struggle to move high volume of events.
</Warning>

## IAM Permission

Grant the relevant IAM Principals on your topic with these pre-defined roles:

* Pub/Sub Publisher (`roles/pubsub.publisher`)
* Pub/Sub Viewer (`roles/pubsub.viewer`)

Or more specifically these permissions if you wish to create a custom IAM role with a minimized grant:

* `pubsub.topics.get`
* `pubsub.topics.publish`

| Environment | Region | Service Account                                                                                                                     |
| ----------- | ------ | ----------------------------------------------------------------------------------------------------------------------------------- |
| Sandbox     | US     | [customer-topics-us@vital-sandbox.iam.gserviceaccount.com](mailto:customer-topics-us@vital-sandbox.iam.gserviceaccount.com)         |
| Sandbox     | Europe | [customer-topics-eu@vital-sandbox.iam.gserviceaccount.com](mailto:customer-topics-eu@vital-sandbox.iam.gserviceaccount.com)         |
| Production  | US     | [customer-topics-us@vital-prod-307415.iam.gserviceaccount.com](mailto:customer-topics-us@vital-prod-307415.iam.gserviceaccount.com) |
| Production  | Europe | [customer-topics-eu@vital-prod-307415.iam.gserviceaccount.com](mailto:customer-topics-eu@vital-prod-307415.iam.gserviceaccount.com) |

## Configuration

<Info>
  Org Management API is available for [the Scale plan](https://tryvital.io/pricing).
</Info>

You can manage your RabbitMQ destination through the Org Management API
[Team ETL Pipeline](https://docs.tryvital.io/api-reference/org-management/team-etl-pipeline/upsert-team-etl-pipelines) endpoints.

A basic configuration would look as such:

```json
{
  "team_id": "TEAM_ID",
  "preferences": {
    "enabled": ["cloud_pubsub"],
    "preferred": "cloud_pubsub",
  },
  "cloud_pubsub": {
      "project": "my-gcp-project-123456",
      "topic": "event-ingestion",
      "message_ordering": true
  },
  "push_historical_data": true
}
```


# ETL Pipelines
Source: https://docs.junction.com/webhooks/etl-pipelines/overview


<Info>
  ETL Pipelines integration is available for [the Scale plan](https://tryvital.io/pricing).
</Info>

With ETL Pipelines, Vital streams all [Vital events](/webhooks/event-structure) continuously to a supported destination
over direct authenticated TLS connections. Compared to [Webhooks](/webhooks/introduction), this simplifies your operational
complexity by removing the need to operate public unauthenticated HTTPS endpoints for receiving incoming Webhooks.

<CardGroup cols={2}>
  <Card title="Scalable" icon="arrow-up-right-dots">
    Offload the pressure on your public HTTP services.
  </Card>

  <Card title="Secure" icon="shield">
    Events are published through authenticated channels over TLS.
  </Card>

  <Card title="Compressed" icon="gift">
    Data events larger than 1 KiB are compressed before publication.
  </Card>

  <Card title="Ordered" icon="traffic-cone">
    Publication order can be preserved for select destination types.
  </Card>
</CardGroup>

## Destinations

The following destinations are supported:

<Card horizontal href="/webhooks/etl-pipelines/google-cloud-pubsub" title="Google Cloud Pub/Sub" icon="google" />

<Card horizontal href="/webhooks/etl-pipelines/rabbitmq" title="RabbitMQ" icon="rabbit" />

<Card horizontal href="/webhooks/etl-pipelines/azure-event-hubs" title="Azure Event Hubs" icon="microsoft" />

## Event Schema

Webhooks, ETL Pipelines and our API endpoints all share the same JSON object schema. Webhooks and ETL Pipelines use
identical JSON event payload structure.

Check out our [Event Catalog](/event-catalog).

## Features

### Data compression

Vital does not compress payload blobs that are smaller than 1 KiB. Please refer to the destination-specific
documentation below on how to detect a compressed blob versus an uncompressed blob.

### Static outbound IPs

Vital establish connections to your ETL Pipeline destination through a static pool of IPs. Contact Vital support to
obtain the up-to-date static IP list.

### Double writing for migration

To ensure smooth switchover from Webhooks to your new ETL Pipelines destination, Vital supports double writing events
to the combination of:

* all your Webhook endpoints; and
* your ETL Pipelines destination.

<Info>
  This is not a proper fan-out feature, and is only intended to aid customers evaluating and one-off migrating
  between destinations.

  There can only be one *preferred* destination, and the secondary destination(s) do not enjoy the same reliability
  guarantee as the *preferred* one.
</Info>

### Pushed Historical Data

When you use ETL Pipelines, Vital can *push* all the historical data as `daily.data.*` data events to your ETL Pipelines
destination.
The data-less `historical.data.*.created` event would still be emitted to denote the completion of historical pull.

## Configuring ETL Pipelines

You can change the ETL Pipelines configuration on your Teams at any time through the
[Set Team ETL Pipelines](https://docs.tryvital.io/api-reference/org-management/team-etl-pipeline/upsert-team-etl-pipelines) endpoint
of the Org Management API.

Your new configuration is typically active as soon as the endpoint has acknowledged your request.

Refer to the destination-specific documentation for configuration examples.

<Info>
  Feel free to reach out Vital support if you need assisted setup, or if you need a Vital Org Key to access the Org Management API.
</Info>


# RabbitMQ
Source: https://docs.junction.com/webhooks/etl-pipelines/rabbitmq


<Info>
  ETL Pipelines integration is available for [the Scale plan](https://tryvital.io/pricing).
</Info>

## Event Structure

Each event is published with these RabbitMQ message custom headers:

| Key                | Value                                                                        |
| ------------------ | ---------------------------------------------------------------------------- |
| Routing Key        | Vital event type, e.g., `daily.data.activity.created`                        |
| `Content-Type`     | application/json : UTF8 JSON document                                        |
| `Content-Encoding` | gzip: The blob is compressed by gzip. null/absent: The blob is uncompressed. |
| Data               | Encoded JSON blob. This may or may not be compressed — see blob\_codec.      |

<Info>
  Payload smaller than 1KiB would not be compressed. You must check `Content-Encoding` to identify if
  decompression of the message payload blob is necessary.
</Info>

<Info>
  At this time, Vital publishes exclusively JSON blobs (`blob_type == json`).

  Having said that, you are strongly encouraged to check for and drop any events with unrecognized `Content-Type` and `Content-Encoding`.
</Info>

## Broker authentication

Vital only supports password authentication at this time.

Vital publishes events with the following settings:

* Publisher Confirm mode is required
* Events are published with the Mandatory flag but without the Immediate flag.
* Events are published with Event Type as the Routing Key.

Please get in touch if these need to be configured differently for your RabbitMQ exchange.

## Configuration

<Info>
  Org Management API is available for [the Scale plan](https://tryvital.io/pricing).
</Info>

You can manage your RabbitMQ destination through the Org Management API
[Team ETL Pipeline](https://docs.tryvital.io/api-reference/org-management/team-etl-pipeline/upsert-team-etl-pipelines) endpoints.

A basic configuration would look as such:

```json
{
  "team_id": "TEAM_ID",
  "preferences": {
    "enabled": ["rabbitmq"],
    "preferred": "rabbitmq",
  },
  "rabbitmq": {
      "uri": "amqps://...",
      "exchange": "default"
  },
  "push_historical_data": true
}
```


# Event Structure
Source: https://docs.junction.com/webhooks/event-structure


All our webhook events have the following standard structure:

* A top-level `event_type` field, specifying the payload type contained in the `data` field.
* A top-level `data` field containing the event-specific payload.
* A set of top-level fields describing the event subject:
  * `team_id`: Your Vital Team ID.
  * `user_id` and `client_user_id`: The unique Vital User ID.
  * `client_user_id`: Your application user reference you declared for [the Vital User](/api-reference/user/create-user).

Schemas and examples are available through [the Event Catalog tab in the Webhooks section of our Web app](https://app.tryvital.io).

<CodeGroup>
  ```json Basic event structure
  {
    "data": {
      # ... event specific data
    },
    "event_type": "daily.data.glucose.created",
    "user_id": "4a29dbc7-6db3-4c83-bfac-70a20a4be1b2",
    "client_user_id": "01HW3FSNVCHC3B2QB5N0ZAAAVG",
    "team_id": "6b74423d-0504-4470-9afb-477252ccf67a"
  }
  ```

  ```json Example: Provider connection created
  {
    "data": {
      "source": {
        "logo": "https://storage.googleapis.com/vital-assets/freestyle.png",
        "name": "Freestyle Libre BLE",
        "slug": "freestyle_libre_ble"
      },
      "user_id": "4a29dbc7-6db3-4c83-bfac-70a20a4be1b2"
    },
    "event_type": "provider.connection.created",
    "user_id": "4a29dbc7-6db3-4c83-bfac-70a20a4be1b2",
    "client_user_id": "01HW3FSNVCHC3B2QB5N0ZAAAVG",
    "team_id": "6b74423d-0504-4470-9afb-477252ccf67a"
  }
  ```
</CodeGroup>

## Wearable data events

Wearable data events have the following extended standard structure:

* An `event_type` field for differentiating the payload contained in the data field.
* A `data` field, which comprises of:
  * The UUID of the Vital user for which this event is intended — note that this is not the `client_user_id` of the Vital user. (JSON path: `$.data.user_id`)
  * The metadata about the data source of this event (JSON path: `$.data.source`)
    * `name`: The human-readable name of the source
    * `slug`: The stable identifier Vital assigned to the source — see [Supported providers](/wearables/providers/introduction) for the complete list.
    * `logo`: The URL to an icon representing the source.
  * Any number of event-specific fields.

```json Wearable data event structure
{
  "data": {
    # ... event specific fields

    # Common wearable data event fields
    "source": {
      "logo": "https://path/to/example",
      "name": "Fitbit",
      "slug": "fitbit"
    },
    "user_id": "4a29dbc7-6db3-4c83-bfac-70a20a4be1b2"
  },
  "event_type": "daily.data.glucose.created",
  "user_id": "4a29dbc7-6db3-4c83-bfac-70a20a4be1b2",
  "client_user_id": "01HW3FSNVCHC3B2QB5N0ZAAAVG",
  "team_id": "6b74423d-0504-4470-9afb-477252ccf67a"
}
```

### Summary types

Each time a [summary object](/wearables/providers/resources) is created or updated, Vital emits a data event for the occurrence.
The object is made available directly at the top-level `data` field (JSON path: `$.data`), alongside the standard fields listed above.

<Note>
  Each summary is uniquely identified by its ID (`$.id`).

  Given the same ID, the latest version of a summary you received **replaces** all its previous versions.
</Note>

<CodeGroup>
  ```json Summary data event structure
  {
    "data": {
      # ... All summary object fields

      # Common wearable data event fields
      "source": {
        "logo": "https://path/to/example",
        "name": "Fitbit",
        "slug": "fitbit"
      },
      "user_id": "4a29dbc7-6db3-4c83-bfac-70a20a4be1b2"
    },
    "event_type": "daily.data.activity.created",
    "user_id": "4a29dbc7-6db3-4c83-bfac-70a20a4be1b2",
    "client_user_id": "01HW3FSNVCHC3B2QB5N0ZAAAVG",
    "team_id": "6b74423d-0504-4470-9afb-477252ccf67a"
  }
  ```

  ```json Example: Activity updated
  {
    "data": {
      "calendar_date": "2023-05-17",
      "calories_active": 134,
      "calories_total": 1006,
      "daily_movement": 1162,
      "date": "2023-05-17T00:00:00+00:00",
      "distance": 1162,
      "floors_climbed": 2,
      "high": null,
      "id": "715dd6a5-0c67-471c-b5fe-9681a980a2c2",
      "low": null,
      "medium": null,
      "steps": 1496,
      "timezone_offset": 3600,

      # Common wearable data event fields
      "source": {
        "logo": "https://storage.googleapis.com/vital-assets/apple_health.png",
        "name": "Apple HealthKit",
        "slug": "apple_health_kit"
      },
      "user_id": "4a29dbc7-6db3-4c83-bfac-70a20a4be1b2"
    },
    "event_type": "daily.data.activity.updated",
    "user_id": "4a29dbc7-6db3-4c83-bfac-70a20a4be1b2",
    "client_user_id": "01HW3FSNVCHC3B2QB5N0ZAAAVG",
    "team_id": "6b74423d-0504-4470-9afb-477252ccf67a"
  }
  ```
</CodeGroup>

### Timeseries types (except for Workout Streams)

Each time a batch of [timeseries samples](/wearables/providers/resources) has been created or updated, Vital emits a data event for the batch of samples.
The samples are made available under an inner `data` field under the top-level `data` field (JSON path: `$.data.data`).

<Note>
  Each timeseries sample is uniquely identified by a compound key of:

  * the timeseries resource type;
  * the source provider;
  * the [Source Type](/wearables/providers/data-attributions#source-type); and
  * the sample timestamp.

  Given the same compound key, the latest value of a sample you received **replaces** all the previous values.
</Note>

<Info>While most timeseries data are immutable, there have been exceptions of some sources aggregating some data types using time bucketing,
and some may even send updates ASAP on time buckets that have incomplete data. For example, activity timeseries data from Apple HealthKit
(integration in production) and Garmin (integration planned) do exhibit such behaviour.<br /><br />These exceptions are the rationale behind the recommended deduplication semantic as stated above.</Info>

<CodeGroup>
  ```json Timeseries data event structure
  {
    "data": {
      "data": [
        {
          "timestamp": "2023-05-16T10:00:00+00:00",
          "timezone_offset": 3600,
          "type": null,
          "unit": "count",
          "value": 237
        },
        {
          "timestamp": "2023-05-16T11:00:00+00:00",
          "timezone_offset": 3600,
          "type": null,
          "unit": "count",
          "value": 451
        },
        # ... other timeseries samples in the batch
      ],
      "source_id": 16,

      # Common wearable data event fields
      "source": {
        "logo": "https://storage.googleapis.com/vital-assets/apple_health.png",
        "name": "Apple HealthKit",
        "slug": "apple_health_kit"
      },
      "user_id": "4a29dbc7-6db3-4c83-bfac-70a20a4be1b2"
    },
    "event_type": "daily.data.steps.created",
    "user_id": "4a29dbc7-6db3-4c83-bfac-70a20a4be1b2",
    "client_user_id": "01HW3FSNVCHC3B2QB5N0ZAAAVG",
    "team_id": "6b74423d-0504-4470-9afb-477252ccf67a"
  }
  ```

  ```json Example: Calories Active created
  {
    "data": {
      "data": [
        {
          "timestamp": "2023-05-17T07:00:00+00:00",
          "start": "2023-05-17T07:00:00+00:00",
          "end": "2023-05-17T08:00:00+00:00",
          "timezone_offset": 3600,
          "type": "",
          "unit": "kcal",
          "value": 39.518054167148996
        },
        {
          "timestamp": "2023-05-17T08:00:00+00:00",
          "start": "2023-05-17T08:00:00+00:00",
          "end": "2023-05-17T09:00:00+00:00",
          "timezone_offset": 3600,
          "type": "",
          "unit": "kcal",
          "value": 31.270257990822234
        },
        {
          "timestamp": "2023-05-17T09:00:00+00:00",
          "start": "2023-05-17T09:00:00+00:00",
          "end": "2023-05-17T09:01:00+00:00",
          "timezone_offset": 3600,
          "type": "",
          "unit": "kcal",
          "value": 5.733999999999999
        }
      ],
      "source_id": 16,

      # Common wearable data event fields
      "source": {
        "logo": "https://storage.googleapis.com/vital-assets/apple_health.png",
        "name": "Apple HealthKit",
        "slug": "apple_health_kit"
      },
      "user_id": "4a29dbc7-6db3-4c83-bfac-70a20a4be1b2"
    },
    "event_type": "daily.data.calories_active.created",
    "user_id": "4a29dbc7-6db3-4c83-bfac-70a20a4be1b2",
    "client_user_id": "01HW3FSNVCHC3B2QB5N0ZAAAVG",
    "team_id": "6b74423d-0504-4470-9afb-477252ccf67a"
  }
  ```
</CodeGroup>

### Workout Streams

While Workout Streams are classified as a timeseries type, it contains a huge amount of timeseries data
which cannot be delivered by our webhook message transport.

So events for Webhook Streams are shallow, with only some minimal metadata about the workout. Successful
reception of the event indicates that the data are available to be read via our REST API,
e.g., [the Workout Stream endpoint](/api-reference/workouts/get-stream) `GET /v2/timeseries/workouts/{workout_id}/stream`.

```json Workout Stream created
{
  "data": {
    "message": "Due to payload size limits, to access the workout stream, please use the /workouts/edc80dd0-8cc8-4ec8-8b80-931fd9a3309a/stream endpoint.",
    "provider_id": "51278201336",
    "sport": {
      "id": 57,
      "name": "Other",
      "slug": "other"
    },
    "workout_id": "fdc70dd0-8cc8-4ec8-8b80-121fd9a3302a"

    # Common wearable data event fields
    "source": {
      "logo": "https://storage.googleapis.com/vital-assets/fitbit.png",
      "name": "Fitbit",
      "slug": "fitbit"
    },
    "user_id": "bf6222fb-3b81-4201-9630-118bfee01e03",
  },
  "event_type": "daily.data.workout_stream.created",
  "user_id": "4a29dbc7-6db3-4c83-bfac-70a20a4be1b2",
  "client_user_id": "01HW3FSNVCHC3B2QB5N0ZAAAVG",
  "team_id": "6b74423d-0504-4470-9afb-477252ccf67a"
}
```


# Introduction
Source: https://docs.junction.com/webhooks/introduction


With Webhooks and [ETL Pipelines](/webhooks/etl-pipelines/overview), Vital pushes any new data or updates to your endpoint
or your ETL destination as soon as they are discovered.

## Connection Created stage

When a user successfully connects a provider through [Vital Link](/wearables/connecting-providers/introduction), Vital sends a
Provider Connection Created event to acknowledge it:

<AccordionGroup>
  <Accordion title="Event Type" defaultOpen>
    `provider.connection.created`
  </Accordion>

  <Accordion title="Example" defaultOpen>
    Check out the [Provider Connection Created event](/event-catalog/provider.connection.created) in the Event Catalog.

    ```json Webhook Event
    {
      "event_type": "provider.connection.created",
      "data": {
        "user_id": "4eca10f9-...",
        "provider": {
          "name": "Strava",
          "slug": "strava",
          "logo": "https://storage.googleapis.com/vital-assets/strava.png"
        },
        "resource_availability": { ... }
      }
    }
    ```
  </Accordion>
</AccordionGroup>

## Historical Data Backfill stage

Vital also schedules jobs to backfill *historical* data upon connection establishment.

Historical data are data that exist prior to the connection establishment. Because this can [amount to months of data](/wearables/providers/introduction#historical-data-pull-range)
— and might potentially run into temporary provider-side API rate limits — these backfill jobs may take minutes to hours to complete.

<Note>
  You can inspect the status of historical data backfill jobs of each individual user through [Vital Dashboard](https://app.tryvital.io) or
  [Vital API](/api-reference/data/introspection/historical-pulls).
</Note>

Once the historical data backfill job of a specific [resource](/wearables/providers/resources) has **fully** completed, Vital sends a **Historical Pull Completion** event for the resource:

<AccordionGroup>
  <Accordion title="Event Type" defaultOpen>
    `historical.data.{RESOURCE}.created`
  </Accordion>

  <Accordion title="Usage" defaultOpen>
    This event is a data-less notification.

    Use the [Vital Data Access API](/api-reference/data/sleep/get-summary) to fetch the resource you are interested in.

    Constrain your API call using the information in the Historical Pull Completion event. For example, the event includes the
    [provider](/wearables/providers/introduction) slug as well as full datetime range which Vital has looked through.
  </Accordion>

  <Accordion title="Example" defaultOpen>
    Check out the [Historical Workout Data Pull Completion event](/event-catalog/historical.data.workouts.created) in the Event Catalog.

    ```json
    {
      "event_type": "historical.data.workouts.created",
      "data": {
        "user_id": "e9e072e8-...",
        "start_date": "2020-06-21T08:23:01+00:00",
        "end_date": "1996-11-02T14:39:28+00:00",
        "provider": "zwift"
      }
    }
    ```
  </Accordion>
</AccordionGroup>

<Note>
  [ETL Pipelines](/webhooks/etl-pipelines/overview) can opt-in to receive historical data as *Vital Data Events*
  (as outlined below in the [Incremental Data stage](#incremental-data-stage) section).

  Note that Vital would still send the Historical Pull Completion event to signal the completion of the historical data backfill stage.
</Note>

## Incremental Data stage

Once the historical data backfill stage completes, Vital [monitors for new data and changes](/wearables/providers/introduction#data-frequency).

Whenever new data or changes are discovered, Vital sends them out as **Data Events** as soon as possible:

<Note>
  You can inspect the state of incremental data updates of each individual user through [Vital Dashboard](https://app.tryvital.io) or
  [Vital API](/api-reference/data/introspection/user-resources).
</Note>

<AccordionGroup>
  <Accordion title="Event Types" defaultOpen>
    * Initial discovery — `daily.data.{RESOURCE}.created`
    * Subsequent updates — `daily.data.{RESOURCE}.updated`

    <Warning>
      Treat the `daily.data` prefix as a misnomer for *Incremental Data*. It **does not** imply a daily delivery schedule.
    </Warning>
  </Accordion>

  <Accordion title="Usage" defaultOpen>
    Vital sends out *Data Events* as soon as we discover new or updated entries as reported by a provider. This also implies:

    1. Vital does not prioritize or aggregate Data Events across providers:

       * You may receive multiple events of the same type from a single provider, because the provider supports multiple
         sources, devices or apps (e.g., iPhone sleeps and Apple Watch sleeps from Apple HealthKit);
       * You may receive multiple events of the same type from multiple providers, because the user has connected to multiple
         providers.

    2. There is no standard Data Event delivery frequency or schedule across providers *and* resources:

       * Some may be sent only once per day;
       * Some may be sent multiple times at irregular times;
       * Some may appear to be sent on a regular schedule throughout the day.

    Your system typically would ingest relevant Vital Data Events into a database.

    You can query the database with any business rules and query constraints suitable to your product experience. This may include
    your own data prioritization rules based on, e.g., [Source Type](/wearables/providers/data-attributions#source-type).

    <Note>
      Vital also offers the [Horizon AI Aggregation API](/api-reference/horizon-ai/aggregation/overview) for your data aggregation
      and consolidation needs.
    </Note>
  </Accordion>

  <Accordion title="Example" defaultOpen>
    Check out the [Workout Created event](/event-catalog/daily.data.workouts.created) in the Event Catalog.

    <Warning>The event structure and deduplication semantic of [summary types](/wearables/providers/resources) and [timeseries types](/wearables/providers/resources) have a few key differences. Please refer to [Event Structure](/webhooks/event-structure) for a more in-depth discussion.</Warning>

    ```json
    {
      "event_type": "daily.data.workouts.created",
      "data": {
        "id": "c90bd6fb-...",
        "average_hr": 198,
        "distance": 8544,
        "time_start": "2012-11-24T22:57:01+00:00",
        "time_end": "2017-04-22T04:57:31+00:00",
        "calories": 4470,
        "hr_zones": [8279],
        "user_id": "ab3247dc-...",
        ...,
        "provider_id": "dolor ipsum reiciendis Lorem veniam elit. esse",
        "source": {
          "provider": "zwift",
          "type": "unknown"
        }
      }
    }
    ```
  </Accordion>
</AccordionGroup>

## Deep Dive into Vital Webhooks

<div
  style={{
  position: "relative",
  paddingBottom: "56.872037914691944%",
  height: 0
}}
>
  <iframe
    src="https://www.loom.com/embed/0121d272e21b44049dd4d418302580a5?sid=0dc174e1-20e6-4fd9-9824-0fc2d5eaf95f"
    frameBorder={0}
    webkitallowfullscreen=""
    mozallowfullscreen=""
    allowFullScreen=""
    style={{
    position: "absolute",
    top: 0,
    left: 0,
    width: "100%",
    height: "100%"
  }}
    loading="lazy"
  />
</div>

### Managing Webhooks

You can manage your team's webhooks programmatically using our [Webhooks API](/api-reference/org-management/team-webhook/list). This API allows you to:

* **CRUD** (create/read/update/delete) your webhooks
* Manage webhook **headers**
* Update webhook **secrets**

### Authenticating Webhooks

You can verify the webhook signature. Each webhook request we send includes these three headers:

* `svix-id`
* `svix-timestamp`
* `svix-signature`

You’ll also need your webhook secret, which you can find in your Junction Dashboard > Webhooks > Endpoint tabs under "Signing Secret".

**Option 1:** Use a Svix SDK

If you’re using a compatible language, the easiest way is to utilize the [official Svix SDKs](https://docs.svix.com/receiving/verifying-payloads/how), which handle signature verification for you.

**Option 2:** Manual Verification

If the Svix SDKs are not an option, you can manually verify them following the instructions [here](https://docs.svix.com/receiving/verifying-payloads/how-manual).


# Retry Policy
Source: https://docs.junction.com/webhooks/retry-policy


Junction attempts to deliver each webhook message based on a retry schedule with exponential backoff.

## **The schedule**[**​**](https://docs.svix.com/retries#the-schedule)

Each message is attempted based on the following schedule, where each period is started following the failure of the preceding attempt:

* Immediately
* 5 seconds
* 5 minutes
* 30 minutes
* 2 hours
* 5 hours
* 10 hours
* 10 hours (in addition to the previous)

If an endpoint is removed or disabled delivery attempts to the endpoint will be disabled as well.

For example, an attempt that fails three times before eventually succeeding will be delivered roughly 35 minutes and 5 seconds following the first attempt.

## **Indicating successful delivery**[**​**](https://docs.svix.com/retries#indicating-successful-delivery)

The way to indicate that a webhook has been processed is by returning a `2xx` (status code `200-299`) response to the webhook message within a reasonable time-frame (15s ). Any other status code, including `3xx` redirects are treated as failures.

## **Failed delivery handling**[**​**](https://docs.svix.com/retries#failed-delivery-handling)

After the conclusion of the above attempts the message will be marked as `Failed` for this endpoint, and you will get a webhook of type `message.attempt.exhausted` notifying you of this error.

## **Disabling failing endpoints**[**​**](https://docs.svix.com/retries#disabling-failing-endpoints)

If all attempts to a specific endpoint fail for a period of 5 days, the endpoint will be disabled. The clock only starts after multiple deliveries failed within a 24 hour span, with at least 12 hours difference between the first and the last failure.

## **Manual retries**[**​**](https://docs.svix.com/retries#manual-retries)

You can also use the webhook portal in the dashboard to manually retry each message at any time, or automatically retry ("Recover") all failed messages starting from a given date.