Human API

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
Suggest Edits

Getting Started

 

Interested in Wellness? - 6/5/2019

We have begun to make Wellness sources available via our newest version of Connect. If you are interested in this or in our Medical API, please contact our sales team.

Welcome to Human API!

You can use Human API to retrieve normalized health data from your app’s users from thousands of unique sources.

Before you’ll be able to use Human API to query real data, you’ll need to create an account and implement Connect to authenticate external sources.

What are you waiting for? Let's get started!

HAPI coding!

 
Suggest Edits

Medical API Introduction

 

Enterprise feature

If you are interested in using the Medical API, please contact our Sales Team here for more information: https://www.humanapi.co/request-call

The Medical API provides access to user’s medical records from healthcare providers. In this section you will see some common objects to many of the Medical API endpoints.

Codes

The codes Array[Object] provides code objects with specific classifications from medical coding systems (when available).

Property
Type
Description

code

String

(optional) Medical code

codeSystem

String

(optional) The identifier of the code system that the code belongs to

codeSystemName

String

(optional) The name of the code system that the code belongs to

inferred

Boolean

(optional) Set to true if this code was inferred. If unset, this code was present in the source data

name

String

The name of the code

Organization Object

Property
Type
Description

id

String

The id of the organization

name

String

The name of the organization

href

String

Human API organizations endpoint URL to retrieve full details

Name Object

Property
Type
Description

prefix

String

(optional) The title of the provider e.g. "MD"

given

Array[String]

Name values associated with the provider e.g. ["Travis", "R"]

family

String

(optional) Family name of the provider e.g. "Liddell"

What are "organizations"?

See organizations for more information.

What is "(optional)"?

Some descriptions for response properties are marked as "(optional)". This indicates that the property may be omitted from the API response.

 
Suggest Edits

Allergies

Get a list of medical allergies the user has had so far

 
gethttps://api.humanapi.co/v1/human/medical/allergies

Response Properties

Property
Type
Description

id

String

The id of the resource

source

String

The name of the originating service

updatedAt

Date

The time the record was updated on the Human API server

createdAt

Date

The time the record was created on the Human API server

name

String

(optional) The name of the allergy (e.g. ‘Etomidate’, 'Fluconazole’, 'Metaxalone’)

patient

Object

(optional) Patient information (“name” and other optional attributes)

reactionsFull

Array[Object]

(optional) See reactions object

allergen

Object

(optional) See allergen object

status

String

(optional) The status of the allergy

severity

String

(optional) The severity of the allergy

dateRange

Object

(optional) See date range object

codes

Array[Object]

(optional) See codes

Allergen Object

Property
Type
Description

name

String

(optional) Name of the allergen

codes

Object

(optional) See codes

Reaction Object

Property
Type
Description

name

String

(optional) Name of the allergen

codes

Object

(optional) See codes

reactionType

Object

(optional) See reaction type object

Reaction Type Object

Property
Type
Description

name

String

(optional) Name of the reaction

codes

Object

(optional) See codes

Date Range Object

Property
Type
Description

start

Date

(optional) Start date

end

Date

(optional) End date

# Get all allergies associated with the user
curl -H "Authorization: Bearer someToken" "https://api.humanapi.co/v1/human/medical/allergies"
A binary file was returned

You couldn't be authenticated

{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
# Returns a json array of allergies:
[
    {
        "createdAt": "2014-10-19T21:02:17.949Z",
        "id": "544323ae5b48098829dcc437",
        "name": "Oxycodone",
        "organization": {
            "href": "/medical/organizations/53c050ac51c69003200aa998",
            "id": "53c050ac51c69003200aa998",
            "name": "Cleveland Clinic"
        },
        "patient": {
            "name": "Maxwell Forrest"
        },
        "reactionsFull": [],
        "source": "emr-1-320",
        "updatedAt": "2014-10-19T21:02:17.949Z"
        "allergen": {
            "codes": [
                {
                    "code": "10831",
                    "codeSystem": "2.16.840.1.113883.6.88",
                    "codeSystemName": "RxNorm",
                    "name": "Bactrim"
                },
                {
                    "code": "N0000008034",
                    "codeSystem": "2.16.840.1.113883.3.26.1.5",
                    "codeSystemName": "NDF-RT",
                    "name": "Sulfa (Sulfonamide Antibiotics)"
                }
            ]
        },
        "codes": [
            {
                "code": "10831",
                "codeSystem": "2.16.840.1.113883.6.88",
                "codeSystemName": "RxNorm",
                "name": "Bactrim"
            },
            {
                "code": "N0000008034",
                "codeSystem": "2.16.840.1.113883.3.26.1.5",
                "codeSystemName": "NDF-RT",
                "name": "Sulfa (Sulfonamide Antibiotics)"
            }
        ]
    },
    {
        "id": "544323ae5b48098829dcc438",
        "name": "Metaxalone",
        "organization": {
            "href": "/medical/organizations/53c050ac51c69003200aa998",
            "id": "53c050ac51c69003200aa998",
            "name": "Cleveland Clinic"
        },
        "patient": {
            "name": "Maxwell Forrest"
        },
        "reactionsFull": [],
        "source": "emr-1-320",
        "createdAt": "2014-10-19T21:02:17.949Z",
        "updatedAt": "2014-10-19T21:02:17.949Z",
        "allergen": {
            "codes": [
                {
                    "code": "10831",
                    "codeSystem": "2.16.840.1.113883.6.88",
                    "codeSystemName": "RxNorm",
                    "name": "Bactrim"
                },
                {
                    "code": "N0000008034",
                    "codeSystem": "2.16.840.1.113883.3.26.1.5",
                    "codeSystemName": "NDF-RT",
                    "name": "Sulfa (Sulfonamide Antibiotics)"
                }
            ]
        },
        "codes": [
            {
                "code": "10831",
                "codeSystem": "2.16.840.1.113883.6.88",
                "codeSystemName": "RxNorm",
                "name": "Bactrim"
            },
            {
                "code": "N0000008034",
                "codeSystem": "2.16.840.1.113883.3.26.1.5",
                "codeSystemName": "NDF-RT",
                "name": "Sulfa (Sulfonamide Antibiotics)"
            }
        ]
    }
]
# Returns a json array of allergies:
[
    {
        "createdAt": "2014-10-19T21:02:17.949Z",
        "id": "544323ae5b48098829dcc437",
        "name": "Oxycodone",
        "organization": {
            "href": "/medical/organizations/53c050ac51c69003200aa998",
            "id": "53c050ac51c69003200aa998",
            "name": "Cleveland Clinic"
        },
        "patient": {
            "name": "Maxwell Forrest"
        },
        "reactionsFull": [],
        "source": "emr-1-320",
        "updatedAt": "2014-10-19T21:02:17.949Z"
        "allergen": {
            "codes": [
                {
                    "code": "10831",
                    "codeSystem": "2.16.840.1.113883.6.88",
                    "codeSystemName": "RxNorm",
                    "name": "Bactrim"
                },
                {
                    "code": "N0000008034",
                    "codeSystem": "2.16.840.1.113883.3.26.1.5",
                    "codeSystemName": "NDF-RT",
                    "name": "Sulfa (Sulfonamide Antibiotics)"
                }
            ]
        },
        "codes": [
            {
                "code": "10831",
                "codeSystem": "2.16.840.1.113883.6.88",
                "codeSystemName": "RxNorm",
                "name": "Bactrim"
            },
            {
                "code": "N0000008034",
                "codeSystem": "2.16.840.1.113883.3.26.1.5",
                "codeSystemName": "NDF-RT",
                "name": "Sulfa (Sulfonamide Antibiotics)"
            }
        ]
    },
    {
        "id": "544323ae5b48098829dcc438",
        "name": "Metaxalone",
        "organization": {
            "href": "/medical/organizations/53c050ac51c69003200aa998",
            "id": "53c050ac51c69003200aa998",
            "name": "Cleveland Clinic"
        },
        "patient": {
            "name": "Maxwell Forrest"
        },
        "reactionsFull": [],
        "source": "emr-1-320",
        "createdAt": "2014-10-19T21:02:17.949Z",
        "updatedAt": "2014-10-19T21:02:17.949Z",
        "allergen": {
            "codes": [
                {
                    "code": "10831",
                    "codeSystem": "2.16.840.1.113883.6.88",
                    "codeSystemName": "RxNorm",
                    "name": "Bactrim"
                },
                {
                    "code": "N0000008034",
                    "codeSystem": "2.16.840.1.113883.3.26.1.5",
                    "codeSystemName": "NDF-RT",
                    "name": "Sulfa (Sulfonamide Antibiotics)"
                }
            ]
        },
        "codes": [
            {
                "code": "10831",
                "codeSystem": "2.16.840.1.113883.6.88",
                "codeSystemName": "RxNorm",
                "name": "Bactrim"
            },
            {
                "code": "N0000008034",
                "codeSystem": "2.16.840.1.113883.3.26.1.5",
                "codeSystemName": "NDF-RT",
                "name": "Sulfa (Sulfonamide Antibiotics)"
            }
        ]
    }
]
 
# Get all allergies associated with the user
curl -H "Authorization: Bearer demo" "https://api.humanapi.co/v1/human/medical/allergies"
Suggest Edits

Encounters

Get a list of medical encounters the user has had so far

 
gethttps://api.humanapi.co/v1/human/medical/encounters

Response Properties

Property
Type
Description

id

String

The id of the resource

source

String

The name of the originating service

updatedAt

Date

The time the record was updated on the Human API server

createdAt

Date

The time the record was created on the Human API server

dateTime

Date

(optional) The date of the encounter

visitType

String

(optional) The type of visit

provider

Object

(optional) The provider for the encounter (see provider object)

prescriptions

Array[Object]

(optional) A list of prescriptions provided during the encounter (see link object)

diagnoses

Array[Object]

(optional) A list of diagnoses for the encounter (see link object)

vitals

Object

(optional) Vitals captured during the encounter (e.g. {"temperature" : 95.2 [degF]","weight" : 180 [lb_av]","height" : "69 [in_us]"})

vitalSigns

Array[Object]

(optional) A list of vital signs from the encounter (see link object)

reasons

Array[String]

(optional) A list of reasons for the encounter (e.g. [‘Follow-up’, 'Consult’, 'DYSPHONIA', 'Back Pain’])

orders

Array[Object]

(optional) A list of medication orders for the patient (see orders object)

testResults

Array[Object]

(optional) A list of test results for the patient (see link object)

plansOfCare

Array[Object]

(optional) A list of plans of care from the encounter (see link object)

medications

Array[Object]

(optional) A list of medications used by the patient. Objects in array can have some or many of the properties of medications. Common properties are "name", "productName", "startDate", "endDate", "instructions".

followUpInstructions

String

(optional) Follow-up instructions

patientInstruction

Object

(optional) Patient information (“name” and other optional attributes)

organization

Object

(optional) See organizations object

codes

Array[Object]

(optional) See codes

Orders Object

Property
Type
Description

name

String

(optional) The name of the order

codeType

String

(optional) The code type of the order (e.g. “CPT( R )”, “Custom”)

expectedDate

Date

(optional) The date the order is expected

expireDate

Date

(optional) The date the order expires

procedureCode

String

(optional) The procedure code of the order

type

String

(optional) The type of the order (e.g. “Lab”, “Procedures”)

codes

Array[Object]

(optional) See codes

Provider Object

Property
Type
Description

name

String

(optional) Name of the provider

departmentName

String

(optional) Name of the provider department

address

String

(optional) Address of the provider

Link Object

Property
Type
Description

name

String

Name of the data element

href

String

API path to the full data object

# Get all encounters associated with the user
curl -H "Authorization: Bearer someToken" "https://api.humanapi.co/v1/human/medical/encounters"
A binary file was returned

You couldn't be authenticated

{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
# Returns a json array of encounters:
[
    {
        "codes": [
            {
                "code": "3",
                "codeSystem": "1.2.840.114350.1.13.106.2.7.4.698084.30",
                "codeSystemName": "Epic.EncounterType",
                "name": "Hospital Encounter"
            }
        ],
        "createdAt": "2014-10-19T21:33:19.971Z",
        "dateTime": "2014-07-21T17:30:00.000Z",
        "diagnoses": [],
        "id": "54442e1f8bbb040d5388e842",
        "medications": [
            {
                "canRefill": false,
                "codes": [],
                "genericProductIndicator": "42200032301810",
                "hasPendingRefill": false,
                "name": "FLUTICASONE PROPIONATE (NASAL) 50 MCG/ACT NA SUSP",
                "ndcCode": "0054-3270-99",
                "startDate": "2010-09-17T04:00:00.000Z"
            },
            {
                "canRefill": false,
                "codes": [],
                "genericProductIndicator": "01200010100315",
                "hasPendingRefill": false,
                "name": "Amoxicillin 875 MG OR TABS",
                "ndcCode": "0093-2264-01",
                "startDate": "2010-09-17T04:00:00.000Z"
            }
        ],
        "orders": [
            {
                "codeType": "Custom",
                "codes": [],
                "expectedDate": "2012-01-19T05:00:00.000Z",
                "expireDate": "2013-01-18T05:00:00.000Z",
                "name": "LIPID PROFILE",
                "procedureCode": "LABLIPID",
                "type": "LAB CHEMISTRY"
            }
        ],
        "organization": {
            "href": "/medical/organizations/54dc427aaa6b4cb7d6203061",
            "id": "54dc427aaa6b4cb7d6203061",
            "name": "Cleveland Clinic"
        },
        "patient": {},
        "plansOfCare": [],
        "prescriptions": [],
        "provider": {
            "address": "1064 Goosetown Drive\nAsheville, NC 28801",
            "departmentName": "Asheville Goosetown Laboratory",
            "name": "LAB"
        },
        "reasons": [
            "Ear Problem"
        ],
        "source": "emr-1-320",
        "testResults": [],
        "updatedAt": "2014-10-19T21:33:19.971Z",
        "visitType": "Office Visit",
        "vitalSigns": []
    }
]
 
Suggest Edits

Functional Statuses

Get a list of medical functional statuses associated with the user

 
gethttps://api.humanapi.co/v1/human/medical/functional_statuses

Response Properties

Property
Type
Description

id

String

The id of the resource

source

String

The name of the originating service

updatedAt

Date

The time the record was updated on the Human API server

createdAt

Date

The time the record was created on the Human API server

dateTime

Date

(optional) The date of the functional status

name

String

(optional) The name of the functional status

codes

Array[Object]

(optional) See codes

# Get all functional statuses associated with the user
curl -H "Authorization: Bearer someToken" "https://api.humanapi.co/v1/human/medical/functional_statuses"
A binary file was returned

You couldn't be authenticated

{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
# Returns a json array of functional statuses:
[
    {
        "id": "55e692d20c7deefb7cfe90f8",
        "createdAt": "2014-09-01T21:42:09.969Z",
        "updatedAt": "2014-09-01T21:42:10.072Z",
        "dateTime": "2014-02-11T09:30:00.000Z",
        "source": "emr-1-320",
        "name": "Memory impairment",
        "codes": []
    }
]
 
Suggest Edits

Immunizations

Get a list of immunizations the user has had so far

 
gethttps://api.humanapi.co/v1/human/medical/immunizations

Response Properties

Property
Type
Description

id

String

The id of the resource

source

String

The name of the originating service

updatedAt

Date

The time the record was updated on the Human API server

createdAt

Date

The time the record was created on the Human API server

dates

Array[Date]

(optional) The dates immunization was given.

name

String

(optional) The name of the immunization (e.g. ‘Tetanus+Dip ADULT (Td)’, 'Varicella’, 'Influenza Virus Vaccine’)

patient

Object

(optional) Patient information (“name” and other optional attributes)

organization

Object

(optional) See organizations object

codes

Array[Object]

(optional) See codes

# Get all immunizations associated with the user
curl -H "Authorization: Bearer someToken" "https://api.humanapi.co/v1/human/medical/immunizations"
A binary file was returned

You couldn't be authenticated

{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
# Returns a json array of immunizations:
[{
  "id": "5443d24d0d2a0e0c4b3672e8",
  "name": "Tetanus+Dip ADULT (Td)",
  "source": "emr-1-320",
  "dates": ["2005-09-27T04:00:00.000Z", "1995-01-01T05:00:00.000Z"],
  "patient": {
    "name": "Maxwell Forrest"
  },
  "updatedAt": "2014-10-19T21:02:17.949Z",
  "createdAt": "2014-10-19T21:02:17.949Z",
  "organization": {
    "id": "53c050ac51c69003200aa998",
    "name": "Cleveland Clinic",
    "href": "/medical/organizations/53c050ac51c69003200aa998"
  }
}, {
  "id": "5443d24d0d2a0e0c4b3672eb",
  "name": "Pneumococcal Conjugate PCV13",
  "source": "emr-1-320",
  "dates": ["2014-03-14T04:00:00.000Z"],
  "patient": {
    "name": "Maxwell Forrest"
  },
  "updatedAt": "2014-10-19T21:02:17.949Z",
  "createdAt": "2014-10-19T21:02:17.949Z",
  "organization": {
    "id": "53c050ac51c69003200aa998",
    "name": "Cleveland Clinic",
    "href": "/medical/organizations/53c050ac51c69003200aa998"
  },
  "codes": []
}]
 
Suggest Edits

Instructions

Get a list of medical instructions associated with the user

 
gethttps://api.humanapi.co/v1/human/medical/instructions

Response Properties

Property
Type
Description

id

String

The id of the resource

source

String

The name of the originating service

updatedAt

Date

The time the record was updated on the Human API server

createdAt

Date

The time the record was created on the Human API server

dateTime

String

(optional) The date of the instruction

name

String

(optional) The name of the instruction (ex. “instructions”, or “discharge instructions”, etc.)

text

String

(optional) Text content of the instruction

codes

Array[Object]

(optional) See codes

# Get all instructions associated with the user
curl -H "Authorization: Bearer someToken" "https://api.humanapi.co/v1/human/medical/instructions"
A binary file was returned

You couldn't be authenticated

{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
# Returns a json array of instructions:
[
    {
        "id": "55e692d20c7deefb7cfe90f8",
        "createdAt": "2015-09-01T21:42:09.969Z",
        "updatedAt": "2015-09-01T21:42:10.072Z",
        "dateTime": "2015-02-11T09:30:00.000Z",
        "source": "emr-1-320",
        "name": "Instructions",
        "text": "Please forward scans to \nDr. Reddy\nDepartment of Children's medicine\n 123 Main St.\nCedarCity, CA 00000\n\nI encourage you to visit my website",
        "codes": []
    }
]
 
Suggest Edits

Medications

Get a list of medical medications the user has had so far

 
gethttps://api.humanapi.co/v1/human/medical/medications

Response Properties

Property
Type
Description

id

String

The id of the resource

source

String

The name of the originating service

updatedAt

Date

The time the record was updated on the Human API server

createdAt

Date

The time the record was created on the Human API server

instructions

String

(optional) The instructions provided for the medication (e.g. ‘Take 1 tablet by mouth daily.’)

details

Object

(optional) Parsed dosage and instruction information (see below)

genericProductIndicator

String

(optional) Generic Product Identifier of the medication

patient

Object

(optional) Patient information (“name” and other optional attributes)

name

String

(optional) The name of the medication (e.g. 'Cyanocobalamin (VITAMIN B12 PO)’)

provider

String

(optional) The name of the provider - if available (e.g. 'Jacob Smith, MD’, 'Outside Provider’, 'Unknown’)

providerID

String

(optional) The id of the provider

ndcCode

String

(optional) The National Drug Code of the medication (if provided)

productName

String

(optional) The product name of the medication - if provided (e.g. 'zolpidem’, 'gabapentin’, 'aspirin’)

commonBrandName

String

(optional) The common brand name of the medication - if provided (e.g. 'NORCO’, 'XANAX’, 'NEURONTIN’)

dosageInfo

String

(optional) The dosage information - if provided (e.g. '10 MG tablet’, '100 UNIT/ML injection’, '5mg Tab’)

pharmacy

Object

(optional) Pharmacy information - if provided (see pharmacy below)

organization

Object

(optional) See organizations object

expiration

Date

(optional) The expiration date of the medication - if provided

refillsRemaining

Number

(optional) The number of refills remaining - if available

refillsTotal

Number

(optional) The total number of refills - if available

status

String

(optional) Prescription status for a medication - if available (e.g. 'Active’, 'On Hold’)

startDate

Date

(optional) Start date of the medication

endDate

Date

(optional) End date of the medication

codes

Array[Object]

(optional) See codes

Pharmacy Object

Property
Type
Description

id

String

The id of the resource

name

String

(optional) The name of the pharmacy

address

String

(optional) The address of the pharmacy

phone

String

(optional) The phone number of the pharmacy

hours

String

(optional) The opening hours of the pharmacy

Details Object

Property
Type
Description

dosage

Object

(optional) The 'form’ and 'value’ of a dosage if applicable e.g. "dosage": {"form: "capsule", "value": "3"}

frequency

Object

(optional) The frequency that the medication should be taken e.g. "frequency": {"number": "1", "unit": "day"}

route

String

(optional) The route the medication is taken e.g. "route": "enteral_oral"

strength

Object

(optional) The strength of the dosage e.g. "strength": {"number": "100, "unit": "mg"}

# Get all medications associated with the user
curl -H "Authorization: Bearer someToken" "https://api.humanapi.co/v1/human/medical/medications"
A binary file was returned

You couldn't be authenticated

{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
# Returns a json array of medications:
[{
  "id": "55a2ff2d197f25c42f2e84b7",
  "updatedAt": "2014-12-09T18:06:42.100Z",
  "createdAt": "2014-12-09T18:06:42.100Z",
  "commonBrandName": "CLARITIN",
  "details": {
      "dosage": {
          "form": "tablet",
          "value": "1"
      },
      "frequency": {
          "number": "1",
          "unit": "as-needed"
      },
      "route": "enteral_oral",
      "strength": {
          "number": "10",
          "unit": "mg"
      }
  },
  "dosageInfo": "10 MG tablet",
  "genericProductIndicator": "41550030000320",
  "instructions": "Take 1 tab by mouth as needed (allergies).",
  "name": "loratadine (CLARITIN) 10 MG tablet",
  "ndcCode": "0781-5077-01",
  "organization": {
      "href": "/medical/organizations/53c050ac51c69003200aa998",
      "id": "53c050ac51c69003200aa998",
      "name": "Cleveland Clinic"
  },
  "patient": {
      "name": "Maxwell Forrest"
  },
  "productName": "loratadine",
  "provider": "Isaias Kingston, MD",
  "providerID": "34665",
  "source": "emr-1-320",
  "status": "Active",
  "startDate": "2012-01-26T00:00:00.000Z",
  "endDate": "2014-01-26T00:00:00.000Z",
  "codes": []
},
{
  "id": "55a2fef4197f25c42f2e849f",
  "updatedAt": "2014-12-09T18:06:42.100Z"
  "createdAt": "2014-12-09T18:06:42.100Z",
  "commonBrandName": "LEXAPRO",
  "details": {
      "dosage": {
          "form": "tablet",
          "value": "1"
      },
      "frequency": {
          "number": "1",
          "unit": "day"
      },
      "route": "enteral_oral",
      "strength": {
          "number": "5",
          "unit": "mg"
      }
  },
  "dosageInfo": "5 mg tablet",
  "genericProductIndicator": "58160034100310",
  "instructions": "Take 1 tablet by mouth every day",
  "name": "escitalopram (LEXAPRO) 5 mg tablet",
  "ndcCode": "0378-3855-77",
  "organization": {
      "href": "/medical/organizations/53c050ac51c69003200aa998",
      "id": "53c050ac51c69003200aa998",
      "name": "Cleveland Clinic"
  },
  "patient": {
      "name": "Maxwell Forrest"
  },
  "productName": "escitalopram",
  "provider": "Isaias Kingston, MD",
  "providerID": "34665",
  "source": "emr-1-320",
  "status": "On Hold",
  "startDate": "2012-01-26T00:00:00.000Z",
  "endDate": "2014-01-26T00:00:00.000Z",
  "codes": []
}]
 
Suggest Edits

Narratives

Get a list of medical narratives associated with the user

 
gethttps://api.humanapi.co/v1/human/medical/narratives

Response Properties

Property
Type
Description

id

String

The id of the resource

source

String

The name of the originating service

updatedAt

Date

The time the record was updated on the Human API server

createdAt

Date

The time the record was created on the Human API server

dateTime

Date

(optional) The date of the narrative

author

String

(optional) The name of the author

entries

Array[Object]

(optional) Array of entry objects (See below)

Entry Object

Property
Type
Description

title

String

(optional) The title of the entry

text

String

(optional) The description text of the entry

# Get all narratives associated with the user
curl -H "Authorization: Bearer someToken" "https://api.humanapi.co/v1/human/medical/narratives"
A binary file was returned

You couldn't be authenticated

{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
# Returns a json array of narratives:
[{
  "id": "54e3521f79192a2e4993dfdc",
  "source": "emr-1-320",
  "updatedAt": "2015-02-11T06:26:53.217Z",
  "createdAt": "2015-02-11T06:26:53.217Z",
  "dateTime": "Mon Jul 07 2014 14:40:26 GMT-0700 (PDT)",
  "author": "Christine Johnson",
  "entries": [{
    "title": "Note from Sutter Health Affiliates and Community Connect Practices",
    "text": "This document contains information that was shared with Maxwell Forrest. It may not contain the entire record from Sutter Health Affiliates and Community Connect Practices."
  }, {
    "title": "Reason for Visit",
    "text": "Reason Comments Diarrhea"
  }, {
    "title": "Encounter Details",
    "text": "Date Type Department Care Team 07/07/2014 Office Visit Palo Alto Family Medicine 795 El Camino Real Palo Alto, CA 94301 650-333-4444 Johnson, Christine, NP 795 EL CAMINO REAL Palo Alto, CA 94301 650-333-4444 650-333-4444 (Fax)"
  }, {
    "title": "Active Allergies and Adverse Reactions - as of 02/09/2015",
    "text": "No Known Allergies"
  }, {
    "title": "Current Medications - as of 02/09/2015",
    "text": "No known medications"
  }, {
    "title": "Active Problems - as of 02/09/2015",
    "text": "Problem Noted Date No Active Medical Problems 04/14/2014"
  }, {
    "title": "Social History - as of 02/09/2015",
    "text": "Tobacco Use Types Packs/Day Years Used Date Never smoker 0 0 Alcohol Use Drinks/Week oz/Week Yes 1 Drinks containing 0.5 oz of alcohol 0.5"
  }, {
    "title": "Last Filed Vital Signs",
    "text": "Vital Sign Reading Time Taken Blood Pressure 120 / 70 07/07/2014  2:47 PM PDT Pulse 75 07/07/2014  2:47 PM PDT Temperature 36.4 °C (97.6 °F) 07/07/2014  2:47 PM PDT Respiratory Rate - - Height - - Weight 84.823 kg (187 lb) 07/07/2014  2:47 PM PDT Body Mass Index 23.52 07/07/2014  2:47 PM PDT Oxygen Saturation 98% 07/07/2014  2:47 PM PDT"
  }, {
    "title": "Plan of Care",
    "text": "Not on file"
  }, {
    "title": "Procedures",
    "text": ""
  }, {
    "title": "Results",
    "text": "Not on file"
  }, {
    "title": "Visit Diagnoses",
    "text": "Viral enteritis - Primary Intestinal infection due to other organism, not elsewhere classified Diarrhea Diarrhea"
  }, {
    "title": "Insurance",
    "text": "Payer Benefit Plan / Group Subscriber ID Type Phone Address BLUE SHIELD BLUE SHIELD PPO XEK901245582 PRIVATE FFS PPO/EPO PO BOX 272550 CHICO, CA 95927 Guarantor Name Account Type Relation to Patient Date of Birth Phone Billing Address FORREST,MAXWELL Personal/Family Self 05/30/1978 Work: +1-650-333-4444 Home: +1-650-333-4444 1 MILKY WAY WAY APT E MENLO PARK, CA 94025"
  }],
  "organization": {
    "id": "53c050ac51c69003200aa998",
    "name": "Cleveland Clinic",
    "href": "/medical/organizations/53c050ac51c69003200aa998"
  }
}]
 
Suggest Edits

Organizations

Get basic medical organization data in Human API associated with the user

 
gethttps://api.humanapi.co/v1/human/medical/organizations/id

Response Properties

Property
Type
Description

id

String

The id of the resource

name

String

The name of the organization

Organization Object (from other endpoints)

Property
Type
Description

id

String

The id of the resource

name

String

The name of the organization

href

String

Human API organizations endpoint URL to retrieve full details

# Get an organization by id
curl -H "Authorization: Bearer someToken" "https://api.humanapi.co/v1/human/medical/organizations/54dc427aaa6b4cb7d6203061"
A binary file was returned

You couldn't be authenticated

{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
{
  "id": "54dc427aaa6b4cb7d6203061",
  "name": "Cleveland Clinic"
}
 
Suggest Edits

Plans of Care

Get a list of medical plans of care associated with the user

 
gethttps://api.humanapi.co/v1/human/medical/plans_of_care

Response Properties

Property
Type
Description

id

String

The id of the resource

source

String

The name of the originating service

updatedAt

Date

The time the record was updated on the Human API server

createdAt

Date

The time the record was created on the Human API server

name

String

(optional) The name of the plan of care

text

String

(optional) The text description of the author

date

Date

(optional) The date of the plan of care

type

String

(optional) The type of the plan of care

specialty

String

(optional) The specialty of the plan of care

provider

Object

(optional) See provider object

organization

Object

(optional) See organizations object

codes

Array[Object]

(optional) See codes

Provider Object

Property
Type
Description

name

Object

(optional) See name object

address

String

(optional) Address of the provider e.g. "CORE ORTHOPEDICS, SIOUX FALLS, SD, 57103"

# Get all plans of care associated with the user
curl -H "Authorization: Bearer someToken" "https://api.humanapi.co/v1/human/medical/plans_of_care"
A binary file was returned

You couldn't be authenticated

{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
# Returns a json array of plans of care:
[ {
    "id": "55e692540c7deefb7cfe90f7",
    "createdAt": "2014-09-01T20:46:35.731Z",
    "updatedAt": "2014-09-01T20:46:35.731Z",
    "source": "emr-1-320",
    "name": "encounter",
    "text": "11/13/2015 Appointment Physical Therapy ",
    "organization": {
        "href": "/medical/organizations/53c050ac51c69003200aa998",
        "id": "53c050ac51c69003200aa998",
        "name": "Cleveland Clinic"
    },
    "codes": []
} ]
 
Suggest Edits

Problems

Get a list of medical problems the user has had so far

 
gethttps://api.humanapi.co/v1/human/medical/issues

Response Properties

Property
Type
Description

id

String

The id of the resource

source

String

The name of the originating service

updatedAt

Date

The time the record was updated on the Human API server

createdAt

Date

The time the record was created on the Human API server

dateTime

Date

(deprecated) Date associated with the problem

documentedDate

Date

(Optional) Date that the problem was documented

startDate

Date

(optional) Date of the physician's understanding of when the problem first appeared

endDate

Date

(Optional) Date of the physician's understanding of when the problem was resolved

name

String

(optional) The name of the problem e.g. "Generalized abdominal pain"

patient

Object

(optional) Patient information (“name” and other optional attributes)

status

String

(optional) Status of the problem e.g. "Active"

sourceOfInfo

String

(Optional) Context of the problem e.g. "Resolved Problem","Active Problem", "Encounter Diagnosis", etc.

comments

String

(Optional) Comments or notes related to the problem

concernStartDate

Date

(Optional) Start of the physician's concern about the problem. Can be different from when the problem actually started.

concernEndDate

Date

(Optional) End of the physician's concern about the problem. Can be different from when the problem actually ended.

organization

Object

(optional) See organizations object

codes

Array[Object]

(optional) See codes

# Get all problems associated with the user
curl -H "Authorization: Bearer someToken" "https://api.humanapi.co/v1/human/medical/issues"
A binary file was returned

You couldn't be authenticated

{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
# Returns a json array of problems:
[
    {
        "codes": [
            {
                "code": "6142004",
                "codeSystem": "2.16.840.1.113883.6.96",
                "codeSystemName": "SNOMED-CT",
                "name": "Influenza"
            }
        ],
        "createdAt": "2014-10-19T21:02:17.949Z",
        "dateTime": "2014-08-29T04:00:00.000Z",
        "id": "5443d6ca71b5c7f1a243879f",
        "name": "Influenza",
        "organization": {
            "href": "/medical/organizations/54dc427aaa6b4cb7d6203061",
            "id": "54dc427aaa6b4cb7d6203061",
            "name": "Cleveland Clinic"
        },
        "patient": {},
        "source": "emr-1-320",
        "updatedAt": "2014-10-19T21:02:17.949Z"
    },
    {
        "codes": [
            {
                "code": "729.89",
                "codeSystem": "2.16.840.1.113883.6.103",
                "codeSystemName": "ICD-9CM",
                "name": "WEAKNESS OF LEFT LEG"
            },
            {
                "code": "R53.1",
                "codeSystem": "2.16.840.1.113883.6.90",
                "codeSystemName": "ICD-10-CM",
                "name": "WEAKNESS OF LEFT LEG"
            }
        ],
        "createdAt": "2014-10-19T21:02:17.949Z",
        "dateTime": "2011-05-02T04:00:00.000Z",
        "id": "5443d6ca71b5c7f1a243879e",
        "name": "Pain in left leg",
        "organization": {
            "href": "/medical/organizations/54dc427aaa6b4cb7d6203061",
            "id": "54dc427aaa6b4cb7d6203061",
            "name": "Cleveland Clinic"
        },
        "patient": {},
        "source": "emr-1-320",
        "updatedAt": "2014-10-19T21:02:17.949Z"
    },
    {
        "codes": [
            {
                "code": "38341003",
                "codeSystem": "2.16.840.1.113883.6.96",
                "codeSystemName": "SNOMED-CT",
                "name": "Hypertensive disorder"
            }
        ],
        "createdAt": "2014-10-19T21:02:17.949Z",
        "dateTime": "2011-03-02T05:00:00.000Z",
        "id": "5443d6ca71b5c7f1a24387a0",
        "name": "Hypertensive disorder",
        "organization": {
            "href": "/medical/organizations/54dc427aaa6b4cb7d6203061",
            "id": "54dc427aaa6b4cb7d6203061",
            "name": "Cleveland Clinic"
        },
        "patient": {},
        "source": "emr-1-320",
        "updatedAt": "2014-10-19T21:02:17.949Z"
    }
]
 
Suggest Edits

Procedures

Get a list of medical procedures associated with the user

 
gethttps://api.humanapi.co/v1/human/medical/procedures

Response Properties

Property
Type
Description

id

String

The id of the resource

source

String

The name of the originating service

updatedAt

Date

The time the record was updated on the Human API server

createdAt

Date

The time the record was created on the Human API server

dateTime

Date

(optional) The date of the procedure

device

String

(optional) Device Note: presence of this value is rare

deviceCodes

Array[Object]

(optional) Device codes Note: presence of this value is rare

name

String

(optional) Name of the procedure

performer

Object

(optional) See performer information)

specimen

String

(optional) Specimen related to the procedure (if applicable) Note: presence of this value is rare

specimenCodes

Array[Object]

(optional) Specimen codes Note: presence of this value is rare

organization

Object

(optional) See organizations object

codes

Array[Object]

(optional) See codes

Performer Object

Property
Type
Description

address

String

(optional) Address of the performer

organizationName

String

(optional) Name of the performer’s organization

phone

String

(optional) Phone number of the performer

# Get all procedures associated with the user
curl -H "Authorization: Bearer someToken" "https://api.humanapi.co/v1/human/medical/procedures"
A binary file was returned

You couldn't be authenticated

{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
# Returns a json array of procedures:
[
    {
        "id": "55e692d20c7deefb7cfe90f8",
        "createdAt": "2014-09-01T21:42:09.969Z",
        "updatedAt": "2014-09-01T21:42:10.072Z",
        "dateTime": "2014-02-11T09:30:00.000Z",
        "source": "emr-1-320",
        "device": null,
        "deviceCodes": [],
        "name": "HCHG CYSTOURETHROSCOPY",
        "organization": {
            "href": "/medical/organizations/53c050ac51c69003200aa998",
            "id": "53c050ac51c69003200aa998",
            "name": "Cleveland Clinic"
        },
        "performer": {
            "address": null,
            "organizationName": null,
            "phone": null
        },
        "specimen": null,
        "specimenCodes": [],
        "codes": [
            {
                "code": "52000",
                "codeSystem": "2.16.840.1.113883.6.12",
                "codeSystemName": "CPT-4",
                "name": "HCHG CYSTOURETHROSCOPY"
            }
        ]
    }
]
 
Suggest Edits

Profile

Get the medical health profile of the user. This includes observations about the user such as demographics, smoking status, alcohol use, etc.

 
gethttps://api.humanapi.co/v1/human/medical/profile

Response Properties

HTTP response 404

The profile endpoint may return a 404 response when there is no profile data to return.

Property
Type
Description

id

String

The id of the resource

source

String

The name of the originating service

updatedAt

Date

The time the record was updated on the Human API server

createdAt

Date

The time the record was created on the Human API server

demographics

Object

(optional) See demographics

alcohol

Object

(optional) The user’s alcohol usage

smoking

Object

(optional) The user’s smoking habits

Demographics Object

Property
Type
Description

address

Object

See address object

dob

String

(optional) The user’s date of birth e.g. "04/21/1965"

ethnicity

String

(optional) The ethnicity of the user e.g. "Not Hispanic of Latino"

gender

String

(optional) The user’s gender e.g. "male"

language

String

(optional) The user’s primary language e.g. "eng"

maritalStatus

String

(optional) The user’s marital status (eg: “married”, “single”)

name

Object

(optional) See name object

race

String

(optional) The user’s race e.g. "White"

ethnicityCodes

Array[Object]

(optional) CDC Race & Ethnicity and SNOMED CT Ethnicity codes: See codes

maritalStatusCodes

String

(optional) SNOMED CT Marital status codes: see codes object

genderCodes

String

(optional) SNOMED CT Gender codes: See codes

Address Object

Property
Type
Description

city

String

(optional) City of address e.g. "SAN FRANCISCO"

country

String

(optional) Country of address e.g. "US"

state

String

(optional) State of address e.g. "CA"

street

Array[String]

(optional) Street of address e.g. ["156 22ND AVE NW"]

zip

String

(optional) Zip of address e.g. "94123"

Alcohol Object

Property
Type
Description

use

String

(optional) The user’s alcohol usage e.g. “yes”, “no”

codes

Array[Object]

(optional) SNOMED CT Alcohol use codes: See codes

Smoking

Property
Type
Description

status

String

The user’s smoking status (e.g. “Never Smoker”)

codes

Array[Object]

SNOMED CT Smoking use codes: See codes

# Get user's medical profile
curl -H "Authorization: Bearer someToken" "https://api.humanapi.co/v1/human/medical/profile"
A binary file was returned

You couldn't be authenticated

{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
# Returns a json object as profile:
{
  "id": "54e344fa79192a2e4993dfda",
  "updatedAt": "2015-02-13T21:27:42.078Z",
  "createdAt": "2015-02-13T21:27:42.078Z",
  "demographics": {
    "address": {
      "city": "Vulcun City",
      "country": "USA",
      "state": "CA",
      "street": ["1 Milky way"],
      "zip": "94025"
    },
    "ethnicity": "Non Hispanic",
    "gender": "male",
    "language": "ENG",
    "maritalStatus": "married",
    "race": "White/Caucasian",
    "dob": "03-05-1985",
    "name": {
      "family": "Forrest",
      "given": ["Maxwell"]
    },
    "ethnicityCodes": [
      {
        "code" : "2186-5",
        "codeSystemName" : "RACE&ETHNICITY-CDC"
        "inferred" : true
      },
      {
        "code" : "2131-1",
        "codeSystemName" : "RACE&ETHNICITY-CDC",
        "inferred" : true
      },
      {
        "code" : "413655005",
        "codeSystemName" : "SNOMED-CT",
        "inferred" : true
      },
      {
        "code" : "413774005",
        "codeSystemName" : "SNOMED-CT",
        "inferred" : true
      }
    ],
    "maritalStatusCodes": [
      {
        "code" : "87915002",
        "codeSystemName" : "SNOMED-CT",
        "inferred" : true
      }
    ],
    "genderCodes": [
      {
        "code" : "703117000",
        "codeSystemName" : "SNOMED-CT",
        "inferred" : true
      }
    ]
  },
  "alcohol": {
    "use": "yes",
    "codes": [
      {
        "code" : "704197006",
        "codeSystemName" : "SNOMED-CT",
        "inferred" : true
      }
    ]
  },
  "smoking": {
    "status": "Never smoker",
    "codes": [
      {
        "code" : "266919005",
        "codeSystemName" : "SNOMED-CT",
        "inferred" : true
      }
    ]
  }
}
 
Suggest Edits

Test Results

Get a list of medical lab results for a user.

 
gethttps://api.humanapi.co/v1/human/medical/test_results

Response Properties

Property
Type
Description

id

String

The id of the resource

source

String

The name of the originating service

updatedAt

Date

The time the record was updated on the Human API server

createdAt

Date

The time the record was created on the Human API server

components

Array[Object]

A list of components of the test (See component below)

name

String

The name of the test preformed e.g. ‘COMPREHENSIVE METABOLIC PANEL’, 'LIPID PANEL’, 'URINE CULTURE’

device

String

(optional) Device name Note: presence of this value is rare

patient

Object

Patient information (“name” and other optional attributes)

specimen

String

(optional) Specimen related to the procedure Note: presence of this value is rare

orderedBy

String

(optional) The name of the ordering physician or entity

recipients

Array[Object]

(optional) See recipient object Note: presence of this value is rare

resultDateTime

Date

(optional) The date of the test result

status

String

(optional) The status of the test result (e.g. 'Final result’, 'Edited’, 'Edited Result - FINAL’)

allResults

Array[Object]

[Deprecated] Use components instead

comments

String

(optional) Comments for the test result

narrative

String

(optional) Narrative for the test result

impression

String

(optional) Impression for the test result

transcriptions

String

(optional) Transcriptions for the test result

codes

Array[Object]

(optional) See codes

Component Object

Property
Type
Description

name

String

(optional) The name of the test component (e.g. 'Potassium’, 'MCHC’, 'MCV’)

value

String

(optional) The test result value

unit

String

(optional) The unit of the value - e.g. 'mg/dL’, ’%’, 'mmol/L’

low

String

(optional) The low value for the component

high

String

(optional) The high value for the component

refRange

String

(optional) The reference range for the value - if provided (e.g. 'Negative’, ’>60’, ’<150’)

componentComments

String

(optional) Comments provided for the component

codes

Array[Object]

(optional) See codes

Recipient Object

Property
Type
Description

objectID

String

The id of the recipient e.g. "856983"

name

String

(optional) The name of the recipient

isPCP

Boolean

(optional) Indicates if the provider is the Primary Care Provider of the user e.g. true

recipTemplate

String

(optional) The recipient template e.g. 'WPMessageRecipientTemplateUnknown’

# Get all test results associated with the user
curl -H "Authorization: Bearer someToken" "https://api.humanapi.co/v1/human/medical/test_results"
A binary file was returned

You couldn't be authenticated

{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
# Returns a json array of test results:
[  {
    "allResults": [ ],
    "components": [
        {
            "codes": [],
            "high": "8.3",
            "low": "5.7",
            "name": "Protein Total, Serum",
            "unit": "g/dL",
            "value": "7.1"
        },
        {
            "codes": [],
            "high": "5.0",
            "low": "3.4",
            "name": "Albumin (Serum)",
            "unit": "g/dL",
            "value": "4.3"
        },
        {
            "codes": [],
            "high": "3.9",
            "low": "1.8",
            "name": "Globulin Serum",
            "unit": "g/dL",
            "value": "2.8"
        }
    ],
    "codes": [
        {
            "codeSystem": "2.16.840.1.113883.6.1",
            "codeSystemName": "LOINC",
            "name": "DIAGNOSIS"
        }
    ],
    "createdAt": "2014-10-30T21:02:17.956Z",
    "id": "546d44478a6d23e01a72865a",
    "name": "LAB TOTAL PROTEIN+ALB",
    "orderedBy": "James Kirk, MD",
    "organization": {
        "href": "/medical/organizations/53c050ac51c69003200aa998",
        "id": "53c050ac51c69003200aa998",
        "name": "Cleveland Clinic"
    },
    "patient": {
        "name": "Maxwell Forrest"
    },
    "recipients": [
        {
            "isPCP": true,
            "name": "Jean-Luc Picard, MD",
            "objectID": "50006",
            "recipTemplate": "WPMessageRecipientTemplateUnknown"
        }
    ],
    "resultDateTime": "2010-09-10T04:00:00.000Z",
    "source": "emr-1-320",
    "status": "Final result",
    "updatedAt": "2014-10-20T21:02:17.956Z"
}]
 
Suggest Edits

Vitals

Get the user’s vitals readings

 
gethttps://api.humanapi.co/v1/human/medical/vitals

Response Properties

Property
Type
Description

id

String

The Id of the resource

source

String

The name of the originating service

updatedAt

Date

The time the record was updated on the Human API server

createdAt

Date

The time the record was created on the Human API server

name

String

(optional) Name representing the set of vitals

dateTime

String

(optional) The date of the vitals reading

author

String

(optional) The name of the vitals reading author (e.g. doctor)

codes

Array[Object]

(optional) A list of all codes. See codes object

results

Array[Object]

(optional) A list of all results. See results object

ccd

Object

See CCD object

organization

Object

See organizations object

Results Object

Property
Type
Description

name

String

(optional) The name of the test component e.g. ‘HEIGHT’, 'WEIGHT’, 'BODY TEMPERATURE’

value

String

(optional) The test result value

unit

String

(optional) The unit of the value - if provided e.g. 'kg’, ’%’, 'Cel’

codes

Array[Object]

(optional) See codes

normalizedName

String

(optional) The normalized name of the measurement e.g. "Body Mass Index (BMI)"

raw

Object

(optional) Un-normalized content as represented from the source. See raw object

values

Array[Object]

(optional) Array of objects containing values, which are converted into standard units. Useful for showing data on a graph, or performing math functions.

CCD Object

Property
Type
Description

id

String

Id of the CCD

href

String

URL to retrieve CCD details

Raw object

Property
Type
Description

value

String

(optional) Value of the result

unit

String

(optional) Unit of the result

name

String

(optional) Name of the result

codes

Array[Object]

(optional) See codes

Value object

Property
Type
Description

value

Float

(optional) Value of result

unit

String

(optional) Unit of result

# Get all vitals readings associated with the user
curl -H "Authorization: Bearer someToken" "https://api.humanapi.co/v1/human/medical/vitals"
A binary file was returned

You couldn't be authenticated

{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
# Returns a json array of vitals:
[
    {
        "author": "Maxwell Forrest",
        "createdAt": "2014-09-02T05:50:22.654Z",
        "dateTime": "2014-08-18T16:04:00.000Z",
        "id": "55e6914a0c7deefb7cfe90f6",
        "organization": {
            "href": "/medical/organizations/53c050ac51c69003200aa998",
            "id": "53c050ac51c69003200aa998",
            "name": "Cleveland Clinic"
        },
        "results": [
            {
                "codes": [
                    {
                        "code": "8480-6",
                        "codeSystem": "2.16.840.1.113883.6.1",
                        "codeSystemName": "LOINC",
                        "name": "SYSTOLIC BLOOD PRESSURE"
                    }
                ],
                "name": "SYSTOLIC BLOOD PRESSURE",
                "unit": "mm[Hg]",
                "value": "102"
            },
            {
                "codes": [
                    {
                        "code": "8462-4",
                        "codeSystem": "2.16.840.1.113883.6.1",
                        "codeSystemName": "LOINC",
                        "name": "DIASTOLIC BLOOD PRESSURE"
                    }
                ],
                "name": "DIASTOLIC BLOOD PRESSURE",
                "unit": "mm[Hg]",
                "value": "70"
            },
            {
                "codes": [
                    {
                        "code": "8867-4",
                        "codeSystem": "2.16.840.1.113883.6.1",
                        "codeSystemName": "LOINC",
                        "name": "HEART RATE"
                    }
                ],
                "name": "HEART RATE",
                "unit": "/min",
                "value": "80"
            },
            {
                "codes": [
                    {
                        "code": "8302-2",
                        "codeSystem": "2.16.840.1.113883.6.1",
                        "codeSystemName": "LOINC",
                        "name": "HEIGHT"
                    }
                ],
                "name": "HEIGHT",
                "unit": "cm",
                "value": "157.5"
            },
            {
                "codes": [
                    {
                        "code": "3141-9",
                        "codeSystem": "2.16.840.1.113883.6.1",
                        "codeSystemName": "LOINC",
                        "name": "WEIGHT"
                    }
                ],
                "name": "WEIGHT",
                "unit": "kg",
                "value": "61.871"
            },
            {
                "codes": [
                    {
                        "code": "39156-5",
                        "codeSystem": "2.16.840.1.113883.6.1",
                        "codeSystemName": "LOINC",
                        "name": "BODY MASS INDEX"
                    }
                ],
                "name": "BODY MASS INDEX",
                "unit": "kg/m2",
                "value": "24.94"
            }
        ],
        "source": "emr-1-320",
        "updatedAt": "2014-09-02T05:50:22.654Z"
    }
]
 
Suggest Edits

CCD

Returns full CCDs available for the user including the raw xml

 
gethttps://api.humanapi.co/v1/human/medical/ccds

Click here for full XML example (Chrome or Firefox only)

Returns single CCD raw payload in XML format
GET https://api.humanapi.co/v1/human/medical/ccds/{id}/raw

Response Properties

Property
Type
Description

id

String

The id of the resource

source

String

The name of the originating service

updatedAt

Date

The time the record was updated on the Human API server

createdAt

Date

The time the record was created on the Human API server

dateTime

String

(optional) The date of the CCD

author

String

(optional) CCD author’s name

organization

Object

(optional) See organizations object

Response Headers (Raw CCD)

Header
Value

Content-Type

text/xml

# Get all ccds associated with the user
curl -H "Authorization: Bearer someToken" "https://api.humanapi.co/v1/human/medical/ccds"
A binary file was returned

You couldn't be authenticated

{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
# Returns a json array of ccds:
[{
  "id": "54e35f5de0b3d53af2c65921",
  "source": "emr-1-320",
  "updatedAt": "2015-02-17T16:54:24.778Z",
  "createdAt": "2015-02-10T00:09:36.679Z",
  "dateTime": "2014-04-14T18:38:44.000Z",
  "author": "John Smith",
  "organization": {
    "id": "53c050ac51c69003200aa998",
    "name": "Cleveland Clinic",
    "href": "/medical/organizations/53c050ac51c69003200aa998"
  }
}]
 
Suggest Edits

Demographics

Get a list of demographics data associated with the user

 
gethttps://api.humanapi.co/v1/human/medical/demographics

Response Properties

Property
Type
Description

id

String

Id of the resource

updatedAt

Date

Time the record was updated on the Human API server

createdAt

Date

Time the record was created on the Human API server

name

Object

(optional) See name object

dob

String

(optional) Date of birth of the patient e.g. "05/20/1971"

dobDateTime

String

(optional) Date of birth of the patient e.g. "1971-05-20T00:00:00.000Z"

ethnicity

String

(optional) Ethnicity of the patient e.g. "Not Hispanic or Latino"

ethnicityCodes

Array[Object]

(optional) CDC Race & Ethnicity and SNOMED CT Ethnicity codes: See codes

gender

String

(optional) Gender of the patient e.g. "male"

genderCodes

Array[Object]

(optional) SNOMED CT Gender codes: See codes

language

String

(optional) Preferred spoken language of the patient e.g. "eng"

languageCodes

Array[Object]

(optional) SNOMED CT Language codes: See codes

maritalStatus

String

(optional) Marital status of the patient e.g. "married"

maritalStatusCodes

Array[Object]

(optional) SNOMED CT Marital codes: See codes

provider

Object

See Provider Object details below

organization

Object

See organizations

race

String

(Optional) Race of the patient e.g. "White"

raceCodes

Array[Object]

(optional) SNOMED CT Race codes: See codes

codes

Array[Object]

(optional) See codes

ccd

Object

(optional) See CCD Object details below

CCD Object

Property
Type
Description

href

String

Link to a more detailed CCD object

id

String

id of the CCD

Provider Object

Property
Type
Description

organization

String

(optional) The name of the medical source

address

Object

(optional) See Address Object below

Address Object (from Provider Object)

Property
Type
Description

city

String

(optional) City of the provider e.g. "San Francisco"

country

String

(optional) Country of the provider e.g. "USA"

state

String

(optional) State of the provider e.g. "CA"

zip

String

(optional) Zip code of the provider e.g. "94156"

street

Array[String]

(optional) Street and number of the address e.g. '["123 Lucas Drive"]'

# Get all demographics data associated with the user
# Note that the demo access token currently returns an empty array. The results in the JSON tab are fictional values. 
curl -H "Authorization: Bearer someToken" "https://api.humanapi.co/v1/human/medical/demographics"
A binary file was returned

You couldn't be authenticated

{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
# Returns a json array of demographics:
[
    {
        "address": {
            "city": "SAN FRANCISCO",
            "country": "USA",
            "state": "CA",
            "street": [
                "123 Lucas Drive"
            ],
            "zip": "95131"
        },
        "ccd": {
            "href": "/medical/ccds/5b3056dd711be0bff640e105",
            "id": "5c3056db711b20bff610e105"
        },
        "createdAt": "2018-07-12T20:16:36.159Z",
        "dob": "05/20/1971",
        "dobDateTime": "1971-05-20T00:00:00.000Z",
        "ethnicity": "Not Hispanic or Latino",
        "ethnicityCodes": [
            {
                "code": "2186-5",
                "codeSystemName": "RACE&ETHNICITY-CDC",
                "inferred": true
            },
            {
                "code": "2131-1",
                "codeSystemName": "RACE&ETHNICITY-CDC",
                "inferred": true
            }
        ],
        "gender": "male",
        "genderCodes": [
            {
                "code": "703117000",
                "codeSystemName": "SNOMED-CT",
                "inferred": true
            }
        ],
        "id": "5b47b7344e72eb0022b9b5a2",
        "language": "eng",
        "languageCodes": [
            {
                "code": "315570003",
                "codeSystemName": "SNOMED-CT",
                "inferred": true
            }
        ],
        "maritalStatus": "married",
        "maritalStatusCodes": [
            {
                "code": "87915002",
                "codeSystemName": "SNOMED-CT",
                "inferred": true
            }
        ],
        "name": {
            "family": "Archer",
            "given": [
                "Archer",
                "B"
            ]
        },
        "organization": {
            "href": "/medical/organizations/54dc427aaa6b4cb7d620302f",
            "id": "54dc427aaa6b4cb7d620302f",
            "name": "Starfleet Medical"
        },
        "provider": {
            "address": {
                "city": "San Francisco",
                "country": "USA",
                "state": "CA",
                "zip": "94156"
            },
            "organization": "Starfleet Medical"
        },
        "race": "White",
        "raceCodes": [
            {
                "code": "185984009",
                "codeSystemName": "SNOMED-CT",
                "inferred": true
            },
            {
                "code": "2106-3",
                "codeSystemName": "RACE&ETHNICITY-CDC",
                "inferred": true
            }
        ],
        "updatedAt": "2018-07-12T20:16:36.159Z"
    }
]
 
Suggest Edits

Social History

Get a list of demographics data associated with the user

 
gethttps://api.humanapi.co/v1/human/medical/social_history

Response Properties

Property
Type
Description

id

String

Id of the resource

updatedAt

Date

Time the record was updated on the Human API server

createdAt

Date

Time the record was created on the Human API server

organization

Object

See organizations

datetime

Date

(Optional) Datetime associated with the social history record

entries

Array[Object]

(optional) Array of entries associated with social history

codes

Array[Object]

(optional) See codes

ccd

Object

(optional) See CCD Object details below

Entry Object

Property
Type
Description

value

String

(optional) Value of the social history entry

datetime

Date

(optional) Datetime of the social history entry

name

String

(optional) Name of the social history entry

Codes

Array[Object]

(optional) See codes

CCD Object

Property
Type
Description

href

String

Link to a more detailed CCD object

id

String

id of the CCD

# Get all social history data associated with the user
# Note that the demo access token currently returns an empty array. The results in the JSON tab are fictional values.
curl -H "Authorization: Bearer someToken" "https://api.humanapi.co/v1/human/medical/social_history"
A binary file was returned

You couldn't be authenticated

{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
// Not available at this time
 
Suggest Edits

Wellness API Introduction

 

Enterprise feature

If you are interested in using the Wellness API, please contact our Sales Team here for more information: https://www.humanapi.co/request-call

The Wellness API provides a standardized way to get data from a variety of wellness sources.

Common Record Properties

Regardless of the type, most wellness data records have a few standard properties:

Property
Type
Description

id

String

The id of the record

humanId

String

Unique Human API user identifier

source

String

The name of the originating source (all lowercase, no spaces)

sourceData

String

Unique properties from a source that do not fit the main data model

createdAt

Date

The time the record was created on the Human API server

updatedAt

Date

The time the record was updated on the Human API server

If you have not already, we highly recommend reading the Patterns and Conventions to familiarize yourself with how to filter for these parameters so you only get the data that you need. In general, data records contain information from the data source that has been normalized to standard units and parameters. Any source specific information will be passed through via the optional sourceData object.

For the full documentation including step-by-step implementation guides and information on data sources, see the Web Guide.

Wellness Network

The wellness network indicates what applications or sources Human API has integrations with. In addition, it advises which datatypes are available with respect to the sources.

Wellness network

 
Suggest Edits

Activities

Activities are specific types of physical activities that occur during a given period of time.

 
gethttps://api.humanapi.co/v1/human/activities

Response Properties

Property
Type
Description

id

String

The id of the resource.

userId

String

[deprecated - use humanId]

humanId

String

Unique user identifier

startTime

Date

The start time of the activity in UTC time

endTime

Date

The end time of the activity in UTC time

tzOffset

String

The offset from UTC time in +/-hh:mm (e.g. -04:00)

type

String

The type of activity, such as walking, running, cycling

source

String

The name of the originating service

duration

Number

The duration in seconds

distance

Number

The distance in meters

steps

Number

The number of steps taken during the activity

calories

Number

The number of estimated calories burned during the activity

sourceData

Object

Additional data from the source that does not fit into the Human API model

timeSeries

Object

Time series of data such as heart rate, gps location, distance, etc.

Query Parameters

Parameter
Description

time_series

Add the query parameter time_series=true to retrieve the time series data if available.

The timeSeries object can have multiple embedded objects. Examples of possible objects include properties such as “heartRate”, “gps”, and “distance”.

# Get all activities associated with the user
curl "https://api.humanapi.co/v1/human/activities?access_token=demo"

# Get an activity by id
curl "https://api.humanapi.co/v1/human/activities/52e20cb2fff56aac62000001?access_token=demo"
A binary file was returned

You couldn't be authenticated

{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
# Returns a json array of activities:
[{
  "id": "5510259685cc310900f67753",
  "userId": "52e20cb2fff56aac62000001",
  "startTime": "2015-03-23T14:29:34.000Z",
  "endTime": "2015-03-23T14:30:17.000Z",
  "tzOffset": "-04:00",
  "type": "walking",
  "source": "moves",
  "duration": 43,
  "distance": 29,
  "steps": 57,
  "calories": 0,
  "sourceData": {
    "manual": false
  },
  "createdAt": "2015-03-23T14:39:19.065Z",
  "updatedAt": "2015-03-23T14:39:19.065Z",
  "humanId": "5dc2527186aaf9de560e5841f1a44bd6"
}, {
  "id": "550fe4b58c34cc6661f46f66",
  "userId": "52e20cb2fff56aac62000001",
  "startTime": "2015-03-23T08:19:24.000Z",
  "endTime": "2015-03-23T08:31:26.000Z",
  "tzOffset": "+00:00",
  "type": "running",
  "source": "runkeeper",
  "duration": 722,
  "distance": 1506.71611260169,
  "steps": 0,
  "calories": 118,
  "sourceData": {},
  "createdAt": "2015-03-23T14:32:27.978Z",
  "updatedAt": "2015-03-23T14:32:27.978Z",
  "humanId": "5dc2527186aaf9de560e5841f1a44bd6"
}, {
  "id": "550fbaa568d29c4133b6531a",
  "userId": "52e20cb2fff56aac62000001",
  "startTime": "2015-03-23T00:01:00.000Z",
  "endTime": "2015-03-23T06:32:00.000Z",
  "tzOffset": "-07:00",
  "type": "unknown",
  "source": "jawbone",
  "duration": 480,
  "distance": 669,
  "steps": 949,
  "calories": 25.2287654541,
  "sourceData": {},
  "createdAt": "2015-03-23T07:03:01.454Z",
  "updatedAt": "2015-03-23T13:36:29.756Z",
  "humanId": "5dc2527186aaf9de560e5841f1a44bd6"
}]

# Returns a json object as activity by id:
{
  "id": "550fbaa568d29c4133b6531a",
  "userId": "52e20cb2fff56aac62000001",
  "startTime": "2015-03-23T00:01:00.000Z",
  "endTime": "2015-03-23T06:32:00.000Z",
  "tzOffset": "-07:00",
  "type": "unknown",
  "source": "jawbone",
  "duration": 480,
  "distance": 669,
  "steps": 949,
  "calories": 25.2287654541,
  "sourceData": {},
  "createdAt": "2015-03-23T07:03:01.454Z",
  "updatedAt": "2015-03-23T13:36:29.756Z",
  "humanId": "5dc2527186aaf9de560e5841f1a44bd6"
}
 
Suggest Edits

Activity Summaries

Get a list of daily activity summaries reported by the data sources.

 
gethttps://api.humanapi.co/v1/human/activities/summaries

Returns a list of activity summaries
GET https://api.humanapi.co/v1/human/activities/summaries

Returns a single activity summary
GET https://api.humanapi.co/v1/human/activities/summaries/{id}

Returns a single activity summary by date
GET https://api.humanapi.co/v1/human/activities/summaries/{YYYY-MM-DD}

Response Properties

Property
Type
Description

id

String

The id of the resource

userId

String

[deprecated - use humanId]

humanId

String

Unique user identifier

date

Date

The date of the activity (format: YYYY-MM-DD)

source

String

The name of the originating service

duration

Number

The duration in seconds

distance

Number

The distance in meters

steps

Number

The number of steps taken during the activity

vigorous

Number

The number of minutes of vigorous activity

moderate

Number

The number of minutes of moderate activity

light

Number

The number of minutes of light activity

sedentary

Number

The number of minutes of sedentary activity

calories

Number

The number of estimated calories burned during the activity

sourceData

Object

Additional data from the source that does not fit into the Human API model.

createdAt

Date

The time the activity was created on the Human API server

updatedAt

Date

The time the activity was updated on the Human API server

# Get all activity summaries associated with the user
curl "https://api.humanapi.co/v1/human/activities/summaries?access_token=demo"

# Get an activity summary by id
curl "https://api.humanapi.co/v1/human/activities/summaries/550f597085cc310900c73f72?access_token=demo"

# Returns a single activity summary by date
curl "https://api.humanapi.co/v1/human/activities/summaries/{YYYY-MM-DD}"
A binary file was returned

You couldn't be authenticated

{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
# Returns a json array of activities summaries:
[{
  "id": "550fe4b68c34cc6661f46f7f",
  "userId": "52e20cb2fff56aac62000001",
  "date": "2015-03-23",
  "duration": 722,
  "distance": 1506.71611260169,
  "steps": 0,
  "calories": 118,
  "source": "runkeeper",
  "vigorous": 0,
  "moderate": 0,
  "light": 0,
  "sedentary": 0,
  "sourceData": {},
  "createdAt": "2015-03-23T18:02:29.578Z",
  "updatedAt": "2015-03-23T18:02:29.578Z",
  "humanId": "5dc2527186aaf9de560e5841f1a44bd6"
}, {
  "id": "550fb80568d29c4133b5e134",
  "userId": "52e20cb2fff56aac62000001",
  "date": "2015-03-23",
  "duration": 108,
  "distance": 171,
  "steps": 207,
  "calories": 12.1920387848,
  "source": "jawbone",
  "vigorous": 0,
  "moderate": 0,
  "light": 0,
  "sedentary": 254,
  "sourceData": {},
  "createdAt": "2015-03-23T06:51:49.355Z",
  "updatedAt": "2015-03-23T17:48:16.610Z",
  "humanId": "5dc2527186aaf9de560e5841f1a44bd6"
}, {
  "calories": 2720,
  "createdAt": "2015-03-22T01:24:07.212Z",
  "date": "2015-03-22",
  "distance": 9410,
  "duration": 23100,
  "humanId": "5dc2527186aaf9de560e5841f1a44bd6",
  "id": "5600adb7d5f967080013c1f0",
  "light": 341,
  "moderate": 3,
  "sedentary": 1055,
  "source": "fitbit",
  "sourceData": {
      "floors": 0,
      "tracker": {
          "calories": 2720,
          "distance": 9409.92,
          "elevation": 0,
          "floors": 0,
          "steps": 12224
      }
  },
  "steps": 12224,
  "updatedAt": "2015-10-30T08:11:23.359Z",
  "userId": "52e20cb2fff56aac62000001",
  "vigorous": 41
  }
]


# Returns a json object as activity summary by id:
{
  "id": "550f597085cc310900c73f72",
  "userId": "52e20cb2fff56aac62000001",
  "date": "2015-03-23",
  "duration": 0,
  "distance": 0,
  "steps": 0,
  "calories": 0,
  "source": "moves",
  "vigorous": 0,
  "moderate": 0,
  "light": 0,
  "sedentary": 0,
  "sourceData": {},
  "createdAt": "2015-03-23T00:08:16.979Z",
  "updatedAt": "2015-03-23T17:44:05.818Z",
  "humanId": "5dc2527186aaf9de560e5841f1a44bd6"
}
 
Suggest Edits

Blood Glucose

Get the blood glucose measurement from a specific point in time.

 
gethttps://api.humanapi.co/v1/human/blood_glucose

Returns the latest blood glucose reading
GET https://api.humanapi.co/v1/human/blood_glucose

Returns all blood glucose readings
GET https://api.humanapi.co/v1/human/blood_glucose/readings

Response Properties

Property
Type
Description

id

String

The id of the resource.

userId

String

[deprecated - use humanId]

humanId

String

Unique user identifier

timestamp

Date

The original date and time of the measurement

tzOffset

String

The offset from UTC time in +/-hh:mm (e.g. -04:00)

source

String

The source service for the measurement, where it was created

value

Number

The value of the measurement in the unit specified

unit

String

The unit of the measurement value

notes

String

User-created notes

mealTag

String

Indication if value was captured before/after a meal

medicationTag

String

Indication if value was captured before/after taking medication

createdAt

Date

The time the measurement was created on the Human API server

updatedAt

Date

The time the measurement was updated on the Human API server

# Get the latest blood glucose measurement associated with the user
curl "https://api.humanapi.co/v1/human/blood_glucose?access_token=demo"

# Returns all blood glucose readings
curl "https://api.humanapi.co/v1/human/blood_glucose/readings?access_token=demo"


A binary file was returned

You couldn't be authenticated

{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
# Returns a json object of blood glucose:
{
  "id": "54be39e6c3fa43b8057d59fc",
  "userId": "52e20cb2fff56aac62000001",
  "timestamp": "2015-01-20T12:20:04.000Z",
  "tzOffset": "-07:00",
  "value": 94,
  "unit": "mg/dL",
  "source": "ihealth",
  "sourceData": {},
  "createdAt": "2015-03-16T23:48:43.696Z",
  "updatedAt": "2015-03-16T23:48:43.696Z",
  "humanId": "5dc2527186aaf9de560e5841f1a44bd6"
}
 
Suggest Edits

Blood Oxygen

Get the blood oxygen measurement from a specific point in time.

 
gethttps://api.humanapi.co/v1/human/blood_oxygen

Returns the latest blood oxygen reading
GET https://api.humanapi.co/v1/human/blood_oxygen

Returns all blood oxygen readings
GET https://api.humanapi.co/v1/human/blood_oxygen/readings

Response Properties

Property
Type
Description

id

String

The id of the resource.

userId

String

[deprecated - use humanId]

humanId

String

Unique user identifier

timestamp

Date

The original date and time of the measurement

tzOffset

String

The offset from UTC time in +/-hh:mm (e.g. -04:00)

source

String

The source service for the measurement, where it was created

value

Number

The duration in seconds

unit

String

The unit of the measurement value

notes

String

User created notes

distance

Number

The value of the measurement in the unit specified

createdAt

Date

The time the measurement was created on the Human API server

updatedAt

Date

The time the measurement was updated on the Human API server

# Returns the latest blood oxygen reading
curl "https://api.humanapi.co/v1/human/blood_oxygen?access_token=demo"

# Returns all blood oxygen readings
curl "https://api.humanapi.co/v1/human/blood_oxygen/readings?access_token=demo"


A binary file was returned

You couldn't be authenticated

{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
# Returns a json object of blood oxygen:
{
  "id": "54d1f018810a5ba429951b07",
  "userId": "52e20cb2fff56aac62000001",
  "timestamp": "2015-01-26T06:58:37.000Z",
  "tzOffset": "-07:00",
  "value": 99,
  "unit": "SpO2(%)",
  "source": "withings",
  "sourceData": {},
  "createdAt": "2015-02-04T10:10:32.691Z",
  "updatedAt": "2015-02-04T10:10:32.691Z",
  "humanId": "5dc2527186aaf9de560e5841f1a44bd6"
}
 
Suggest Edits

Blood Pressure

Get the blood pressure measurement from a specific point in time.

 
gethttps://api.humanapi.co/v1/human/blood_pressure

Returns the latest blood pressure reading
GET https://api.humanapi.co/v1/human/blood_pressure

Returns all blood pressure readings
GET https://api.humanapi.co/v1/human/blood_pressure/readings

Response Properties

Property
Type
Description

id

String

The id of the resource.

userId

String

[deprecated - use humanId]

humanId

String

Unique user identifier

timestamp

Date

The original date and time of the measurement

tzOffset

String

The offset from UTC time in +/-hh:mm (e.g. -04:00)

source

String

The source service for the measurement, where it was created

unit

String

The unit of the measurement value

heartRate

String

The heart rate in BPM captured at the time of measurement

systolic

String

The systolic value captured at the time of measurement

diastolic

String

The diastolic value captured at the time of measurement

createdAt

Date

The time the measurement was created on the Human API server

updatedAt

Date

The time the measurement was updated on the Human API server

# Returns the latest blood pressure reading
curl "https://api.humanapi.co/v1/human/blood_pressure?access_token=demo"

# Returns all blood pressure readings
curl "https://api.humanapi.co/v1/human/blood_pressure/readings?access_token=demo"
A binary file was returned

You couldn't be authenticated

{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
# Returns a json object of blood pressure:
{
  "id": "550b8a8e834dd16f259683b1",
  "userId": "52e20cb2fff56aac62000001",
  "timestamp": "2015-03-19T22:48:26.000Z",
  "tzOffset": "-07:00",
  "systolic": 117,
  "diastolic": 76,
  "unit": "mmHg",
  "heartRate": 66,
  "source": "ihealth",
  "createdAt": "2015-03-20T02:48:46.925Z",
  "updatedAt": "2015-03-20T02:48:46.925Z",
  "humanId": "5dc2527186aaf9de560e5841f1a44bd6"
}
 
Suggest Edits

Body Mass Index (BMI)

Get the BMI measurement from a specific point in time.

 
gethttps://api.humanapi.co/v1/human/bmi

Returns the latest bmi reading
GET https://api.humanapi.co/v1/human/bmi

Returns all bmi readings
GET https://api.humanapi.co/v1/human/bmi/readings

Response Properties

Property
Type
Description

id

String

The id of the resource.

userId

String

[deprecated - use humanId]

humanId

String

Unique user identifier

timestamp

Date

The original date and time of the measurement

tzOffset

String

The offset from UTC time in +/-hh:mm (e.g. -04:00)

source

String

The source service for the measurement, where it was created

unit

String

The unit of the measurement value

value

Number

The value of the measurement in the unit specified

createdAt

Date

The time the measurement was created on the Human API server

updatedAt

Date

The time the measurement was updated on the Human API server

# Returns the latest bmi reading
curl "https://api.humanapi.co/v1/human/bmi?access_token=demo"

# Returns all bmi readings
curl "https://api.humanapi.co/v1/human/bmi/readings?access_token=demo"
A binary file was returned

You couldn't be authenticated

{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
# Returns a json object of bmi:
{
  "id": "5506f5080ba9b35f0af6cc89",
  "userId": "52e20cb2fff56aac62000001",
  "timestamp": "2015-03-16T23:59:59.000Z",
  "tzOffset": "-07:00",
  "value": 30.26,
  "unit": "kg/m2",
  "source": "fitbit",
  "sourceData": {},
  "createdAt": "2015-03-16T15:21:44.304Z",
  "updatedAt": "2015-03-16T15:24:48.492Z",
  "humanId": "5dc2527186aaf9de560e5841f1a44bd6"
}
 
Suggest Edits

Body Fat

Get the body fat measurement from a specific point in time.

 
gethttps://api.humanapi.co/v1/human/body_fat

Returns a body fat reading
GET https://api.humanapi.co/v1/human/body_fat

Returns all body fat readings
GET https://api.humanapi.co/v1/human/body_fat/readings

Response Properties

Property
Type
Description

id

String

The id of the resource.

userId

String

[deprecated - use humanId]

humanId

String

Unique user identifier

timestamp

Date

The original date and time of the measurement

tzOffset

String

The offset from UTC time in +/-hh:mm (e.g. -04:00)

source

String

The source service for the measurement, where it was created

unit

String

The unit of the measurement value

value

Number

The value of the measurement in the unit specified

createdAt

Date

The time the measurement was created on the Human API server

updatedAt

Date

The time the measurement was updated on the Human API server

# Returns the latest body fat reading
curl "https://api.humanapi.co/v1/human/body_fat?access_token=demo"

# Returns all body fat readings
curl "https://api.humanapi.co/v1/human/body_fat/readings?access_token=demo"
A binary file was returned

You couldn't be authenticated

{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
# Returns a json object of body fat:
{
  "id": "54ed75ccd9f8e13b13eaf17f",
  "userId": "52e20cb2fff56aac62000001",
  "timestamp": "2015-02-25T07:09:52.000Z",
  "tzOffset": "-07:00",
  "value": 18.695,
  "unit": "percent",
  "source": "withings",
  "sourceData": {},
  "createdAt": "2015-02-26T05:21:01.021Z",
  "updatedAt": "2015-02-26T05:21:01.021Z",
  "humanId": "5dc2527186aaf9de560e5841f1a44bd6"
}
 
Suggest Edits

Heart Rate

Get the heart rate measurement from a specific point in time.

 
gethttps://api.humanapi.co/v1/human/heart_rate

Returns a heart rate reading
GET https://api.humanapi.co/v1/human/heart_rate

Returns all heart rate readings
GET https://api.humanapi.co/v1/human/heart_rate/readings

Response Properties

Property
Type
Description

id

String

The id of the resource.

userId

String

[deprecated - use humanId]

humanId

String

Unique user identifier

timestamp

Date

The original date and time of the measurement

tzOffset

String

The offset from UTC time in +/-hh:mm (e.g. -04:00)

source

String

The source service for the measurement, where it was created

value

Number

The value of the measurement in the unit specified

createdAt

Date

The time the measurement was created on the Human API server

updatedAt

Date

The time the measurement was updated on the Human API server

# Returns the latest heart rate reading
curl "https://api.humanapi.co/v1/human/heart_rate?access_token=demo"

# Returns all heart rate readings
curl "https://api.humanapi.co/v1/human/heart_rate/readings?access_token=demo"
A binary file was returned

You couldn't be authenticated

{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
# Returns a json object of heart rate:
{
  "id": "550b8a8e834dd16f259683b2",
  "userId": "52e20cb2fff56aac62000001",
  "timestamp": "2015-03-19T22:48:26.000Z",
  "tzOffset": "-07:00",
  "value": 66,
  "unit": "bpm",
  "source": "ihealth",
  "sourceData": {},
  "createdAt": "2015-03-20T02:48:46.945Z",
  "updatedAt": "2015-03-20T02:48:46.945Z",
  "humanId": "5dc2527186aaf9de560e5841f1a44bd6"
}
 
Suggest Edits

Heart Rate Summaries

Get a list of daily heart rate summaries for a user.

 
gethttps://api.humanapi.co/v1/human/heart_rate/summaries

Returns a list of heart rate summaries
GET https://api.humanapi.co/v1/human/heart_rate/summaries

Returns a heart rate summary by id
GET https://api.humanapi.co/v1/human/heart_rate/summaries/{id}

Returns a heart rate summary by date
GET https://api.humanapi.co/v1/human/heart_rate/summaries/{YYYY-MM-DD}

Response Properties

Property
Type
Description

id

String

The id of the resource.

userId

String

[deprecated - use humanId]

humanId

String

Unique user identifier

zones

Array[Object]

Array of heart rate zones for the day (see ‘Zone Object’ below)

date

Date

The date that the heart rate summary corresponds to (format: YYYY-MM-DD)

source

String

The source service for the measurement, where it was created

value

Number

The value of the measurement in the unit specified

restingHR

Number

The user’s resting heart rate for the day in beats per minute (optional)

averageHR

Number

The user’s average heart rate for the day in beats per minute (optional)

maxHR

Number

The maximum heart rate reading recorded for the day in beats per minute (optional)

minHR

Number

The maximum heart rate reading recorded for the day in beats per minute (optional)

sourceData

Object

Additional data from the source that does not fit into the Human API model

createdAt

Date

The time the measurement was created on the Human API server

updatedAt

Date

The time the measurement was updated on the Human API server

# Get the heart rate summaries associated with the user
curl "https://api.humanapi.co/v1/human/heart_rate/summaries?access_token=demo"

# Get heart rate summary by id
curl "https://api.humanapi.co/v1/human/heart_rate/summaries/550b8a8e834dd16f259683b2?access_token=demo"
 
 # Get heart rate summary by date
curl "https://api.humanapi.co/v1/human/heart_rate/summaries/{YYYY-MM-DD}"
A binary file was returned

You couldn't be authenticated

{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
# Returns a json array of heart rate summaries:
[
  {
    "id": "550b8a8e834dd16f259683b2",
    "userId": "52e20cb2fff56aac62000001",
    "date": "2017-06-29",
    "zones": [
      {
        "name": "Out of Range",
        "max": 97,
        "min": 30,
        "duration": 45600,
        "caloriesBurned": 1497.92
      },
      {
        "name": "Fat Burn",
        "max": 135,
        "min": 97,
        "duration": 5040,
        "caloriesBurned": 557.41
      },
      {
        "name": "Cardio",
        "max": 164,
        "min": 135,
        "duration": 180,
        "caloriesBurned": 34.98
      },
      {
        "name": "Peak",
        "max": 220,
        "min": 164,
        "duration": 0,
        "caloriesBurned": 0
      }
    ],
    "restingHR": 58,
    "averageHR": 66,
    "maxHR": 158,
    "minHR": 45,
    "source": "fitbit",
    "sourceData": {},
    "createdAt": "2017-07-07T20:39:18.346Z",
    "updatedAt": "2017-07-07T20:39:18.346Z",
    "humanId": "5dc2527186aaf9de560e5841f1a44bd6"
  }
 ]

Zone Object

Zones are defined at the source and may vary, including zone names and ranges.

Property
Type
Description

name

String

Name of the zone

max

Number

Maximum heart rate applicable to the zone in beats per minute

min

Number

Minimum heart rate applicable to the zone in beats per minute

duration

Number

Duration that the user’s heart rate remained in the zone in seconds

caloriesBurned

Number

Calories burned while within the zone

Suggest Edits

Height

Get the height measurement from a specific point in time.

 
gethttps://api.humanapi.co/v1/human/height

Returns a height reading
GET https://api.humanapi.co/v1/human/height

Returns all height readings
GET https://api.humanapi.co/v1/human/height/readings

Response Properties

Property
Type
Description

id

String

The id of the resource.

userId

String

[deprecated - use humanId]

humanId

String

Unique user identifier

timestamp

Date

The original date and time of the measurement

source

String

The source service for the measurement, where it was created

value

Number

The value of the measurement in the unit specified

tzOffset

String

The offset from UTC time in +/-hh:mm (e.g. -04:00)

createdAt

Date

The time the measurement was created on the Human API server

updatedAt

Date

The time the measurement was updated on the Human API server

Zones are defined at the source and may vary, including zone names and ranges.

# Get the latest height measurement associated with the user
curl "https://api.humanapi.co/v1/human/height?access_token=demo"

# Get height measurement readings associated with the user
curl "https://api.humanapi.co/v1/human/height/readings?access_token=demo"
A binary file was returned

You couldn't be authenticated

{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
# Returns a json object of height:
{
  "id": "5509b45bb384e1620a5933c5",
  "userId": "52e20cb2fff56aac62000001",
  "timestamp": "2015-03-18T00:00:00.000Z",
  "tzOffset": "-07:00",
  "value": 1753,
  "unit": "mm",
  "source": "fitbit",
  "sourceData": {},
  "createdAt": "2015-03-18T17:22:35.859Z",
  "updatedAt": "2015-03-18T17:22:35.859Z",
  "humanId": "5dc2527186aaf9de560e5841f1a44bd6"
}
 
Suggest Edits

Human (Summary)

Get summary object for a person’s latest wellness metrics. The data consists of all the discrete wellness measurements and summary information about the person’s activity and sleep data.

 
gethttps://api.humanapi.co/v1/human

Returns the human profile
GET https://api.humanapi.co/v1/human

Response Properties

Property
Type
Description

id

String

The id of the resource.

userId

String

[deprecated - use humanId]

humanId

String

Unique user identifier

bloodGlucose

Object

The latest blood glucose measurement

bloodPressure

Object

The latest blood pressure measurement

bmi

Object

The latest body mass index measurement

bodyFat

Object

The latest body fat percentage measurement

height

Object

The latest height measurement

heartRate

Object

The latest heart rate measurement

weight

Object

The latest weight measurement

activitySummary

Object

The latest activity summary

sleepSummary

Object

The latest sleep summary

# Get user's wellness summary
curl "https://api.humanapi.co/v1/human?access_token=demo"
A binary file was returned

You couldn't be authenticated

{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
# Returns a json object:
{
  "humanId": "5dc2527186aaf9de560e5841f1a44bd6",
  "userId": "52e20cb2fff56aac62000001",
  "createdAt": "2014-01-24T06:48:18.361Z",
  "bloodGlucose": {
    "id": "54be39e6c3fa43b8057d59fc",
    "timestamp": "2015-01-20T12:20:04.000Z",
    "tzOffset": "-07:00",
    "source": "ihealth",
    "value": 94,
    "unit": "mg/dL"
  },
  "bloodOxygen": {
    "id": "54d1f018810a5ba429951b07",
    "timestamp": "2015-01-26T06:58:37.000Z",
    "tzOffset": "-07:00",
    "source": "withings",
    "value": 99,
    "unit": "SpO2"
  },
  "bloodPressure": {
    "id": "550b8a8e834dd16f259683b1",
    "userId": "52e20cb2fff56aac62000001",
    "timestamp": "2015-03-19T22:48:26.000Z",
    "tzOffset": "-07:00",
    "source": "ihealth",
    "systolic": 117,
    "diastolic": 76,
    "unit": "mmHg",
    "heartRate": 66
  },
  "bmi": {
    "id": "5506f5080ba9b35f0af6cc89",
    "timestamp": "2015-03-16T23:59:59.000Z",
    "tzOffset": "-07:00",
    "source": "fitbit",
    "value": 30.26,
    "unit": "kg/m2"
  },
  "bodyFat": {
    "id": "54ed75ccd9f8e13b13eaf17f",
    "timestamp": "2015-02-25T07:09:52.000Z",
    "tzOffset": "-07:00",
    "source": "withings",
    "value": 18.695,
    "unit": "%"
  },
  "height": {
    "id": "5509b45bb384e1620a5933c5",
    "timestamp": "2015-03-18T00:00:00.000Z",
    "tzOffset": "-07:00",
    "source": "fitbit",
    "value": 1753,
    "unit": "mm"
  },
  "heartRate": {
    "id": "550b8a8e834dd16f259683b2",
    "timestamp": "2015-03-19T22:48:26.000Z",
    "tzOffset": "-07:00",
    "source": "ihealth",
    "value": 66,
    "unit": "bpm"
  },
  "weight": {
    "id": "5506f5080ba9b35f0af6cc8a",
    "timestamp": "2015-03-16T23:59:59.000Z",
    "tzOffset": "-07:00",
    "source": "fitbit",
    "value": 92.9,
    "unit": "kg"
  },
  "activitySummary": {
    "id": "53adbf5dbef3fe0d24a1d453",
    "date": "2014-06-27",
    "duration": 1468.137,
    "distance": 3043.21010200387,
    "sedentary": 0,
    "light": 0,
    "moderate": 0,
    "vigorous": 0,
    "total": 1468.137,
    "steps": 0,
    "calories": 241,
    "source": "runkeeper"
  },
  "sleepSummary": {
    "id": "540e96b74247c3ea71d671b9",
    "userId": "52e20cb2fff56aac62000001",
    "date": "2014-09-09",
    "source": "fitbit",
    "timeAsleep": 456,
    "timeAwake": 0,
    "updatedAt": "2014-09-11T02:28:27.377Z"
  }
}
 
Suggest Edits

Locations

Get the user’s location at a specific point in time.

 
gethttps://api.humanapi.co/v1/human/locations

Returns a locations readings
GET https://api.humanapi.co/v1/human/locations

Response Properties

Property
Type
Description

id

String

The id of the resource.

userId

String

[deprecated - use humanId]

humanId

String

Unique user identifier

startTime

Date

The start time of the activity in UTC time

endTime

Date

The end time of the activity in UTC time

tzOffset

String

The offset from UTC time in +/-hh:mm (e.g. -04:00)

name

String

The name of the place

source

String

The source service for the measurement, where it was created

createdAt

Date

The time the measurement was created on the Human API server

location

Object

The coordinate point with a lat/lon value

updatedAt

Date

The time the measurement was updated on the Human API server

Location Object

Property
Type
Description

lon

Number

Longitude

lat

Number

Latitude

# Get locations measurement associated with the user
curl "https://api.humanapi.co/v1/human/locations?access_token=demo"
A binary file was returned

You couldn't be authenticated

{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
# Returns a json array of locations:
[{
  "id": "54aa4c5623e093b72ba122ec",
  "userId": "52e20cb2fff56aac62020001",
  "startTime": "2015-03-23T16:48:37.000Z",
  "endTime": "2015-03-23T17:15:40.000Z",
  "tzOffset": "-07:00",
  "name": "",
  "source": "moves",
  "location": {
    "lon": 77.3092283085,
    "lat": 28.5941775291
  },
  "createdAt": "2015-02-06T21:21:13.679Z",
  "updatedAt": "2015-02-06T21:21:13.679Z",
  "humanId": "5dc2527186aaf9de560e5841f1a44bd6"
}, {
  "id": "54c8681d94ae47d0702e8624",
  "userId": "52e20cb2aaf56aac62000001",
  "startTime": "2015-03-23T02:04:02.000Z",
  "endTime": "2015-03-23T03:38:26.000Z",
  "tzOffset": "-07:00",
  "name": "Walmart",
  "source": "moves",
  "location": {
    "lon": -87.06979948824468,
    "lat": 20.63034803007769
  },
  "createdAt": "2015-01-31T22:32:58.332Z",
  "updatedAt": "2015-01-31T22:32:58.332Z",
  "humanId": "5dc2527186aaf9de560e5841f1a44bd6"
}]
 
Suggest Edits

Meals

The Meals resource contains detailed data about nutrition consumed by the human separated by date and type: breakfast/lunch/dinner/other/morning_snack/afternoon_snack/after_dinner.

 
gethttps://api.humanapi.co/v1/human/meals

Get a list of meals the user has
GET https://api.humanapi.co/v1/human/food/meals

Returns a single meal
GET https://api.humanapi.co/v1/human/food/meals/{id}

Query Parameters

Parameter
Description

updated_since

Date in YYYYMMDDTHHmmssZ format

Response Properties

Property
Type
Description
Units

id

String

The id of the resource.

userId

String

[deprecated - use humanId]

humanId

String

Unique user identifier

timestamp

Date

The original date of the meal

type

String

Type of the meal: breakfast/lunch/dinner/other/morning_snack/afternoon_snack/after_dinner

tzOffset

String

The offset from UTC time in +/-hh:mm (e.g. -04:00)

name

String

Descriptive name of the meal

source

String

The source service for the meal data

calories

Object

The coordinate point with a lat/lon value

kcal

carbohydrate

Number

The amount of consumed carbohydrate

g

fat

Number

The amount of consumed fat

g

protein

Number

The amount of consumed protein

g

sodium

Number

The amount of consumed sodium

mg

sugar

Number

The amount of consumed sugar

g

fiber

Number

The amount of consumed fiber (optional)

g

saturatedFat

Number

The amount of consumed saturated fat (optional)

g

monounsaturatedFat

Number

The amount of consumed monounsaturated fat (optional)

g

polyunsaturatedFat

Number

The amount of consumed polyunsaturated fat (optional)

g

cholesterol

Number

The amount of consumed cholesterol (optional)

mg

vitaminA

Number

The amount of consumed vitamin A (optional)

mg

vitaminC

Number

The amount of consumed vitamin C (optional)

mg

calcium

Number

The amount of consumed calcium (optional)

mg

iron

Number

The amount of consumed iron (optional)

mg

potassium

Number

The amount of consumed potassium (optional)

mg

amount

Object

Amount of a food type (See below) (optional)

updatedAt

Date

The time the measurement was updated on the Human API server

createdAt

Date

The time the measurement was created on the Human API server

Amount Object

Property
Type
Description

value

Number

Quantity

unit

String

Unit of measure

# Get all meals associated with the user
curl "https://api.humanapi.co/v1/human/food/meals?access_token=demo"

# Get an meal by id
curl "https://api.humanapi.co/v1/human/food/meals/54fe0ad40f701cf4630be975?access_token=demo"
A binary file was returned

You couldn't be authenticated

{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
# Returns a json array of meals:
[{
  "id": "5508205f6101270148721599",
  "userId": "52e20cb2fff56aac62000001",
  "source": "jawbone",
  "timestamp": "2015-03-17T00:00:00.000Z",
  "tzOffset": "-07:00",
  "type": "lunch",
  "name": "Apfelstückchen mit Banane",
  "calories": 124,
  "carbohydrate": 26.6000003815,
  "fat": 0.600000023842,
  "protein": 1.60000002384,
  "sodium": 0,
  "sugar": 0,
  "calcium": 0,
  "cholesterol": 0,
  "fiber": 3,
  "iron": 0,
  "monounsaturatedFat": 0,
  "polyunsaturatedFat": 0,
  "potassium": 0,
  "saturatedFat": 0,
  "vitaminA": 0,
  "vitaminC": 0,
  "createdAt": "2015-03-17T12:38:55.712Z",
  "updatedAt": "2015-03-17T12:38:55.712Z",
  "humanId": "5dc2527186aaf9de560e5841f1a44bd6"
}, {
  "id": "54fe0ad40f701cf4630be975",
  "userId": "52e20cb2fff56aac62000001",
  "source": "jawbone",
  "timestamp": "2015-03-04T00:00:00.000Z",
  "tzOffset": "-07:00",
  "type": "lunch",
  "name": "3 Cereais e Leite",
  "calories": 633.999984741,
  "carbohydrate": 75.9680023193,
  "fat": 22.6160001755,
  "protein": 32.4159994125,
  "sodium": 723.199981689,
  "sugar": 40.2880020142,
  "calcium": 896,
  "cholesterol": 54.4000015259,
  "fiber": 3.07999992371,
  "iron": 0,
  "monounsaturatedFat": 0,
  "polyunsaturatedFat": 0,
  "potassium": 0,
  "saturatedFat": 11.1679999828,
  "vitaminA": 0,
  "vitaminC": 0,
  "createdAt": "2015-03-09T21:04:20.973Z",
  "updatedAt": "2015-03-09T21:04:20.973Z",
  "humanId": "5dc2527186aaf9de560e5841f1a44bd6"
}]
 
Suggest Edits

Profile

The Profile resource contains reference attributes that are convenient when you link a local app user from your application with a Human API user.

 
gethttps://api.humanapi.co/v1/human/profile

Returns the human profile
GET https://api.humanapi.co/v1/human/profile

Response Properties

Property
Type
Description

userId

String

[deprecated - use humanId]

humanId

String

Unique user identifier

email

String

The user’s email address, if known

createdAt

Date

The time the measurement was created on the Human API server

updatedAt

Date

The time the measurement was updated on the Human API server

# Get user's health profile
curl "https://api.humanapi.co/v1/human/profile?access_token=demo"
A binary file was returned

You couldn't be authenticated

{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
# Returns a json object:
{
  "userId": "52e20cb2fff56aac62000001",
  "createdAt": "2014-01-24T06:48:18.361Z",
  "email": "[email protected]",
  "defaultTimeZone": {
    "name": "UTC"
  },
  "humanId": "5dc2527186aaf9de560e5841f1a44bd6"
}
 
Suggest Edits

Sleeps

Sleep resources are segments of sleep that occur during a specific period of time.

 
gethttps://api.humanapi.co/v1/human/sleeps

Get a list of sleeps the user has
GET https://api.humanapi.co/v1/human/sleeps

Returns a single sleep
GET https://api.humanapi.co/v1/human/sleeps/{id}

Response Properties

Property
Type
Description

id

String

The id of the resource.

userId

String

[deprecated - use humanId]

humanId

String

Unique user identifier

day

Date

The day the sleep was recorded

startTime

Date

The original start date and time of the sleep segment in UTC time

endTime

Date

The original end date and time of the sleep segment in UTC time

tzOffset

String

The offset from UTC time in +/-hh:mm (e.g. -04:00)

source

String

The source service for the measurement, where it was created

mainSleep

Boolean

A boolean value indicating if this sleep was the main sleep of the day (default true when not specified by source)

timeAsleep

Number

The time asleep during the segment (in minutes)

timeAwake

Number

The time awake during the segment (in minutes)

efficiency

Number

The efficiency score

timeToFallAsleep

Number

The number of minutes it took to fall asleep

timeAfterWakeup

Number

The number of minutes in bed after waking up

timeInBed

Number

The total number of minutes spent in bed

numberOfWakeups

Number

The number of times the user woke up while in bed

updatedAt

Date

The time the measurement was updated on the Human API server

createdAt

Date

The time the measurement was created on the Human API server

timeSeries

Object

Time series data for the sleep, such as quality. See below for details

Time Series

Add time_series=true to get time series data for sleeps. See below for details.

Query Parameters

Parameter
Description

time_series

Add time_series=true to get time series data for sleeps. See below for details

Time Series Object

The timeSeries object can have multiple embedded objects. In the example below there is one object called “quality”, some services might provide other properties such as “heartRate” or “breathing” etc.

The embedded objects have the following properties:

Property
Description

type

Type of data, indexed with fixed time interval (See intervalInMillis) or timestamped.

intervalInMillis

If the type is indexed this indicates the number of milliseconds between each value.

values

The array of values, single values (indexed) or key-value pairs* (timestamped).

Timestamp represents the number of seconds from startTime.

Standard Series

Some series have standardized values across sources. Standard series are listed below.

Series
Values

state

0: wide awake, 1: awake, 2: light sleep, 3: regular sleep, 4: deep sleep, 5: REM sleep

# Get all sleeps associated with the user
curl "https://api.humanapi.co/v1/human/sleeps?access_token=demo"

# Get an sleep by id
curl "https://api.humanapi.co/v1/human/sleeps/550f8daf68d29c4133b122b5?access_token=demo"
A binary file was returned

You couldn't be authenticated

{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
# Returns a json array of sleeps:
[{
  "id": "551058f168d29c4133c4d1f4",
  "userId": "52e20cb2fff56aac62000001",
  "day": "2015-03-23",
  "startTime": "2015-03-23T02:50:27.000Z",
  "endTime": "2015-03-23T09:21:54.000Z",
  "tzOffset": "-07:00",
  "source": "jawbone",
  "mainSleep": true,
  "timeAsleep": 362,
  "timeAwake": 28,
  "efficiency": 57,
  "timeToFallAsleep": 12,
  "timeAfterWakeup": 0,
  "timeInBed": 391,
  "createdAt": "2015-03-23T18:18:25.687Z",
  "updatedAt": "2015-03-23T18:18:25.687Z",
  "humanId": "5dc2527186aaf9de560e5841f1a44bd6"
}, {
  "id": "550facab68d29c4133b4cf18",
  "userId": "52e20cb2fff56aac62000001",
  "day": "2015-03-23",
  "startTime": "2015-03-22T23:07:33.000Z",
  "endTime": "2015-03-23T06:54:35.000Z",
  "tzOffset": "+01:00",
  "source": "jawbone",
  "mainSleep": true,
  "timeAsleep": 442,
  "timeAwake": 24,
  "efficiency": 80,
  "timeToFallAsleep": 4,
  "timeAfterWakeup": 0,
  "timeInBed": 467,
  "createdAt": "2015-03-23T06:03:23.091Z",
  "updatedAt": "2015-03-23T06:03:23.091Z",
  "humanId": "5dc2527186aaf9de560e5841f1a44bd6"
}, {
  "id": "550f8daf68d29c4133b122b5",
  "userId": "52e20cb2fff56aac62000001",
  "day": "2015-03-22",
  "startTime": "2015-03-22T04:06:58.000Z",
  "endTime": "2015-03-22T13:36:10.000Z",
  "tzOffset": "-04:00",
  "source": "jawbone",
  "mainSleep": true,
  "timeAsleep": 377,
  "timeAwake": 180,
  "efficiency": 68,
  "timeToFallAsleep": 16,
  "timeAfterWakeup": 0,
  "timeInBed": 569,
  "createdAt": "2015-03-23T03:51:11.219Z",
  "updatedAt": "2015-03-23T03:51:11.219Z",
  "humanId": "5dc2527186aaf9de560e5841f1a44bd6"
}]
 
Suggest Edits

Sleep Summaries

Get a list of daily sleep summaries reported by the data sources.

 
gethttps://api.humanapi.co/v1/human/sleeps/summaries

Returns a list of sleep summaries
GET https://api.humanapi.co/v1/human/sleeps/summaries

Returns a single sleep summary
GET https://api.humanapi.co/v1/human/sleeps/summaries/{id}

Returns a single sleep summary by date
GET https://api.humanapi.co/v1/human/sleeps/summaries/{YYYY-MM-DD}

Response Properties

Property
Type
Description

id

String

The id of the resource.

userId

String

[deprecated - use humanId]

humanId

String

Unique user identifier

date

Date

The date of the sleep (format: YYYY-MM-DD)

source

String

The name of the originating service

timeAsleep

Number

The time asleep during the segment (in minutes)

timeAwake

Number

The time awake during the segment (in minutes)

updatedAt

Date

The time the measurement was updated on the Human API server

createdAt

Date

The time the measurement was created on the Human API server

# Get all sleep summaries associated with the user
curl "https://api.humanapi.co/v1/human/sleeps/summaries?access_token=demo"

# Get an sleep summary by id
curl "https://api.humanapi.co/v1/human/sleeps/summaries/550d599c47be23e06c83bbde?access_token=demo"
A binary file was returned

You couldn't be authenticated

{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
# Returns a json array of sleeps summaries:
[{
  "id": "550facab68d29c4133b4cf22",
  "userId": "52e20cb2fff56aac62000001",
  "date": "2015-03-23",
  "source": "jawbone",
  "timeAsleep": 391.45,
  "timeAwake": 28,
  "createdAt": "2015-03-23T06:03:23.141Z",
  "updatedAt": "2015-03-23T18:18:25.678Z",
  "humanId": "5dc2527186aaf9de560e5841f1a44bd6"
}, {
  "id": "550e92b25ee14de827d16689",
  "userId": "52e20cb2fff56aac62000001",
  "date": "2015-03-22",
  "source": "jawbone",
  "timeAsleep": 443.6,
  "timeAwake": 23,
  "createdAt": "2015-03-22T10:00:18.804Z",
  "updatedAt": "2015-03-23T15:05:28.591Z",
  "humanId": "5dc2527186aaf9de560e5841f1a44bd6"
}, {
  "id": "550d599c47be23e06c83bbde",
  "userId": "52e20cb2fff56aac62000001",
  "date": "2015-03-21",
  "source": "jawbone",
  "timeAsleep": 412.5,
  "timeAwake": 96,
  "createdAt": "2015-03-21T11:44:28.969Z",
  "updatedAt": "2015-03-23T15:05:28.599Z",
  "humanId": "5dc2527186aaf9de560e5841f1a44bd6"
}]
 
Suggest Edits

Weight

Get the weight measurement from a specific point in time.

 
gethttps://api.humanapi.co/v1/human/weight

Returns a weight reading
GET https://api.humanapi.co/v1/human/weight

Returns all weight readings
GET https://api.humanapi.co/v1/human/weight/readings

Response Properties

Property
Type
Description

id

String

The id of the reading

userId

String

[deprecated - use humanId]

timestamp

Date

The original date and time of the measurement

humanId

String

Unique user identifier

tzOffset

String

The offset from UTC time in +/-hh:mm (e.g. -04:00)

value

Number

The value of the measurement in the unit specified

unit

String

The unit of the measurement value

createdAt

Date

The time the measurement was created on the Human API server

updatedAt

Date

The time the measurement was updated on the Human API server

# Get the latest weight measurement associated with the user
curl "https://api.humanapi.co/v1/human/weight?access_token=demo"

# Returns all weight readings
https://api.humanapi.co/v1/human/weight/readings
A binary file was returned

You couldn't be authenticated

{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
# Returns a json object of weight:
{
  "id": "5506f5080ba9b35f0af6cc8a",
  "userId": "52e20cb2fff56aac62000001",
  "timestamp": "2015-03-16T23:59:59.000Z",
  "tzOffset": "-07:00",
  "value": 92.9,
  "unit": "kg",
  "source": "fitbit",
  "sourceData": {},
  "createdAt": "2015-03-16T15:21:44.289Z",
  "updatedAt": "2015-03-16T15:24:48.475Z",
  "humanId": "5dc2527186aaf9de560e5841f1a44bd6"
}
 
Suggest Edits

Sources

The Sources endpoint returns the synchronization status of the different sources that a specific user has connected.

 

Returns a sources array
GET https://api.humanapi.co/v1/human/sources

Response Properties

Property
Type
Description

source

String

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

supportedDataTypes

Array[String]

(Deprecated) List of data types supported by the source

devices

Array[String]

(Deprecated) List of devices or medical source id (when available)

id

String

Non-unique id for an external data account

connectedSince

Date

Date that the source was connected to Human API

sourceName

String

Name of medical or wellness source

historySync

Object

See historySync object

syncStatus

Object

See syncStatus object

resync

Object

See resync object

organization

Object

See organization object

historySync Object

Property
Type
Description

status

String

Status of the historical sync

oldestDate

Date

Oldest date of the data retrieved from the service

For some services, oldestDate is just an indication of how far back the synchronization tasks attempted to retrieve data.

syncStatus Object

Property
Type
Description

status

String

Status of the most recent sync

synchedAt

Date

The last time the synchronization task ran for this user

newestDate

Date

(Deprecated) The timestamp of the most recently retrieved data

details

String

Identifies details about the status property when appropriate

resync Object

Property
Type
Description

active

Boolean

Identifies if the data source belonging to the user has continuous capability

# Returns a json object of sources:
// example
[
	{
    "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"
    }
  }
]
 
# Get sources measurement associated with the user
curl -H "Authorization: Bearer demo" "https://api.humanapi.co/v1/human/sources"