Patterns and Conventions

Conventions to follow when working with Human API

Example queries

Human API lets you query a user's health data with a Bearer token authorization header. For details on how to authorize users and retrieve these tokens please click here.

Bearer token:

curl -H "Authorization: Bearer demo"


The demo access token will serve demo user data. Replace it with a valid accessToken to get data for that specific user.

Media types

Human API uses JSON (JavaScript Object Notation) for all payloads. To accommodate for this:

  • Set the Accept Header to application/json when querying data.
  • Set the Content-Type Header to application/json when sending data.

API versions

Different versions of Human API can be used by specifying the version number in the url, i.e. /v1:[version]/human

Query options

The standard query options for Human API are as described in the table below. These parameters make it easier for you to implement smart synchronization for your application. For instance, by using the updated_since parameter you only retrieve the data that was changed or added since the specified time.




The max number of records to return in one query.
Default is 50. Maximum is 500 if set.


The index of the first record to return. Default is 0


Returns records that are created after the specified date.


Returns records that are updated after the specified date.


Returns records that are created before the specified date.


Returns records that are updated before the specified date.


Returns filtered data from a specific source.

(Use the source ID e.g. 55a83bdc8d1eb1420aa1a71b)


What are the Wellness source values?

Wellness "source" values are static and alphanumeric. See this article for a dictionary of these values.


All dates are in UTC date format: YYYYMMDDTHHmmssZ

Date ranges

In addition to the parameters listed above, you can also query by a date range. These parameters must be used together.




The oldest date to retrieve.


The most recent date to retrieve.


Date filtering for medical data

If you wish to use "start_date" and "end_date" query parameters to help filter medical data, this reference will indicate which response properties will be filtered against.

Retrieving lists of objects vs a single object

Medical data includes any data from the Medical API endpoints.

To retrieve a list of periodic data objects:


To retrieve a single object by ID:


Pagination conventions

To make it easier to retrieve all the data for a user you can iterate through their historical data using the Link Header and, optionally, the X-Total-Count Header. The Link Header contains the first, prev, next, and last links that will help you easily iterate through all the records available for a query. The Link Header follows the RFC5988 standard.

For example, if you query a user with the following parameters:


Your response headers would return like this:


There is also a total count for the query stored in the X-Total-Count Header:

X-Total-Count: 56