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

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

// example response
[
  {
    "id": "551ac6ef15eab1445e527c64",
    "source": "55a83bdc8d1eb1420aa1a71b",
    "sourceName": "Starfleet Medical",
    "supportedDataTypes": [
    ], // deprecated supportedDataTypes property
    "devices": [
      "55a83bdc8d1eb1420aa1a71b"
    ], // deprecated devices property 
    "connectedSince": "2018-07-20T21:07:13.136Z",
    "historySync": {
        "status": "completed",
        "oldestDate": "2015-03-21T00:00:00.000Z"
    },
    "organization": {
      "href": "/medical/organizations/55a83bdc8d1eb1420aa1a71b",
      "id": "55a83bdc8d1eb1420aa1a71b",
      "name": "Starfleet Medical"
    },
    "resync" : {
      "active" : true
    },
    "syncStatus": {
        "status": "ok",
        "details" : "ok",
        "synchedAt": "2018-07-20T21:07:13.136Z",
        "newestDate": "2018-04-20T19:06:11.151Z" // deprecated newestDate property
    }
  }
]

See our sources endpoint reference for more details about each property.

What are the different sync statuses and how can I respond to them?

Whether a user’s data is being synched for the first time or on a recurring basis, you can find information about an end user’s sync status by querying our sources endpoint. The table below identifies the key values and how your implementation should best respond to them:

syncStatus.status
syncStatus.details
Description
Action

inProgress

ok

User’s data is actively synching.

No action is required.

ok

ok

User's most recent sync is successful at Human API.

Query the API.

userActionRequired

invalidCredentials

User’s credentials are invalid.

Notify the end user to launch Connect and re-authenticate their data source.

userActionRequired

unverified

User's authentication was successful but there is an issue collecting downloadable data pending action at the source (e.g. they have not added their provider to the portal, an activation email link has not been used, etc).

Notify the end user to complete any pending actions for their source portal and verify if their CCDs are available for download. If downloadable CCDs are not available, advise the end user to contact their healthcare provider to make that available.

unavailable

ok

User’s data is unavailable to retrieve from the source.

Advise the user that their data is unretrievable. Contact Human API support for details.

Source Sync Status


Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.