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

Header Parameters

X-API-KEYstringrequired
Description
Your API key
Content-Typestringrequired
Description
"application/json"

Body Parameters

userstringrequired
Description
User ID
readingDatastringrequired
Description
Spren Vision SDK reading data

Request Body Example

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

Request Body Schema

{
    "user": <string, user ID>,
    "readingData": <string, Spren Vision SDK reading data>
}

curl

curl --location --request POST 'https://test.api.spren.com/submit/sdkData' \
--header 'X-API-KEY: YourSprenAPIKey' \
--header 'Content-Type: application/json' \
--data-raw '{"user":"SuperAwesomeSprenUser", "readingData": "z6dWlcxi5EXAMPLErv48go0e7s25ucFcev8mzsT4s4oggpkEXAMPLEq74abn53c8a8rqOtfsZeqr6bawwae15al62xEyEXAMPLE"}'

200

{"guid": "IOWQ4fDEXAMPLEQM+ey7N9WgVhSnQ6JEXAMPLEZb7hSQDASK+Jd1vEXAMPLEa3Km"}

401

{
    "message": "Bad request error; please check that your payload and parameters are formatted correctly."
}

404

{
    "message": "Authentication/Authorization error; please check that your authorization information is correct."
}

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

Header Parameters

X-API-KEYstringrequired
Description
Your API key
Content-Typestringrequired
Description
"application/json"

Body Parameters

userstringrequired
Description
User ID
readingDataObjectrequired
Description
See Request Body Example and Request Body Schema tabs

Request Body Example

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

        "ibis": [1195,1117,1184,1272,1329,1305,1308,1211,1110,1098,1292,1418,1368,1372,1307,1194,1077,1140,1373,1363,1328,1303,1191,1042,954,1011,1396,1360,1363,1348,1262,1172,1183,1309,1338,1317,1264,1171,1051,1111,1317,1330,1303,1240,1153,1042,1088,1288,1265,1304,1241,1168,1060,1106,1223,1273,1265,1244,1173,1054,1004,1084,1252,1284,1210,1108,1128,1062,1072,1188,1289,1278,1251,1178,1055,1011,1090,1231,1293,1278,1225,1128,1048,1064,1177,1256,1220,1193,1175,1129,1056,994,981,1209,1314,1271,1255,1208,1113,1002,981,1164,1322,1302,1264,1216,1115,1044,1082,1227,1245,1224,1189,1181,1127,1087,1046,1187,1307,1322,1282,1232,1126,1039,1010,1154,1305,1292],
        "ibiResolution": "1/1024",
        
        "deviceType": "bluetoothChestStrap",
        "deviceModel": "H7",
        "deviceBrand": "Polar",
        "sourceApp": "Health",

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

Request Body Schema

{
    "user": <user, string>,
    "readingData" : {
        
        "timeInfo": {
            "timezoneAbbreviation": <string, e.g., "EST">,
            "readingStartTime": <datetime string - "yyyy-MM-dd'T'HH:mm:ss.SSSZZZZZ", e.g., "2022-01-31T14:29:47.836-05:00">,
            "timezoneId": <string timezone id, e.g., "America/New_York">,
            "regionCode": <string region code, e.g., "US">
        },

        "ibis": [<number, minimum of 50 ibis, limited to 10 minutes>],
        "ibiResolution": <"1/1000" or "1/1024", or "1" for Apple Watch>,
        
        "deviceType":  <required if sourceApp not set, string>,
        "deviceModel": <optional, string>,
        "deviceBrand": <optional, string>,
        "sourceApp":   <required if deviceType not set, string>,

        "additionalData": <optional, JSON string, e.g., "{ \"spo2\": 97}", limited to 300KB>
    }
}

Apple Watch Example

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

curl

curl --location --request POST 'https://test.api.spren.com/submit/deviceData' \
--header 'X-API-KEY: YourSprenAPIKey' \
--header 'Content-Type: application/json' \
--data-raw '{"user":"SuperAwesomeSprenUser","readingData":{"timeInfo":{"timezoneAbbreviation":"EST","readingStartTime":"2022-01-31T14:29:47.836-05:00","timezoneId":"America/New_York","regionCode":"US"},"ibis":[1195,1117,1184,1272,1329,1305,1308,1211,1110,1098,1292,1418,1368,1372,1307,1194,1077,1140,1373,1363,1328,1303,1191,1042,954,1011,1396,1360,1363,1348,1262,1172,1183,1309,1338,1317,1264,1171,1051,1111,1317,1330,1303,1240,1153,1042,1088,1288,1265,1304,1241,1168,1060,1106,1223,1273,1265,1244,1173,1054,1004,1084,1252,1284,1210,1108,1128,1062,1072,1188,1289,1278,1251,1178,1055,1011,1090,1231,1293,1278,1225,1128,1048,1064,1177,1256,1220,1193,1175,1129,1056,994,981,1209,1314,1271,1255,1208,1113,1002,981,1164,1322,1302,1264,1216,1115,1044,1082,1227,1245,1224,1189,1181,1127,1087,1046,1187,1307,1322,1282,1232,1126,1039,1010,1154,1305,1292],"ibiResolution":"1/1024","deviceType":"bluetoothChestStrap","deviceModel":"H7","deviceBrand":"Polar","sourceApp":"Health","additionalData":"{\"spo2\": 97}"}}'

200

{"guid": "IOWQ4fDEXAMPLEQM+ey7N9WgVhSnQ6JEXAMPLEZb7hSQDASK+Jd1vEXAMPLEa3Km"}

400

{
    "message": "Bad request error; please check that your payload and parameters are formatted correctly."
}

401

{
    "message": "Authentication/Authorization error; please check that your authorization information is correct."
}

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}

Header Parameters

X-API-KEYstringrequired
Description
Your API key

Response Body Example

// 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!
}

Response Body Schema

{
    "biomarkers": {
        <biomarker name, string>: <status/value, see above>,
        ...
    }
    "insights": {
        <insight name, string>: <status/value, see above>,
        ...
    }
    "signalQuality": <status/value, see above>
}

curl

curl --location --request GET 'https://test.api.spren.com/results/IOWQ4fDEXAMPLEQM+ey7N9WgVhSnQ6JEXAMPLEZb7hSQDASK+Jd1vEXAMPLEa3Km' \
--header 'X-API-KEY: YourSprenAPIKey'

200

// see Response Body Example
{ ... }

400

{
    "message": "Bad request error; please check that your payload and parameters are formatted correctly."
}

401

{
    "message": "Authentication/Authorization error; please check that your authorization information is correct."
}

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

Body Parameters

X-API-KEYstringrequired
Description
Your API key

Response Body Example

{
  "hrv": {
    "result": {
      "mean": 59.48192017501054,
      "range": [
        24.884232390998157,
        94.07960795902292
      ],
      "byGender": {
        "male": {
          "mean": 59.15151765546141,
          "range": [
            24.553829871449025,
            93.7492054394738
          ]
        },
        "female": {
          "mean": 58.14132921101882,
          "range": [
            23.543641427006435,
            92.7390169950312
          ]
        },
        "other": {
          "mean": 59.48820715817252,
          "range": [
            30.65680067149553,
            88.31961364484951
          ]
        }
      }
    },
    "age-18-25": {
      "result": {
        "mean": 67.30673952641166,
        "range": [
          38.47533303973467,
          96.13814601308866
        ],
        "byGender": {
          "male": {
            "mean": 67.70155230781934,
            "range": [
              38.87014582114235,
              96.53295879449632
            ]
          },
          "female": {
            "mean": 65.13206135428358,
            "range": [
              42.066936164941986,
              88.19718654362518
            ]
          },
          "other": {
            "mean": 0,
            "range": [
              0,
              0
            ]
          }
        }
      }
    }
    ... 
  },
  "hr": {
    // see HRV above
    ...
  }
}

Response Body Schema

{
		"hrv": {
				<result>,
				<age range, string>: {
						<result>,
				}
		},
		"hr": {
				<result>,
				<age range, string>: {
						<result>,
				}
		}
}

curl

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

200

// see Response Body Example
{ ... }

400

{
    "message": "Bad request error; please check that your payload and parameters are formatted correctly."
}

401

{
    "message": "Authentication/Authorization error; please check that your authorization information is correct."
}

Submit user data

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

POST

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

Header Parameters

X-API-KEYstringrequired
Description
Your API key
Content-Typestringrequired
Description
"application/json"

Body Parameters

userstringrequired
Description
User ID
birthdatestring
Description
User birthdate
genderstring
Description
User gender

Request Body Example

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

Request Body Schema

{
    "user": <string>,
    "birthdate": <optional string, yyyy-MM-dd>,
    "gender": <optional string, "male", "female", or "other">
}

curl

curl --location --request POST 'https://test.api.spren.com/submit/userData' \
--header 'X-API-KEY: YourSprenAPIKey' \
--header 'Content-Type: application/json' \
--data-raw '{"user":"SuperAwesomeSprenUser","birthdate": "2017-09-19","gender": "female"}'

200

{}

400

{
    "message": "Bad request error; please check that your payload and parameters are formatted correctly."
}

401

{
    "message": "Authentication/Authorization error; please check that your authorization information is correct."
}

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