GuidesAPI ReferencePortalSupport and Knowledge baseIntegration Status
Guides

Patterns and Conventions

Conventions to follow when working with Human API

Suggest Edits

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" https://api.humanapi.co/v1/human

📘

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:

https://api.humanapi.co/[version]/human
https://api.humanapi.co/v1/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.

ParameterDescription
limitThe max number of records to return in one query.
Default is 50. Maximum is 500 if set.
offsetThe index of the first record to return. Default is 0
created_sinceReturns records that are created after the specified date.
updated_sinceReturns records that are updated after the specified date.
created_beforeReturns records that are created before the specified date.
updated_beforeReturns records that are updated before the specified date.
sourceReturns filtered data from a specific source.

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

📘

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.

ParameterDescription
start_dateThe oldest date to retrieve.
Format YYYY-MM-DD
end_dateThe most recent date to retrieve.
Format YYYY-MM-DD

📘

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:

/v1/human/medical/[type]
/v1/human/medical/encounters

To retrieve a single object by ID:

/v1/human/medical/[type]/{id}
/v1/human/medical/encounters/5b60f9042e208223a3773175

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:

/test_results?start_date=2013-01-01&limit=50&offset=100

Your response headers would return like this:

Link:   https://api.humanapi.co/v1/human/medical/test_results?&limit=50&start_date=2013-01-01&offset=50; 
rel="prev",
   https://api.humanapi.co/v1/human/medical/test_results?limit=50&start_date=2013-01-01&offset=100; 
rel="last",
   https://api.humanapi.co/v1/human/medical/test_results?limit=50&start_date=2013-01-01&offset=0; 
rel="first"

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

X-Total-Count: 56

Updated almost 5 years ago