Human API Developer Hub

Welcome to the Human API Developer Hub. You'll find comprehensive guides and documentation to help you start working with Human API as quickly as possible. Let's jump right in!

Get Started

Source Sync Status

You can make use of the /sources endpoint to view the type and synchronization status of the services that a user has connected.

For information on keeping your database synchronized and up-to-date with Human API, please see the guide on data sync best practices.

To retrieve information on connected sources, query the /source endpoint:

https://api.humanapi.co/v1/human/sources?access_token=demo

The result payload is an array of the services and the synchronization properties related to each specific source:

[
  {
    "id": "551ac6ef15eab1445e527c64",
    "source": "fitbit",
    "supportedDataTypes": [
        "activities",
        "bmi",
        "body_fat",
        "food",
        "sleeps",
        "height",
        "weight"
    ],
    "devices": [
        "Fitbit Charge HR",
        "Fitbit Aria"
    ],
    "connectedSince": "2015-03-31T16:10:23.382Z",
    "historySync": {
        "status": "completed",
        "oldestDate": "2015-03-21T00:00:00.000Z"
    },
    "syncStatus": {
        "status": "ok",
        "synchedAt": "2015-08-11T22:17:08.218Z",
        "newestDate": "2015-08-11T00:00:00.000Z"
    }
  }
]
{
  "id": "54cd4697a7b875300999ff44",
  "source": "emr-1-320",
  "connectedSince": "2015-01-31T21:18:15.672Z",
  "devices": [
    "emr-1-320"
  ],
  "historySync": {
    "status": "completed"
  },
  "sourceName": "Cleveland Clinic",
  "organization": {
    "id": "53c050ac51c69003200aa998",
    "name": "Cleveland Clinic",
    "href": "/medical/organizations/53c050ac51c69003200aa998"
  }
}
Property
Type
Description

source

String

Name of the connected source (all lowercase, no spaces)

supportedDataTypes

Array[String]

List of data types supported by the source
(does not indicate data is available for each type)

devices

Array[String]

List of devices
(when available)

connectedSince

Date

Date source was connected to Human API

historySync

Object

See "Historical Data Synchronization" below

syncStatus

Object

See "Current Synchronization Status" below

Device Information

The source attribute will be available immediately once you receive tokens for a user. In contrast, the devices array is updated on the first sync with the source, and thus takes a few seconds before it is available.

Best practice for updating your UI is to check source immediately upon receiving tokens and wait for a notification to sync device information when it is available.

Historical Synchronization Status

The historySync information refers to the synchronization of historical data for the particular user.

  • historySync.status tells if the synchronization is complete or not.
  • historySync.oldestDate is the oldest date of the data retrieved from the service.

Some services can take time to synchronize all the data, so you can query this endpoint and look at historySync.status to determine if it is completed or not, and once it is complete you can use historySync.oldestDate to determine how much data is available for this user.

For some services, historySync.oldestDate is just an indication of how far back the synchronization tasks attempted to retrieve data. It is not a guarantee that there is data available for this date.

Current Synchronization Status

The syncStatus property contains data about the current data synchronization tasks and indicates if the services sync is working properly or not.

  • syncStatus.synchedAt shows the last time the synchronization task ran for this user
  • syncStatus.newestDate shows the timestamp for the last retrieved data.

One thing to keep in mind about these timestamps is that they do not indicate that the data was updated at this time. It just means that we attempted to retrieve data at this point in time.

Unsupported services

Some services do not synchronize data continuously or do not support historical data synchronization. These services will show status not_supported.

{
  source: "23andme",
  supportedDataTypes: [
    "genetics"
  ],
  connectedSince: "2013-07-23T22:17:49.870Z",
  historySync: {
    status: "not_supported"
  },
  syncStatus: {
     status: "not_started"
  }
}

Source Sync Status