Spren HRV API

Summary

Spren HRV API is RESTful and partially async. It communicates with JSON request and response bodies. Authorization is in the header.

Environments

https://test.api.spren.com
https://prod.api.spren.com

Headers/Authorization

Header	Notes	Example
X-API-KEY	Your API key for authorization	X-API-KEY: <API key>
Content-Type	JSON, if request body present	Content-Type: application/json

Endpoints

POST /submit/sdkData
POST /submit/deviceData
GET /results/{guid}
GET /populationComparison
POST /submit/userData

Biomarkers and Insights

readiness and ansBalance require 2 readings on 2 separate days within 10 days or value will be null This will occur for a user's first reading OR after their first reading if they have not performed a reading in the last 10 days, and when this occurs an errorDescription of "baseline not set" is returned. See GET /results/{guid} below for more details.

Response Key	Description	Type	Data Type	Return Values
hr	Heart rate	Biomarker	number	Floating point, unrestricted range
hrvScore	HRV score	Biomarker	number	Floating point, 0-100
rmssd	RMSSD	Biomarker	number	Floating point, unrestricted range
breathingRate	Breathing/respiration rate	Biomarker	number	Floating point, unrestricted range
readiness*	Morning readiness	Insight	number	Int, 0-10
ansBalance*	ANS balance level	Insight	number	Int, 1-5
balance*	ANS balance	Insight	string	SNS \| PSNS
signalQuality	Signal quality	Other	number	Int, 1-3

*require 2 readings on 2 separate days within 10 days or value will be null for insights

Endpoints - Async

Submit data

From a Spren Vision SDK reading

POST

https://test.api.spren.com/submit/sdkData

{
    "user": "SuperAwesomeSprenUser",
    "readingData": "z6dWlcxi5EXAMPLErv48go0e7s25ucFcev8mzsT4s4oggpkEXAMPLEq74abn53c8a8rqOtfsZeqr6bawwae15al62xEyEXAMPLE"
}

While we accept interbeat intervals (IBIs) from any device, the following devices have been tested

Apple Watch
Polar H7, H9, and H10
Garmin HRM Dual and HRM Pro
Suunto Smart Belt
4iiii Viiiiva
Zephyr HxM
Cardiosport TP3
Ambiotex smart shirt with cardio-monitor
BlueLeza HRM Blue

Submit data

From an external measurement device

POST

https://test.api.spren.com/submit/deviceData

{
    "user": "SuperAwesomeSprenUser",
    "readingData" : {
        
        "timeInfo": {
            "timezoneAbbreviation": "EST",
            "readingStartTime": "2022-01-31T14:29:47.836-05:00",
            "timezoneId": "America/New_York",
            "regionCode": "US"
        },

        "ibis": [0.4843750298023224, 1.5517280101776123, 2.657050609588623, 3.7742903232574463, 4.8220062255859375, 5.828125, 6.844399929046631, 7.88457727432251, 8.874582290649414, 9.875000953674316, 10.967329025268555, 12.10489273071289, 13.176104545593262, 14.196523666381836, 15.272435188293457, 16.402050018310547, 17.508533477783203, 18.508146286010742, 19.565383911132812, 20.672771453857422, 21.826953887939453, 22.902862548828125, 23.955883026123047, 25.045291900634766, 26.14838218688965, 27.140625, 28.0631103515625, 29.03072738647461, 30.06393051147461, 31.15479278564453, 32.248600006103516, 33.2828369140625, 34.322052001953125, 35.37783432006836, 36.442169189453125, 37.405731201171875, 38.28491973876953, 39.21875, 40.21875, 41.2934455871582, 42.304595947265625, 43.25, 44.24182891845703, 45.2844352722168, 46.29751968383789, 47.407127380371094, 48.56134033203125, 49.62022399902344, 50.61715316772461, 51.67640686035156, 52.78999328613281, 53.88925552368164, 54.94934844970703, 56.047752380371094, 57.1885871887207, 58.228050231933594, 59.27463150024414, 60.37499997019768, 61.511565804481506, 62.5560462474823, 63.58746147155762, 64.65309286117554, 65.76651000976562, 66.74961137771606, 67.78284978866577, 68.83904552459717, 69.81901168823242, 70.83590984344482, 71.9028434753418, 73.02445411682129, 74.03125, 75.09842586517334, 76.24885749816895, 77.40503883361816, 78.48084449768066, 79.59456634521484, 80.71140098571777, 81.6954460144043, 82.7123031616211, 83.77799224853516, 84.8914566040039, 85.89860343933105, 86.88304710388184, 87.91612434387207, 89.01422882080078, 90.03980827331543, 91.07221603393555, 92.15488052368164, 93.27340316772461, 94.42807006835938, 95.55830001831055, 96.65484619140625, 97.79670715332031, 98.91775512695312, 100.0401725769043, 101.07981491088867, 102.06212997436523, 103.09540176391602, 104.18608856201172, 105.26212692260742, 106.20312118530273, 107.1871223449707, 108.24712753295898, 109.34455108642578, 110.3766098022461, 111.44198608398438, 112.5404052734375, 113.64141082763672, 114.65488052368164, 115.60173034667969, 116.58527755737305, 117.67549896240234, 118.80835723876953, 119.85273742675781, 120.89062494039536, 122.00082588195801, 123.14705157279968, 124.25875854492188, 125.3061637878418, 126.35422229766846, 127.45398759841919, 128.60808849334717, 129.73786735534668, 130.734375, 131.7749319076538, 132.8654270172119, 133.97714042663574, 135.07672595977783, 136.07035446166992, 137.1374282836914, 138.23282432556152, 139.33598518371582, 140.385591506958, 141.32812690734863, 142.29640007019043, 143.34667015075684, 144.45397567749023, 145.5405979156494, 146.53087043762207, 147.5640640258789, 148.63706588745117, 149.70759201049805, 150.71924018859863, 151.71843910217285, 152.74370193481445, 153.81671524047852, 154.79243087768555, 155.76891708374023, 156.8154640197754, 157.9302635192871, 159.03949737548828, 160.0385971069336, 161.03913497924805, 162.0733299255371, 163.13729858398438, 164.21561431884766, 165.26880645751953, 166.37579727172852, 167.48523712158203, 168.57672119140625, 169.53887176513672, 170.4471778869629, 171.37500381469727, 172.37499618530273, 173.3820915222168, 174.4233741760254, 175.42995834350586, 176.3671531677246, 177.34336471557617, 178.40122604370117, 179.48114013671875, 180.484375, 181.47623324394226, 182.47652959823608, 183.51719069480896, 184.531964302063, 185.4995265007019, 186.46076440811157, 187.47742462158203, 188.5016269683838, 189.54054927825928, 190.53085708618164, 191.54897117614746, 192.6414270401001, 193.7691478729248, 194.8837947845459, 195.890625, 196.88312530517578, 197.91597366333008, 198.97961807250977, 200.05919075012207, 201.0953254699707, 202.16857528686523, 203.25482940673828, 204.21105575561523, 205.14818954467773, 206.14062690734863, 207.1816349029541, 208.23711967468262, 209.30925941467285, 210.4228115081787, 211.5224323272705, 212.5230941772461, 213.53190994262695, 214.56406784057617, 215.54646682739258, 216.5797882080078, 217.67046737670898, 218.67993927001953, 219.65573501586914, 220.65625, 221.6724967956543, 222.659912109375, 223.68122482299805, 224.74639129638672],
        "ibiResolution": "1",
        
        "deviceType": "watch",
        "deviceModel": "6",
        "deviceBrand": "apple",
        "sourceApp": "appleHealth",

        "additionalData": "{ \"spo2\": 97}"
    }
}

For certain insights, a minimum number of readings are required. See the Biomarkers/Insights section.

Status/Value

For each biomarker or insight, a status/value JSON object is returned

{
    "status": <string, "pending", "complete", or "error">
    "value": <string, number, optional, null on error, see Biomarkers/Insights section below for precision and range>,
    "errorDescription": <string, optional>
}

State Permutations

status	Description	value (for calculated Biomarker/Insight)	errorDescription
pending	Calculation is in progress	null	null
complete	Calculation is complete	string, number, see Biomarkers/Insights section below for precision and range	null
error	Calculation has errored	null	string, error encountered

Get biomarkers and insights

With a GUID from a SDK or device data endpoint POST response

GET

https://test.api.spren.com/results/{guid}

// see the Biomarkers/Insights section for additional info about "value" precision and range
{
    "biomarkers": {
        "hr": {
            "value": 79.7994974014928,
            "status": "complete",
            "errorDescription": null
        },
        "hrvScore": {
            "value": 61.691193950645186,
            "status": "complete",
            "errorDescription": null
        },
        "rmssd": {
            "value": 51.25768235103885,
            "status": "complete",
            "errorDescription": null
        },
        "breathingRate": {
            "value": 11.7,
            "status": "complete",
            "errorDescription": null
        }
    },
    "insights": {
        "readiness": {
            "value": null,
            "status": "complete",
            "errorDescription": null
        },
        "ansBalance": {
            "value": null,
            "status": "complete",
            "errorDescription": null
        },
        "balance": {
            "value": null,
            "status": "complete",
            "errorDescription": null
        }
    },
    "signalQuality": {
        "value": 2,
        "status": "complete",
        "errorDescription": null
    }

    ... stress insight coming soon!
}

Endpoints - Sync

Types in Response

Gender

male
female
other

Age Range

age-18-25
age-26-35
age-36-45
age-46-55
age-56-65
age-66-1000

Mean/Range Object, Result Object

{
    "mean": <number>,
    "range": [
        <range start, number>, 
        <range end, number>
    ]
}

Get population comparison data

For genders and age ranges

GET

https://test.api.spren.com/populationComparison

curl --location --request GET 'https://test.api.spren.com/populationComparison' \
--header 'X-API-KEY: YourSprenAPIKey'

Submit user data

Birthdate and gender for future intra-customer HR and HRV population comparisons

POST

https://test.api.spren.com/submit/userData

{
    "user": "SuperAwesomeSprenUser",
    "birthdate": "2017-09-19",
    "gender": "female">
}

Spren HRV API

Summary

Environments

Headers/Authorization

Endpoints

Biomarkers and Insights

Endpoints - Async

POST /submit/sdkData

POST /submit/deviceData

GET /results/{guid}

Status/Value

Endpoints - Sync

GET /populationComparison

Types in Response

POST /submit/userData