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

 

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 Human Connect to authenticate external sources.

What are you waiting for? Get Started!

Common Record Properties

Regardless of the type, most 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 API Patterns & Conventions guide 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 reference.humanapi.co.

HAPI coding!

 
Suggest Edits

Medical API Introduction

 

Enterprise feature

If you are interested in using the Medical API, send us an email at enterprise@humanapi.co.

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

 

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

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

patient

Object

Patient information (“name” and other optional attributes)

organization

Object

reactionsFull

Array[Object]

allergen

Object

status

String

(optional) The status of the allergy

severity

String

(optional) The severity of the allergy

dateRange

Object

codes

Array[Object]

Allergen Object

Property
Type
Description

name

String

Name of the allergen

codes

Object

Reaction Object

Property
Type
Description

name

String

Name of the allergen

codes

Object

reactionType

Object

Reaction Type Object

Property
Type
Description

name

String

Name of the reaction

codes

Object

Date Range Object

Property
Type
Description

start

Date

Start date

end

Date

End date

# 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

 

Returns a list of medical encounters
GET https://api.humanapi.co/v1/human/medical/encounters

Returns a single encounter
GET https://api.humanapi.co/v1/human/medical/encounters/{id}

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

The date of the encounter

visitType

String

The type of visit

provider

Object

The provider for the encounter (see provider object)

prescriptions

Array[Object]

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

diagnoses

Array[Object]

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]

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

reasons

Array[String]

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

orders

Array[Object]

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

testResults

Array[Object]

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

plansOfCare

Array[Object]

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

medications

Array[Object]

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

Patient information (“name” and other optional attributes)

organization

Object

codes

Array[Object]

Orders Object

Property
Type
Description

name

String

The name of the order

codeType

String

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

expectedDate

Date

The date the order is expected

expireDate

Date

The date the order expires

procedureCode

String

The procedure code of the order

type

String

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

codes

Array[Object]

Provider Object

Property
Type
Description

name

String

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

# 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": []
    }
]
# Get all encounters associated with the user
curl -H "Authorization: Bearer demo" "https://api.humanapi.co/v1/human/medical/encounters"
Suggest Edits

Functional Statuses

Get a list of medical functional statuses associated with the user

 

Returns a list of medical functional statuses
GET https://api.humanapi.co/v1/human/medical/functional_statuses

Returns a single functional status
GET https://api.humanapi.co/v1/human/medical/functional_statuses/{id}

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

The name of the functional status

codes

Array[Object]

# 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": []
    }
]
# Get all functional statuses associated with the user
curl -H "Authorization: Bearer demo" "https://api.humanapi.co/v1/human/medical/functional_statuses"
Suggest Edits

Immunizations

Get a list of immunizations the user has had so far

 

Returns a list of medical immunizations
GET https://api.humanapi.co/v1/human/medical/immunizations

Returns a single immunization
GET https://api.humanapi.co/v1/human/medical/immunizations/{id}

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]

The dates immunization was given.

name

String

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

patient

Object

Patient information (“name” and other optional attributes)

organization

Object

codes

Array[Object]

# 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": []
}]
# Get all immunizations associated with the user
curl -H "Authorization: Bearer demo" "https://api.humanapi.co/v1/human/medical/immunizations"
Suggest Edits

Instructions

Get a list of medical instructions associated with the user

 

Returns a list of medical instructions
GET https://api.humanapi.co/v1/human/medical/instructions

Returns a single instruction
GET https://api.humanapi.co/v1/human/medical/instructions/{id}

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

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

text

String

Text content of the instruction

codes

Array[Object]

# 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": []
    }
]
# Get all instructions associated with the user
curl -H "Authorization: Bearer demo" "https://api.humanapi.co/v1/human/medical/instructions"
Suggest Edits

Medications

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

 

Returns a list of medical medications
GET https://api.humanapi.co/v1/human/medical/medications

Returns a single medication
GET https://api.humanapi.co/v1/human/medical/medications/{id}

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

Patient information (“name” and other optional attributes)

name

String

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

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]

Pharmacy Object

Property
Type
Description

id

String

The id of the resource

name

String

The name of the pharmacy

address

String

The address of the pharmacy

phone

String

The phone number of the pharmacy

hours

String

The opening hours of the pharmacy (if provided)

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"}

# 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": []
}]
# Get all medications associated with the user
curl -H "Authorization: Bearer demo" "https://api.humanapi.co/v1/human/medical/medications"
Suggest Edits

Narratives

Get a list of medical narratives associated with the user

 

Returns a list of medical narratives
GET https://api.humanapi.co/v1/human/medical/narratives

Returns a single narrative
GET https://api.humanapi.co/v1/human/medical/narratives/{id}

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

The date of the narrative

author

String

The name of the author

entries

Array[Object]

Array of entry objects (See below)

Entry Object

Property
Type
Description

title

String

The title of the entry

text

String

The description text of the entry

# 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"
  }
}]
# Get all narratives associated with the user
curl -H "Authorization: Bearer demo" "https://api.humanapi.co/v1/human/medical/narratives"
Suggest Edits

Organizations

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

 

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

{
  "id": "53c050ae51c69003200aaa29",
  "name": "Singing River Health System"
}
# Get an organization by id
curl -H "Authorization: Bearer demo" "https://api.humanapi.co/v1/human/medical/organizations/54dc427aaa6b4cb7d6203061"
Suggest Edits

Plans of Care

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

 

Returns a list of medical plans of care
GET https://api.humanapi.co/v1/human/medical/plans_of_care

Returns a single plan of care
GET https://api.humanapi.co/v1/human/medical/plans_of_care/{id}

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

The name of the plan of care

text

String

The text description of the author

date

Date

The date of the plan of care

type

String

The type of the plan of care

specialty

String

(optional) The specialty of the plan of care

provider

Object

See provider object

organization

Object

codes

Array[Object]

Provider Object

Property
Type
Description

name

Object

address

String

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

# 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": []
} ]
# Get all plans of care associated with the user
curl -H "Authorization: Bearer demo" "https://api.humanapi.co/v1/human/medical/plans_of_care"
Suggest Edits

Problems

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

 

Returns a list of medical problems
GET https://api.humanapi.co/v1/human/medical/issues

Returns a single problem
GET https://api.humanapi.co/v1/human/medical/issues/{id}

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

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

patient

Object

Patient information (“name” and other optional attributes)

status

String

Status of the problem e.g. "Active"

organization

Object

codes

Array[Object]

# 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"
    }
]
# Get all problems associated with the user
curl -H "Authorization: Bearer demo" "https://api.humanapi.co/v1/human/medical/issues"
Suggest Edits

Procedures

Get a list of medical procedures associated with the user

 

Returns a list of medical procedures
GET https://api.humanapi.co/v1/human/medical/procedures

Returns a single procedure
GET https://api.humanapi.co/v1/human/medical/procedures/{id}

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

source

String

The name of the originating service

device

String

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

deviceCodes

Array[Object]

Device codes Note: presence of this value is rare

name

String

Name of the procedure

performer

Object

specimen

String

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

specimenCodes

Array[Object]

Specimen codes Note: presence of this value is rare

organization

Object

codes

Array[Object]

Performer Object

Property
Type
Description

address

String

Address of the performer

organizationName

String

Name of the performer’s organization

phone

String

Phone number of the performer

# 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"
            }
        ]
    }
]
# Get all procedures associated with the user
curl -H "Authorization: Bearer demo" "https://api.humanapi.co/v1/human/medical/procedures"
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.

 

Return a user’s medical profile:
GET https://api.humanapi.co/v1/human/medical/profile

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

demographics

Object

alcohol

Object

The user’s alcohol usage

smoking

Object

The user’s smoking habits

Demographics Object

Property
Type
Description

address

Object

dob

String

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

ethnicity

String

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

gender

String

The user’s gender e.g. "male"

language

String

The user’s primary language e.g. "eng"

maritalStatus

String

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

name

Object

race

String

The user’s race e.g. "White"

ethnicityCodes

Array[Object]

maritalStatusCodes

String

genderCodes

String

Address Object

Property
Type
Description

city

String

City of address e.g. "SAN FRANCISCO"

country

String

Country of address e.g. "US"

state

String

State of address e.g. "CA"

street

Array[String]

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

zip

String

Zip of address e.g. "94123"

Alcohol Object

Property
Type
Description

use

String

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

codes

Array[Object]

Smoking

Property
Type
Description

status

String

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

codes

Array[Object]

# 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
      }
    ]
  }
}
# Get user's medical profile
curl -H "Authorization: Bearer demo" "https://api.humanapi.co/v1/human/medical/profile"
Suggest Edits

Test Results

Get a list of medical lab results for a user.

 

Return a list of medical test results:
GET https://api.humanapi.co/v1/human/medical/test_results

Return a single test result:
GET https://api.humanapi.co/v1/human/medical/test_results/{id}

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

deviceCodes

Array[Object]

(optional) Device codes 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]

See recipient object Note: presence of this value is rare

resultDateTime

Date

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

organization

Object

codes

Array[Object]

Component Object

Property
Type
Description

name

String

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

value

String

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]

Recipient Object

Property
Type
Description

objectID

String

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

name

String

The name of the recipient

isPCP

Boolean

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

recipTemplate

String

The recipient template e.g. 'WPMessageRecipientTemplateUnknown’

# 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"
}]
# Get all test results associated with the user
curl -H "Authorization: Bearer demo" "https://api.humanapi.co/v1/human/medical/test_results"
Suggest Edits

Vitals

Get the user’s vitals readings

 

Returns a list of vitals readings
GET https://api.humanapi.co/v1/human/medical/vitals

Returns a single vitals reading
GET https://api.humanapi.co/v1/human/medical/vitals/{id}

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 vitals reading

author

String

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

results

Array[Object]

A list of all test results (see results object)

organization

Object

Results Object

Property
Type
Description

name

String

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

value

String

The test result value

unit

String

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

codes

Array[Object]

normalizedName

String

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

# 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"
    }
]
# Get all vitals readings associated with the user
curl -H "Authorization: Bearer demo" "https://api.humanapi.co/v1/human/medical/vitals"
Suggest Edits

CCD

Returns full CCDs available for the user including the raw xml

 

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

The date of the CCD

author

String

CCD author’s name

organization

Object

Response Headers (Raw CCD)

Header
Value

Content-Type

text/xml

# 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"
  }
}]
# Get all ccds associated with the user
curl -H "Authorization: Bearer demo" "https://api.humanapi.co/v1/human/medical/ccds"
Suggest Edits

Demographics

Get a list of demographics data associated with the user

 

Returns a list of demographics data associated with the user
GET https://api.humanapi.co/v1/human/medical/demographics

Returns a single record of demographics data associated with the user
GET https://api.humanapi.co/v1/human/medical/demographics/{id}

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

dob

String

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

dobDateTime

String

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

ethnicity

String

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

ethnicityCodes

Array[Object]

gender

String

Gender of the patient e.g. "male"

genderCodes

Array[Object]

language

String

Preferred spoken language of the patient e.g. "eng"

languageCodes

Array[Object]

martialStatus

String

Marital status of the patient e.g. "married"

maritalStatusCodes

Array[Object]

provider

Object

See Provider Object details below

organization

Object

race

String

Race of the patient e.g. "White"

raceCodes

Array[Object]

codes

Array[Object]

ccd

Object

See CCD Object details below

CCD Object

Property
Type
Description

id

String

id of the CCD

Provider Object

Property
Type
Description

organization

String

The name of the medical source

address

Object

See Address Object below

Address Object (from Provider Object)

Property
Type
Description

city

String

City of the provider e.g. "San Francisco"

country

String

Country of the provider e.g. "USA"

state

String

State of the provider e.g. "CA"

zip

String

Zip code of the provider e.g. "94156"

street

Array[String]

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

# 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"
    }
]
# 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 demo" "https://api.humanapi.co/v1/human/medical/demographics"
Suggest Edits

Claims API Introduction

 

Enterprise feature

If you are interested in using the Claims API, send us an email at enterprise@humanapi.co.

The Claims API is enabled by default when a customer has access to the Medical API.

Claims allow customers to see a detailed invoice produced by a healthcare provider and a health insurer on services provided.

Bundles

When querying a Claims API endpoint without stating an id, the system will produce a bundle. This is equivalent to a list of items associated with the query.

For more information about bundles, see HL7's documentation.

Response Properties

Mapping of properties

#Generic bundle

{
  "resourceType": "Bundle",
  "id": "bundle-example",
  "meta": {
    "lastUpdated": "2014-08-18T01:43:30Z"
  },
  "type": "searchset",
  "total": 3,
  "link": [
    {
      "relation": "self",
      "url": "https://example.com/base/MedicationRequest?patient=347&_include=MedicationRequest.medication"
    },
    {
      "relation": "next",
      "url": "https://example.com/base/MedicationRequest?patient=347&searchId=ff15fd40-ff71-4b48-b366-09c706bed9d0&page=2"
    }
  ],
  "entry": [
    {
      "fullUrl": "https://example.com/base/MedicationRequest/3123",
      "resource": {
        "resourceType": "MedicationRequest",
        "id": "3123",
        "text": {
          "status": "generated",
          "div": "<div xmlns=\"http://www.w3.org/1999/xhtml\"><p><b>Generated Narrative with Details</b></p><p><b>id</b>: 3123</p><p><b>intent</b>: order</p><p><b>medication</b>: <a>Medication/example</a></p><p><b>subject</b>: <a>Patient/347</a></p></div>"
        },
        "intent": "order",
        "medicationReference": {
          "reference": "Medication/example"
        },
        "subject": {
          "reference": "Patient/347"
        }
      },
      "search": {
        "mode": "match",
        "score": 1
      }
    },
    {
      "fullUrl": "https://example.com/base/Medication/example",
      "resource": {
        "resourceType": "Medication",
        "id": "example",
        "text": {
          "status": "generated",
          "div": "<div xmlns=\"http://www.w3.org/1999/xhtml\"><p><b>Generated Narrative with Details</b></p><p><b>id</b>: example</p></div>"
        }
      },
      "search": {
        "mode": "include"
      }
    }
  ]
}
 

Metadata, or the Capability Statement, describes the server's FHIR-related features. It also describes the resources available to pull from Human API.

No access token is required to query the server's metadata.

Response Properties

Description of properties

Mapping of properties
(see JSON example)

{
    "date": "2018-06-21T23:50:57.288Z",
    "fhirVersion": "3.0.1",
    "format": [
        "application/json"
    ],
    "kind": "instance",
    "publisher": "Human API",
    "resourceType": "CapabilityStatement",
    "rest": [
        {
            "mode": "server",
            "resource": [
                {
                    "interaction": [
                        {
                            "code": "read"
                        },
                        {
                            "code": "search-type"
                        }
                    ],
                    "profile": {
                        "reference": "https://www.hl7.org/fhir/coverage.html"
                    },
                    "searchParam": [
                        {
                            "definition": "https://www.hl7.org/fhir/resource-definitions.html#Meta.lastUpdated",
                            "name": "_lastUpdated",
                            "type": "date"
                        }
                    ],
                    "type": "Coverage"
                },
                {
                    "interaction": [
                        {
                            "code": "read"
                        },
                        {
                            "code": "search-type"
                        }
                    ],
                    "profile": {
                        "reference": "https://www.hl7.org/fhir/explanationofbenefit.html"
                    },
                    "searchParam": [
                        {
                            "definition": "https://www.hl7.org/fhir/resource-definitions.html#Meta.lastUpdated",
                            "name": "_lastUpdated",
                            "type": "date"
                        }
                    ],
                    "type": "ExplanationOfBenefit"
                },
                {
                    "interaction": [
                        {
                            "code": "read"
                        },
                        {
                            "code": "search-type"
                        }
                    ],
                    "profile": {
                        "reference": "https://www.hl7.org/fhir/patient.html"
                    },
                    "searchParam": [
                        {
                            "definition": "https://www.hl7.org/fhir/resource-definitions.html#Meta.lastUpdated",
                            "name": "_lastUpdated",
                            "type": "date"
                        }
                    ],
                    "type": "Patient"
                }
            ]
        }
    ],
    "status": "active",
    "url": "https://api.humanapi.co/v2/metadata"
}
curl https://api.humanapi.co/v2/fhir/metadata
Suggest Edits

Explanation of Benefit

 

This resource provides: the claim details; adjudication details from the processing of a Claim; and optionally account balance information, for informing the subscriber of the benefits provided.

The Explanation of Benefit resource combines key information from a Claim, a ClaimResponse and optional Account information to inform a patient of the goods and services rendered by a provider and the settlement made under the patient's coverage in respect of that Claim.

For more information about this datatype, see HL7's page.

Returns a bundle of benefits
GET https://api.humanapi.co/v2/fhir/explanationofbenefit

Returns a single benefit
GET https://api.humanapi.co/v2/fhir/explanationofbenefit/{_id}

Human API access token must be in header

While the Wellness and Medical APIs allow for the access token to be added as a query parameter, Claims API endpoints only allow the token as a header.

Query Parameters

Parameter
Datatype
Description

_lastUpdated

Timestamp/Instant (ISO 8601)

Used to select resources based on the last time they were changed

Available prefixes: eq, gt, lt, ge, le

e.g. gt2018-06-21T22:51:10.720Z

_count

Int

The number of items in response

offset

Int

Offsets the list in the response by the number

Response Properties

Description of properties

Mapping of properties

{
  "resourceType": "ExplanationOfBenefit",
  "id": "EB3500",
  "text": {
    "status": "generated",
    "div": "<div xmlns=\"http://www.w3.org/1999/xhtml\">A human-readable rendering of the ExplanationOfBenefit</div>"
  },
  "identifier": [
    {
      "system": "http://www.BenefitsInc.com/fhir/explanationofbenefit",
      "value": "987654321"
    }
  ],
  "status": "active",
  "type": {
    "coding": [
      {
        "system": "http://hl7.org/fhir/ex-claimtype",
        "code": "oral"
      }
    ]
  },
  "patient": {
    "reference": "Patient/pat1"
  },
  "created": "2014-08-16",
  "enterer": {
    "reference": "Practitioner/1"
  },
  "provider": {
    "reference": "Practitioner/1"
  },
  "organization": {
    "reference": "Organization/2"
  },
  "facility": {
    "reference": "Location/1"
  },
  "claim": {
    "reference": "Claim/100150"
  },
  "claimResponse": {
    "reference": "ClaimResponse/R3500"
  },
  "outcome": {
    "coding": [
      {
        "system": "http://hl7.org/fhir/remittance-outcome",
        "code": "complete"
      }
    ]
  },
  "disposition": "Claim settled as per contract.",
  "payee": {
    "type": {
      "coding": [
        {
          "system": "http://hl7.org/fhir/payeetype",
          "code": "provider"
        }
      ]
    },
    "resourceType": {
      "coding": [
        {
          "system": "http://hl7.org/fhir/resource-type-link",
          "code": "organization"
        }
      ]
    },
    "party": {
      "reference": "Organization/2"
    }
  },
  "careTeam": [
    {
      "sequence": 1,
      "provider": {
        "reference": "Practitioner/example"
      }
    }
  ],
  "insurance": {
    "coverage": {
      "reference": "Coverage/9876B1"
    }
  },
  "item": [
    {
      "sequence": 1,
      "careTeamLinkId": [
        1
      ],
      "service": {
        "coding": [
          {
            "system": "http://hl7.org/fhir/service-uscls",
            "code": "1200"
          }
        ]
      },
      "servicedDate": "2014-08-16",
      "unitPrice": {
        "value": 135.57,
        "system": "urn:iso:std:iso:4217",
        "code": "USD"
      },
      "net": {
        "value": 135.57,
        "system": "urn:iso:std:iso:4217",
        "code": "USD"
      },
      "encounter": [
        {
          "reference": "Encounter/example"
        }
      ],
      "adjudication": [
        {
          "category": {
            "coding": [
              {
                "code": "eligible"
              }
            ]
          },
          "amount": {
            "value": 120.00,
            "system": "urn:iso:std:iso:4217",
            "code": "USD"
          }
        },
        {
          "category": {
            "coding": [
              {
                "code": "eligpercent"
              }
            ]
          },
          "value": 0.80
        },
        {
          "category": {
            "coding": [
              {
                "code": "benefit"
              }
            ]
          },
          "amount": {
            "value": 96.00,
            "system": "urn:iso:std:iso:4217",
            "code": "USD"
          }
        }
      ]
    }
  ],
  "totalCost": {
    "value": 135.57,
    "system": "urn:iso:std:iso:4217",
    "code": "USD"
  },
  "totalBenefit": {
    "value": 96.00,
    "system": "urn:iso:std:iso:4217",
    "code": "USD"
  }
}
#Get explanation of benefit by id
curl -X GET \
'https://api.humanapi.co/v2/fhir/explanationofbenefit/id' \
  -H 'authorization: Bearer HUMANAPI_ACCESS_TOKEN'
 

Financial instrument which may be used to reimburse or pay for health care products and services.

The Coverage resource is intended to provide the high level identifiers and potentially descriptors of an insurance plan which may used to pay for, in part or in whole, the provision of health care products and services.

For more information about this datatype, see HL7's page.

Returns a bundle of coverage
GET https://api.humanapi.co/v2/fhir/coverage

Returns a single coverage
GET https://api.humanapi.co/v2/fhir/coverage/{_id}

Human API access token must be in header

While the Wellness and Medical APIs allow for the access token to be added as a query parameter, Claims API endpoints only allow the token as a header.

Query Parameters

Parameter
Datatype
Description

_lastUpdated

Timestamp/Instant (ISO 8601)

Used to select resources based on the last time they were changed

Available prefixes: eq, gt, lt, ge, le

e.g. gt2018-06-21T22:51:10.720Z

_count

int

The number of items in response

offset

int

Offsets the list in the response by the number

Response Properties

Description of properties

Description of mapping

{
  "resourceType": "Coverage",
  "id": "9876B1",
  "text": {
    "status": "generated",
    "div": "<div xmlns=\"http://www.w3.org/1999/xhtml\">A human-readable rendering of the coverage</div>"
  },
  "identifier": [
    {
      "system": "http://benefitsinc.com/certificate",
      "value": "12345"
    }
  ],
  "status": "active",
  "type": {
    "coding": [
      {
        "system": "http://hl7.org/fhir/v3/ActCode",
        "code": "EHCPOL",
        "display": "extended healthcare"
      }
    ]
  },
  "policyHolder": {
    "reference": "http://benefitsinc.com/FHIR/Organization/CBI35"
  },
  "subscriber": {
    "reference": "Patient/4"
  },
  "beneficiary": {
    "reference": "Patient/4"
  },
  "relationship": {
    "coding": [
      {
        "code": "self"
      }
    ]
  },
  "period": {
    "start": "2011-05-23",
    "end": "2012-05-23"
  },
  "payor": [
    {
      "reference": "Organization/2"
    }
  ],
  "grouping": {
    "group": "CBI35",
    "groupDisplay": "Corporate Baker's Inc. Local #35",
    "subGroup": "123",
    "subGroupDisplay": "Trainee Part-time Benefits",
    "plan": "B37FC",
    "planDisplay": "Full Coverage: Medical, Dental, Pharmacy, Vision, EHC",
    "subPlan": "P7",
    "subPlanDisplay": "Includes afterlife benefits",
    "class": "SILVER",
    "classDisplay": "Silver: Family Plan spouse only",
    "subClass": "Tier2",
    "subClassDisplay": "Low deductable, max $20 copay"
  },
  "dependent": "0",
  "sequence": "9"
}
#Get coverage data by id
curl -X GET \
'https://api.humanapi.co/v2/fhir/coverage/id' \
  -H 'authorization: Bearer HUMANAPI_ACCESS_TOKEN'
 

Demographics and other administrative information about an individual or animal receiving care or other health-related services.

This Resource covers data about patients and animals involved in a wide range of health-related activities, including:

  • Curative activities
  • Psychiatric care
  • Social services
  • Pregnancy care
  • Nursing and assisted living
  • Dietary services
  • Tracking of personal health and exercise data

The data in the Resource covers the "who" information about the patient: its attributes are focused on the demographic information necessary to support the administrative, financial and logistic procedures. A Patient record is generally created and maintained by each organization providing care for a patient. A patient or animal receiving care at multiple organizations may therefore have its information present in multiple Patient Resources.

For more information about this resource, see HL7's page.

Returns a bundle of patients
GET https://api.humanapi.co/v2/fhir/patient

Human API access token must be in header

While the Wellness and Medical APIs allow for the access token to be added as a query parameter, Claims API endpoints only allow the token as a header.

Query Parameters

Parameter
Datatype
Description

_lastUpdated

Timestamp/Instant (ISO 8601)

Used to select resources based on the last time they were changed

Available prefixes: eq, gt, lt, ge, le

e.g. gt2018-06-21T22:51:10.720Z

_count

Int

The number of items in response

offset

Int

Offsets the list in the response by the number

Response Properties

Description of properties

Mapping of properties

{
    "entry": [
        {
            "fullUrl": "https://api.humanapi.co/v2/fhir/patient/134e278b-62f0-47b3-810j-c4g7244d0e6d",
            "resource": {
                "address": [
                    {
                        "district": "030",
                        "line": [],
                        "postalCode": "58712",
                        "state": "03"
                    }
                ],
                "birthDate": "1954-01-13T00:00:00.000Z",
                "communication": [],
                "contact": [],
                "gender": "unknown",
                "generalPractitioner": [],
                "id": "404ef78b-62f0-47b3-810b-b4d7444d0e6d",
                "identifier": [
                    {
                        "system": "https://bluebutton.cms.gov/resources/variables/bene_id",
                        "value": "154684"
                    },
                    {
                        "system": "https://bluebutton.cms.gov/resources/identifier/hicn-hash",
                        "value": "d73328d314b249gd0296c5422071dc34cf8209de635f3849785a36328033ae6c"
                    }
                ],
                "link": [],
                "meta": {
                    "lastUpdated": "2018-06-20T12:40:55.677Z",
                    "profile": [],
                    "security": [],
                    "tag": []
                },
                "name": [
                    {
                        "family": "Brian",
                        "given": [
                            "Miles",
                            "O"
                        ],
                        "prefix": [],
                        "resourceType": "HumanName",
                        "suffix": [],
                        "use": "usual"
                    }
                ],
                "photo": [],
                "resourceType": "Patient",
                "telecom": []
            }
        }
    ],
    "id": "77152ac6-d39b-5ecf-8b1f-e6ba513ba854",
    "link": [
        {
            "relation": "self",
            "url": "https://api.humanapi.co/v2/fhir/patient?_count=20&offset=0"
        },
        {
            "relation": "first",
            "url": "https://api.humanapi.co/v2/fhir/patient?_count=20&offset=0"
        },
        {
            "relation": "last",
            "url": "https://api.humanapi.co/v2/fhir/patient?_count=20&offset=0"
        }
    ],
    "resourceType": "Bundle",
    "total": 1,
    "type": "searchset"
}
#Get explanation of a bundle of patient data
curl -X GET \
'https://api.humanapi.co/v2/fhir/patient' \
  -H 'authorization: Bearer HUMANAPI_ACCESS_TOKEN'
Suggest Edits

Wellness API Introduction

 

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

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.

 

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

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

Query Parameters

Parameter
Description

time_series

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

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. See below for details.

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”.

The embedded objects have the following properties:

# 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"
}]
# Get an activity by id
curl "https://api.humanapi.co/v1/human/activities/52e20cb2fff56aac62000001?access_token=demo"

# Returns a json object as activity:
{
  "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"
}
# Get all activities associated with the user
curl -H "Authorization: Bearer demo" "https://api.humanapi.co/v1/human/activities"
Suggest Edits

Activity Summaries

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

 

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

# 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
  }
]

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

# Returns a json object as activity summary:
{
  "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"
}
# Get all activity summaries associated with the user
curl -H "Authorization: Bearer demo" "https://api.humanapi.co/v1/human/activities/summaries"
Suggest Edits

Blood Glucose

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

 

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

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

# 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"
}
# Get the latest blood glucose measurement associated with the user
curl -H "Authorization: Bearer demo" "https://api.humanapi.co/v1/human/blood_glucose"
Suggest Edits

Blood Oxygen

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

 

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

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 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"
}
# Get latest blood oxygen measurement associated with the user
curl -H "Authorization: Bearer demo" "https://api.humanapi.co/v1/human/blood_oxygen"

Suggest Edits

Blood Pressure

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

 

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

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 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"
}
# Get the latest blood pressure measurement associated with the user
curl -H "Authorization: Bearer demo" "https://api.humanapi.co/v1/human/blood_pressure"
Suggest Edits

Body Mass Index (BMI)

Get the BMI measurement from a specific point in time.

 

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

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 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"
}
# Get latest bmi measurement associated with the user
curl -H "Authorization: Bearer demo" "https://api.humanapi.co/v1/human/bmi"
Suggest Edits

Body Fat

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

 

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

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 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"
}
# Get the latest body fat measurement associated with the user
curl -H "Authorization: Bearer demo" "https://api.humanapi.co/v1/human/body_fat"
Suggest Edits

Genetic Traits

Get genetic traits of a user

 

Genetic traits endpoint has been deprecated

The genetic traits endpoint has been deprecated by 23andMe. Users who provided access to their 23andMe account and had genetic traits data available via Human API will still have that data available through genetic/traits. However, any new data will not be retrievable.

Property
Type
Description

id

String

The id of the resource.

userId

String

[deprecated - use humanId]

humanId

String

Unique user identifier

trait

String

The most likely present trait

possibleTraits

String

A list of all the possible values for a specific trait, for easy comparison

description

String

A description/name of the trait

# Returns a JSON array of genetic traits:
[{
  "userId": "52e20cb2fff56aac62000001",
  "description": "Hair Curl",
  "trait": "Straighter Hair on Average",
  "possibleTraits": ["Slightly Curlier Hair on Average", "Straighter Hair on Average"],
  "humanId": "5dc2527186aaf9de560e5841f1a44bd6"
}, {
  "userId": "52e20cb2fff56aac62000001",
  "description": "Male Pattern Baldness",
  "trait": "Decreased Odds",
  "possibleTraits": ["Decreased Odds", "Increased Odds", "No Data", "Not Applicable", "Typical Odds"],
  "humanId": "5dc2527186aaf9de560e5841f1a44bd6"
}, {
  "userId": "52e20cb2fff56aac62000001",
  "description": "Smoking Behavior",
  "trait": "Typical",
  "possibleTraits": ["If a Smoker, Likely to Smoke More", "Typical"],
  "humanId": "5dc2527186aaf9de560e5841f1a44bd6"
}]
# Get genetic traits associated with the user
curl -H "Authorization: Bearer demo" "https://api.humanapi.co/v1/human/genetic/traits"
Suggest Edits

Genotypes

Get genetic traits of a user

 

The genotypes endpoint has been deprecated by 23andMe. Users who provided access to their 23andMe account and had genetic data available via Human API will still have that data available through genetic/traits. However, any new data will not be retrievable.

Returns the base-pairs, like AA, for the given locations. The value can have Ds or Is for deletions and insertions (for example, DD or DI). It can be __ if the user is not on a chip that calls that location, or hasn’t yet unlocked their call since it corresponds to a sensitive report. It can be -- if the user is on a chip that calls that location, but it could not be determined. Hemizygous calls (such as on X-linked genes in males) will also return two base pairs.

Finally, due to locations and the fixed nature of genetic information, this endpoint cannot be queried by batch, nor can it be filtered by standard query parameters.

Note: This endpoint requires the locations query Parameter.

This list of SNPs (31MB) shows which SNPs are available. When requesting multiple locations, you will need to separate each location with a space (represented by %20 in an encoded URI). We recommend querying no more than 60 locations per request.

Returns a list of requested genotypes
GET https://api.humanapi.co/v1/human/genetic/genotypes

Response Properties

Property
Type
Description

id

String

The id of the resource.

genotypes

Array[Object]

An array of genotype objects (see below).

Genotypes Object

Property
Type
Description

location

String

Location of the genotype

call

String

Call of the genotype (see description above)

# Returns a json object of genotypes:
{
    "id": "c4480ba411939067",
    "genotypes": [
        {
            "location": "i3000001",
            "call": "II"
        },
        {
            "location": "rs3094315",
            "call": "AA"
        }
    ]
}
# Get specific genotypes associated with the user
curl "https://api.humanapi.co/v1/human/genetic/genotypes?access_token=demo&locations=rs3094315%20i3000001"
Suggest Edits

Heart Rate

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

 

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

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 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"
}
# Get the latest heart rate measurement associated with the user
curl -H "Authorization: Bearer demo" "https://api.humanapi.co/v1/human/heart_rate"
Suggest Edits

Heart Rate Summaries

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

 

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}

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

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

# 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"
  }
 ]
# Get the heart rate summaries associated with the user
curl -H "Authorization: Bearer demo" "https://api.humanapi.co/v1/human/heart_rate/summaries"
Suggest Edits

Height

Get the height measurement from a specific point in time.

 

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

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.

# 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"
}
# Get the latest height measurement associated with the user
curl -H "Authorization: Bearer demo" "https://api.humanapi.co/v1/human/height"
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.

 

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

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

# 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"
  }
}
# Get user's health summary 
curl -H "Authorization: Bearer demo" "https://api.humanapi.co/v1/human"
Suggest Edits

Locations

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

 

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

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

# 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"
}]
# Get locations measurement associated with the user
curl -H "Authorization: Bearer demo" "https://api.humanapi.co/v1/human/locations"
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.

 

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

Number

The amount of consumed calories

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

# 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"
}]
# Get all meals associated with the user
curl -H "Authorization: Bearer demo" "https://api.humanapi.co/v1/human/food/meals"
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.

 

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

# Returns a json object:
{
  "userId": "52e20cb2fff56aac62000001",
  "createdAt": "2014-01-24T06:48:18.361Z",
  "email": "demo@humanapi.co",
  "defaultTimeZone": {
    "name": "UTC"
  },
  "humanId": "5dc2527186aaf9de560e5841f1a44bd6"
}
# Get user's health profile
curl -H "Authorization: Bearer demo" "https://api.humanapi.co/v1/human/profile"
Suggest Edits

Sleeps

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

 

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

# 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"
}]
# Get all sleeps associated with the user
curl -H "Authorization: Bearer demo" "https://api.humanapi.co/v1/human/sleeps"
Suggest Edits

Sleep Summaries

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

 

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

# 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"
}]
# Get all sleep summaries associated with the user
curl -H "Authorization: Bearer demo" "https://api.humanapi.co/v1/human/sleeps/summaries"
Suggest Edits

Weight

Get the weight measurement from a specific point in time.

 

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

# 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"
}
# Get the latest weight measurement associated with the user
curl -H "Authorization: Bearer demo" "https://api.humanapi.co/v1/human/weight"
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

Name or 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 source (only for medical sources)

historySync

Object

See historySync object

syncStatus

Object

See syncStatus object

resync

Object

(optional) See resync object

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

(optional) 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"
Suggest Edits

Users

The users endpoint returns users of a specific app.

Users for your app are primarily created using Connect. This endpoint is best used for management of existing users.

As a part of the Application API this endpoint is authenticated using Basic Authentication. You must use your App Key as username and a blank password. Make sure you include the “:” after the username to avoid being asked to enter a password.

For a more detailed description on how to manage your app’s users, see the documentation here.

 

Response Properties

Property
Type
Description

humanId

String

The id of the user in Human API

externalId

String

The id of the user provided from your application

appId

String

Unique app identifier found in the Developer Portal.

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

Deletes a user
DELETE https://api.humanapi.co/v1/apps/{appId}/users/{humanId}
The response code for this is 204

# Delete a user
curl -X DELETE -u 1cf3900bd3968ab34344c9318342f6c3ca1456d3: https://api.humanapi.co/v1/apps/1479b39aa3476f92d7569485e3b3f6f773642ef/users/2242b2440ef1aab43719f202af316a2a
# Returns status code
204
# Returns a json array of users
[
  {
    "humanId": "0a34dca6b9fe0b2361038bd371d96539",
    "externalId": "sample.user1@example.com",
    "appId": "1d129c20acf6fcef9be0b067cc7859d872ed5ade",
    "createdAt": "2013-12-28T18:46:10.436Z",
    "updatedAt": "2013-12-29T05:05:50.601Z"
  },
  {
    "humanId": "8bd9999a4f902e609343dcb850361f23",
    "externalId": "sample.user2@example.com",
    "appId": "1d129c20acf6fcef9be0b067cc7859d872ed5ade",
    "createdAt": "2013-12-28T23:46:37.701Z",
    "updatedAt": "2013-12-28T23:46:37.701Z"
  },
  {
    "humanId": "f29b82027297553353acbf4901683830",
    "externalId": "sample.user3@example.com",
    "appId": "1d129c20acf6fcef9be0b067cc7859d872ed5ade",
    "createdAt": "2013-12-29T05:08:11.610Z",
    "updatedAt": "2013-12-29T05:08:11.610Z"
  }
]
# Get all users associated with an app
curl -X GET -H 'Accept: application/json' -u e7db255f4828e1d482743eba04faacb945ab7ca8: https://api.humanapi.co/v1/apps/1d129c20acf6fcef9be0b067cc7859d872ed5ade/users
Suggest Edits

Batch Query

Returns data for all of your app’s users in one query per data type.

These endpoints replicate those available for the individual user queries. The payload data model is the same for individual and batch queries, except the batch query results return a list multiple users so you need to parse the data accordingly.

As a part of the Application API this endpoint is authenticated using Basic Authentication. You must use your App Key as username and a blank password. Make sure you include the “:” after the username to avoid being asked to enter a password.

 

Activities
/apps/:clientId/users/activities

Activity Summaries
/apps/:clientId/users/activities/summaries

Heart Rates
/apps/:clientId/users/heart_rates

BMIs
/apps/:clientId/users/bmis

Body Fats
/apps/:clientId/users/body_fats

Heights
/apps/:clientId/users/heights

Weights
/apps/:clientId/users/weights

Blood Glucoses
/apps/:clientId/users/blood_glucoses

Blood Oxygens
/apps/:clientId/users/blood_oxygens

Blood Pressures
/apps/:clientId/users/blood_pressures

Genetic Traits
/apps/:clientId/users/genetic_traits

Locations
/apps/:clientId/users/locations

Meals
/apps/:clientId/users/food/meals

Sleeps
/apps/:clientId/users/sleeps

Sleep Summaries
/apps/:clientId/users/sleeps/summaries

Do not perform regular batch queries without the updated_since query parameter. By supplying updated_since with your last query time, you can ensure that your queries are quick and efficient.

For a more detailed description of batch queries including best practices, see the documentation.

Query Parameters

Parameter
Type
Description

updated_since

Date in YYYYMMDDTHHmmssZ format.

Use this in order to retrieve only the new data since your last query.

# Get activities for all of your users
curl -X GET -H 'Accept: application/json' \
    -u e7db255f4828e1d482743eba04faacb945ab7ca8: \
https://api.humanapi.co/v1/apps/1d129c20acf6fcef9be0b067cc7859d872ed5ade/users/activities
# Returns a json array of activities
[
  {
    "id": "52867cbfde3155565f000b01",
    "userId": "51cc7cb31a154bf215000002",
    "humanId": "7eddd553c81b8de9ac271bc21f50e32e",
    "startTime": "2013-11-01T17:27:00.346Z",
    "endTime": "2013-11-01T18:27:11.346Z",
    "type": "walking",
    "source": "runkeeper",
    "duration": 3611,
    "distance": 1251,
    "steps": 2689,
    "calories": 482,
    "timeZone": "America/Los_Angeles",
    "sourceData": {},
    "timeSeries": {},
    "createdAt": "2013-11-01T17:27:00.346Z",
    "updatedAt": "2013-11-01T17:27:00.346Z"
  },
  {
    "id": "52867cbfde3155565f000b02",
    "userId": "538b9d3a9b1e35be7302607e",
    "humanId": "7eddd553c81b8de9ac271bc21f50e32e",
    "startTime": "2014-05-31T16:18:19.000Z",
    "endTime": "2014-05-31T19:00:27.000Z",
    "type": "cycling",
    "source": "strava",
    "duration": 9728,
    "distance": 45468.6,
    "steps": 0,
    "calories": 0,
    "sourceData": {
      "maxHeartrate": 196,
      "averageHeartrate": 145,
      "maxSpeed": 17.3,
      "mapId": "a147785724",
      "movingTime": 7782,
      "type": "Ride"
    },
    "createdAt": "2014-05-31T19:03:32.032Z",
    "updatedAt": "2014-05-31T19:03:32.032Z"
  },
  {
    "id": "52867cbfde3155565f000b03",
    "userId": "538029c700850beb2601c578",
    "humanId": "7eddd553c81b8de9ac271bc21f50e32e",
    "startTime": "2014-05-28T20:04:02.000Z",
    "endTime": "2014-05-29T00:00:00.000Z",
    "type": "walking",
    "source": "mapmyfitness",
    "duration": 0,
    "distance": 178636.74,
    "steps": 0,
    "calories": 1916,
    "sourceData": { },
    "createdAt": "2014-05-31T00:21:09.386Z",
    "updatedAt": "2014-05-31T00:21:09.386Z"
  }
]

Response Properties

Property
Type
Description

humanId

String

The id of the user in Human API

externalId

String

The id of the user provided from your application

appId

String

Unique app identifier found in the Developer Portal.

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