Fulcra Developer Docs

Overview

The Fulcra Life API is the primary interface to Fulcra's core services, including data store access, user preferences, and other features. Users of the Context iOS app and the Portal also make use of the API.

This document contains a conceptual overview as well as links to reference material.

To get started quickly with example code, see the demos repository, which contains example Jupyter notebooks; or the fulcra-api Python client library, which makes interacting with the API more straightforward.

Creating an Account

To create an account, simply log in to either the Portal or Context; an account will automatically be created for you.

API Concepts

Request Authorization

Nearly all requests to the Fulcra Life API require authentication; this takes the form of a bearer access token that must be included as a header with every request.

The Python client library acts as a client that uses the Auth0 Device Authorization Flow to retrieve valid access tokens.

If you'd like to build your own client library and want your own client ID, please contact Fulcra via the Portal.

Fulcra UserID

Each user of the Fulcra Platform has a unique ID. Throughout our documentation, this is called "Fulcra UserID" or fulcra_userid. This parameter is required for several API requests.

To get your Fulcra UserID, you can decode your Access Token; it is a JWT, and the Fulcra UserID is the value of the "fulcradynamics.com/userid" claim.

In the Python client library, the get_fulcra_userid() function handles this for you automatically.

Your UserID will not change between sessions, and it need not be treated as a secret.

REST API Documentation

Specifics of the individual Life API endpoints can be found in the REST API Reference.

Retrieving data

Data from the Fulcra Platform can be retrieved via the /data/v0 API endpoints in a variety of formats.

Data Types

Below is a brief description of the types of data currently available in the Data Service. For details on each call, see the OpenAPI spec or various calls in the Python client library.

Time Series Metrics

There are dozens of time series metrics available for users that have elected to send data from various methods, including Context, to the Data Service. Each metric is a value with a specific meaning. Many are quantitative, such as StepCount (count of steps the user has taken) and HeartRate (the user's heart rate). Others are qualitative, such as SleepStage (the discrete measure of the stage of a user's sleep).

The /data/v0/time_series_grouped API call lets you retrieve a table containing an arbitrary number of metrics, indexed by time. The length of time described by each row is variable; the samprate parameter to the API call defines the length of each slice of time in seconds.

For an easy way to retrieve time series metrics and get the result as a pandas DataFrame, use the Python client library.

To get a list of the currently-available metrics and their descriptions, use the /data/v0/metrics_catalog call to get a JSON document describing each metric.

Here's a subset of metrics from this catalog:

[
  {
    "name": "AFibBurden",
    "description": "A discrete measure of the percentage of time that the user's heart
shows signs of atrial fibrillation (AFib) during a given monitoring period.",
    "unit": "percent",
    "is_time_series": true,
    "value_column": "afib_burden"
  },
  {
    "name": "ActiveCaloriesBurned",
    "description": "A cumulative measure of the amount of active energy the user has
burned.",
    "unit": "cal",
    "is_time_series": true,
    "value_column": "active_calories_burned"
  },

  ...

]

Retrieving Raw Samples For Metrics

The time_series_grouped call does the work of normalizing the samples for each metric, prioritizing conflicting samples, and resampling as necessary.

However, if you'd like to retrieve the raw samples for a given metric in order to do your own calculations, you can use the /metric_samples call. This will retrieve all the raw samples that comprise the metric during the requested time period, along with details on the source(s) that generated them.

Calendars and Calendar Events

If you've chosen to send calendar events to your data store, you can use the /calendars call to get an inventory of individual calendars, and the /calendar_events call to get the events themselves.

Apple Workouts

Apple Workout events can be retrieved using the /apple_workouts call.

Location Updates and Visits

If you're using Context and have enabled the "High Frequency Location" option, Context sends frequent location updates to your data store, indicating where you are at a specific point in time.

Update objects are serializations of the iOS/macOS CLLocationUpdate object; you can retrieve them by using the /apple_location_updates API call.

If you're sending location to your data store through Context, even if you haven't enabled the "High Frequency Location" option, Context is still sending some location information; these less-frequent samples contain a location and the range of time that you were there.

These less-frequent samples map to the iOS/macOS CLVisit objects, and you can retrieve them by using the /apple_location_visits API call.