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
breathingRate
Breathing/respiration rate
Biomarker
number
Floating point, unrestricted range
readiness*
Morning readiness
Insight
number
Int, 0-10
ansBalance*
ANS balance
Insight
number
Int, 1-5
signalQuality
Signal quality
Other
number
Int, 1-3
*require 2 readings on 2 separate days within 10 days or value will be null
Endpoints - Async
POST /submit/sdkData
From a Spren Vision SDK reading
POST
Params
Header Parameters
X-API-KEY
required
String
Your API key
Content-Type
required
String
"application/json"
Body Parameters
user
required
String
User ID
readingData
required
String
Spren Vision SDK reading data
﻿
POST /submit/deviceData
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
From an external measurement device
POST
Params
Header Parameters
X-API-KEY
required
String
Your API key
Content-Type
required
String
"application/json"
Body Parameters
user
required
String
User ID
readingData
required
Object
See Request Body Example and Request Body Schema tabs
﻿
GET /results/{guid}
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/Value
|
{
    "status": <string, "pending", "complete", or "error">
    "value": <number, optional, null on error, see Biomarkers/Insights section below for precision and range>,
    "errorDescription": <string, optional>
}
{
    "status": <string, "pending", "complete", or "error">
    "value": <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
number, see Biomarkers/Insights section below for precision and range
null
error
Calculation has errored
null
string, error encountered
With a GUID from a SDK or device data endpoint POST response
GET
Params
Header Parameters
X-API-KEY
required
String
Your API key
﻿
Endpoints - Sync
GET /populationComparison
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/Range
Result
|
{
    "mean": <number>,
    "range": [
        <range start, number>, 
        <range end, number>
    ]
}
{
    "mean": <number>,
    "range": [
        <range start, number>, 
        <range end, number>
    ]
}
﻿
For genders and age ranges
GET
Params
Body Parameters
X-API-KEY
required
String
Your API key
﻿
POST /submit/userData
Birthdate and gender for future intra-customer HR and HRV population comparisons
POST
Params
Header Parameters
X-API-KEY
required
String
Your API key
Content-Type
required
String
"application/json"
Body Parameters
user
required
String
User ID
birthdate
optional
String
User birthdate
gender
optional
String
User gender
﻿
﻿

Submit data

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

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
breathingRate	Breathing/respiration rate	Biomarker	number	Floating point, unrestricted range
readiness*	Morning readiness	Insight	number	Int, 0-10
ansBalance*	ANS balance	Insight	number	Int, 1-5
signalQuality	Signal quality	Other	number	Int, 1-3

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