Skip to main content

​
The hypnogram timeseries type

The removal will happen on or after 31 January 2025.
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

Recommended Action

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.

​
Redefining Source and Provider

The stated removals in this section will happen on or after 31 July 2024.
Vital has redefined what Source and Provider means across our API and event schemas:
EntityDefinition
SourceThe source context of a specific summary or a specific timeseries value group.
ProviderA wearable data provider (an app, a platform, a service, or Vital Mobile SDKs).
A Source context comprises of: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.
To migrate to the new definitions, Vital is announcing the following deprecations:
1

All Data Dvents (daily.data.*)

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 as an illustration, originally the source field describes the wearable data provider:
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:
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:
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"
}

Recommended Action

Stop parsing name, logo and slug when processing the $.data.source field in all Data Events (daily.data.*).
If you need the Provider information, you can obtain it through the Get Providers endpoint.
2

Get Summary endpoints

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/*
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 as an illustration, originally the source field describes the wearable data provider:
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:
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:
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"
}

Recommended Action

Stop parsing name, logo and slug fields in all Get Summary endpoint responses.
If you need the Provider information, you can obtain it through the Get Providers endpoint.
3

Provider Connection events

This applies to:
  • Provider Connection Created: provider.connection.created.
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:
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.
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:
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": {...}
    }
}

Recommended Action

Update your provider.connection.created event parsing logic to parse the provider field, and stop parsing the source field.

​
The is_final flag in historical.data.*.created events

The removal will happen on or after 31 June 2024.
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.

Recommended Action

Stop parsing is_final as a required field when processing historical.data.*.created events.
⌘I