Querying Health Data

Platform APIs do not support browser Javascript initiated calls that required specific CORS (Cross-origin resource sharing) domains to be allow listed, we recommend a BFF pattern in place of direct client interaction with platform APIs

Samples may be read by a Client acting on behalf of:

• the owner of Samples, or
• an Agent of the owners of Samples.

The procedure for reading Samples by the owner or an Agent differs only by the inclusion of an agency query token generated via the agency APIs. Simply add the following header to the request agency-query-token: <generated-token>

Please use the content in the Samples API specification as your primary source of details on how to handle requests and responses for health data samples.

Sample Data Schema

The SampleData object represents a single Sample in the DataServer. SampleDatas are the units that a Client uses to create Samples, and are the unit that are returned from querying the DataServer.

Examples

SampleData for Creating a Height Sample

{
    "Device": "man=\"Apple\";mod=\"iPhone\";hwv=\"iPhone9,4\";swv=\"10.3.3\"",
    "ClientAssignedId": "57128634578",
    "Type": "Height",
    "DateRange": {
        "LowerBound": "2018-01-22T10:55:21+00:00",
        "UpperBound": "2018-01-22T10:55:21+00:00",
    },
    "QuantityValue": 1.74
}

SampleData for Creating a Blood Pressure Sample

{
    "Device": "btn=\"A&A7236476\";swv=\"1.2\"",
    "ClientAssignedId": "8273647384",
    "Type": "blood_pressure",
    "DateRange": {
        "LowerBound": "2018-01-22T10:55:21+00:000",
        "UpperBound": "2018-01-22T10:55:21+00:000"
    },
    "CorrelationObjects": [
        {
            "Device": "btn=\"A&A7236476\";swv=\"1.2\"",
            "ClientAssignedId": "8273647385",
            "Type": "blood_pressure_systolic",
            "DateRange": {
                "LowerBound": "2018-01-22T10:55:21+00:000",
                "UpperBound": "2018-01-22T10:55:21+00:000"
            },
            "QuantityValue": 15998.7
        },
        {
            "Device": "btn=\"A&A7236476\";swv=\"1.2\"",
            "ClientAssignedId": "8273647386",
            "Type": "blood_pressure_diastolic",
            "DateRange": {
                "LowerBound": "2018-01-22T10:55:21+00:000",
                "UpperBound": "2018-01-22T10:55:21+00:000"
            },
            "QuantityValue": 12000
        }
    ]
}

Note the QuantityValues above are in Pascals, not Millimeters of Mercury, it is important that the correct quantity unit is observed when submitting samples.

Device

The device string should capture details about the type of device used to measure the Sample. It should not include particular device or user identifiers.

The Lenus convention used is to concatenate name value pairs of device information like so:

man="Apple";mod="iPhone";hwv="iPhone9,4";swv="10.3.3"

By convention, each name is three characters long, each value is double-quoted. Double-quotes within a value should be escaped thus \".

ClientAssignedId

The purpose of the ClientAssignedId is to:

• Avoid duplicate Samples being accidentally written by a Client
• Allow Clients to identify and retrieve specific Samples

Subject

The Subject of a Sample is the creator and owner, i.e. the person the Sample is about.

When creating a Sample, the SampleData’s Subject attribute is ignored – the identity of the owner is determined by authorization associated with the API call.

When a Client queries the DataServer on behalf of an Agent, the Subject value represents the unique relationship between the Agent and owner – the actual user identifier is hidden.

DateRange Object

The DateRange object represents a period or instant in time. If the upper and lower bounds are the same, the time represented is considered instant.