Results API

Introduction
This is the API documentation for the IntelliProve results API, which allows you to request results for past health checks based on the health check UUID.
Prerequisites
If you are new to this developer portal, we recommend first reading the Plug-in: overview﻿, a five-minute read which will get you acquainted with how our plug-in works and how it can be integrated into your platform. To integrate the plug-in into your platform, follow our Plug-in﻿ documentation.
Keep in mind that this API is mainly geared towards backend functionality such as requesting results of past health checks, getting history for specific users, deleting data, etc. The actual health check is performed using our web plug-in﻿.
Setup
Environments
As a customer, you will receive information about the environment (API base URL) to use for development and production.
Authentication
All the endpoints described below require an API key or a bearer token in the header for authentication purposes.
API Key
An API key forms a permanent access key to authenticate with the API. Your API key should never be exposed in your front-end and only be used on protected servers and back-end systems.
API keys are sent in the header of the request:
x-api-key: <your-api-key> 
No API key and interested in our product? Contact us ([email protected]) or set up a call﻿
Action Tokens
﻿These are JWT Tokens with an expiry date that only provide access to 'action routes'. They are generated with your API key and are perfect for doing API calls from front-end applications. Action Tokens have a max lifetime of 12 hours.﻿
Action tokens are sent in the header of the request:
authorization: Token <ActionToken>
You can use our Create action token﻿ endpoint to request one.
For security reasons, action tokens only provide access to a restricted set of routes. The available routes are listed below:
"Get results" route
Results by measurement UUID
We provide the results in two different formats: simple 'results' and 'buckets'.
The simple results of a health check contain the values for each biomarker, without further context. The buckets contain more context, such as the optimum, max and minimum for each biomarker.
The meaning of the 'results' and 'bucket' objects is further explained in the Message events﻿. More information about the actual biomarkers we measure can be found on the following page: Insights & biomarkers﻿﻿
﻿
Use the below endpoint to request the results of a previously performed health check. Note that we recommend listening to events, as described in Plug-in: events﻿, in case you want to obtain the results right after the user completes the measurement.
﻿
Whereas the above endpoint returns immediately if no results are available (yet), some use cases might require the use of long polling to wait while your video is still processing.
This request long-polls our database for up to 20 seconds, returning the results as soon as they are available or returning a HTTP 202 if no results were found after this time has expired.
GET
Request Params
Path Params
uuid
required
String
The uuid of the health check for which to fetch the results
Curl
curl --location 'https://engine.intelliprove.com/v1/results/wait/your-video-uuid' \
--header 'Accept: application/json' \
--header 'x-api-key: your-api-key'
curl --location 'https://engine.intelliprove.com/v1/results/wait/your-video-uuid' \
--header 'Accept: application/json' \
--header 'x-api-key: your-api-key'
Responses
200
202
401
422
{
    "timestamp_epoch": 1670921835,
    "timestamp": "2022-12-13T08:57:15+00:00",
    "heart_rate": 112,
    "respiratory_rate": 13,
    "heart_rate_variability": 161,
    "ans_balance": 1,
    "resonant_breathing_score": 30,
    "morning_readiness": 7,
    "acute_mental_stress_score": 3,
    "mental_health_risk": 1
}
{
    "timestamp_epoch": 1670921835,
    "timestamp": "2022-12-13T08:57:15+00:00",
    "heart_rate": 112,
    "respiratory_rate": 13,
    "heart_rate_variability": 161,
    "ans_balance": 1,
    "resonant_breathing_score": 30,
    "morning_readiness": 7,
    "acute_mental_stress_score": 3,
    "mental_health_risk": 1
}
﻿
If the measurement was successfully processed, you will receive the biomarkers in json format, as shown in the example responses above with the HTTP 200 status code.
However, in case the video did not meet the Video input requirements﻿, an error code will be returned to the body of the response. Refer to the example response above with HTTP 422 status. 
The error code refers to why the video could not be processed. Examples of input requirements not being met, include too little light, excessive movement of the subject during the video, or a framerate that is too low.
A list of all possible error codes, their explanation and suggested messages towards the user can be found in the table below (click open with the arrow).
List of possible result error codes
Result Error Code
Error Type
Explanation
1
VideoFileError
The device or camera lacks the necessary performance for conducting a high-quality health scan. We recommend using another device with a better quality camera
2
VideoTooShortError
The video is not long enough
21
FpsTooLowError
The video does not meet the minimal FPS threshold.
22
CodecNotSupportedError
The video codec is not in the list of supported codecs.
23
BitrateTooLowError
The video bitrate does not meeting our minimal bitrate threshold.
3
NoFaceDetectedError
A face could not be accurately detected in the video.
4
InsufficientVisibleSkinError
Insufficient skin is visible, e.g. due to the face being partially covered, making an accurate health scan unfeasible.
5
MovedOutOfFrame
The subject's face (partially) moved out of frame during the recording.
99
UnexpectedError
Something unexpected happened. We will look into this.
﻿
In some cases, the video quality or lighting conditions might be insufficient to calculate certain parameters which rely on very subtle fluctuations, such as SDNN, but sufficient for other parameters like HR and RR. In these cases, the response will contain a None for the parameters for which quality was insufficient
﻿
﻿
The buckets corresponding to a health check can be requested using the below endpoint.
Get all the buckets corresponding to a health check. 
GET
Request Params
Path Params
uuid
required
String
The uuid of the health check for which to fetch the buckets
Curl
curl --location 'https://engine.intelliprove.com/v1/results/wait/your-video-uuid' \
--header 'Accept: application/json' \
--header 'x-api-key: your-api-key'
curl --location 'https://engine.intelliprove.com/v1/results/wait/your-video-uuid' \
--header 'Accept: application/json' \
--header 'x-api-key: your-api-key'
Responses
200
400
401
422
{
    "uuid": "4b7b6dc34ddd413e8ce14dbac8e640c4",
    "buckets": [
        {
            "name": "physical",
            "timestamp_epoch": 1707081928,
            "timestamp": "2024-02-04T22:25:28+01:00",
            "status": "bad",
            "biomarkers": [
                {
                    "name": "heart_rate",
                    "value": 88.0,
                    "zone": "bad",
                    "unit": "bpm",
                    "range": [
                        36.0,
                        216.0
                    ],
                    "optimum": "low"
                },
                {
                    "name": "respiratory_rate",
                    "value": 7.0,
                    "zone": "good",
                    "unit": "brpm",
                    "range": [
                        4.0,
                        48.0
                    ],
                    "optimum": "middle"
                }
            ],
            "history": [
                {
                    "biomarkers": {
                        "heart_rate": 77.0,
                        "respiratory_rate": 15.0
                    },
                    "timestamp_epoch": 1708030833,
                    "timestamp": "2024-02-15T22:00:33+01:00"
                },
                {
                    "biomarkers": {
                        "heart_rate": 62.0,
                        "respiratory_rate": 11.0
                    },
                    "timestamp_epoch": 1708029278,
                    "timestamp": "2024-02-15T21:34:38+01:00"
                },
                }
            ]
        },
        {
            "name": "mental",
            "timestamp_epoch": 1707081928,
            "timestamp": "2024-02-04T22:25:28+01:00",
            "status": "good",
            "biomarkers": [...],
            "history": [...]
        },
        ...
    ]
}
{
    "uuid": "4b7b6dc34ddd413e8ce14dbac8e640c4",
    "buckets": [
        {
            "name": "physical",
            "timestamp_epoch": 1707081928,
            "timestamp": "2024-02-04T22:25:28+01:00",
            "status": "bad",
            "biomarkers": [
                {
                    "name": "heart_rate",
                    "value": 88.0,
                    "zone": "bad",
                    "unit": "bpm",
                    "range": [
                        36.0,
                        216.0
                    ],
                    "optimum": "low"
                },
                {
                    "name": "respiratory_rate",
                    "value": 7.0,
                    "zone": "good",
                    "unit": "brpm",
                    "range": [
                        4.0,
                        48.0
                    ],
                    "optimum": "middle"
                }
            ],
            "history": [
                {
                    "biomarkers": {
                        "heart_rate": 77.0,
                        "respiratory_rate": 15.0
                    },
                    "timestamp_epoch": 1708030833,
                    "timestamp": "2024-02-15T22:00:33+01:00"
                },
                {
                    "biomarkers": {
                        "heart_rate": 62.0,
                        "respiratory_rate": 11.0
                    },
                    "timestamp_epoch": 1708029278,
                    "timestamp": "2024-02-15T21:34:38+01:00"
                },
                }
            ]
        },
        {
            "name": "mental",
            "timestamp_epoch": 1707081928,
            "timestamp": "2024-02-04T22:25:28+01:00",
            "status": "good",
            "biomarkers": [...],
            "history": [...]
        },
        ...
    ]
}
﻿
﻿
The below endpoint allows you to fetch the summary and tips corresponding to each bucket.
Get the summary and tip for each of the buckets of a health check. 
GET
Request Params
Path Params
uuid
required
String
The uuid of the health check for which to fetch the buckets
Query Parameters
include_tips
optional
Boolean
Whether to include a tip for each bucket
language
optional
String
The language in which to return the results
Curl
curl --location 'https://engine.intelliprove.com/v1/results/wait/your-video-uuid' \
--header 'Accept: application/json' \
--header 'x-api-key: your-api-key'
curl --location 'https://engine.intelliprove.com/v1/results/wait/your-video-uuid' \
--header 'Accept: application/json' \
--header 'x-api-key: your-api-key'
Responses
200
400
401
404
406
422
{
    "detail": "Resource not found." // we currently do not provide feedback/tips for this scenario
}
{
    "detail": "Resource not found." // we currently do not provide feedback/tips for this scenario
}
﻿
Results by patient ID
Use this endpoint to obtain results related to a patient (user) and/or performer.
Get the history of results for one or more patients based on patient and/or performer reference.
GET
Request Params
Query Parameters
patient-ref
optional
String
Patient for which the health checks are retrieved.
performer-ref
optional
String
Additional filter on performer reference.
start
required
String
Date time string value in ISO 8601 format
page
required
Integer
Page of pagination
page_size
optional
Integer
Number of items to return per page of pagination
Curl
curl --location 'https://engine.intelliprove.com/v1/patient/history?page=0&patient-ref=your-patient-ref&start=2022-03-27%2015%3A10%3A29&sort_by=timestamp&sort_desc=false' \
--header 'x-api-key: your-api-key'
curl --location 'https://engine.intelliprove.com/v1/patient/history?page=0&patient-ref=your-patient-ref&start=2022-03-27%2015%3A10%3A29&sort_by=timestamp&sort_desc=false' \
--header 'x-api-key: your-api-key'
Responses
200
400
401
{
    "data": [
        {
            "timestamp_epoch": 1678100000,
            "timestamp": "2023-03-06T10:00:00+01:00",
            "heart_rate": 60,
            "respiratory_rate": 13,
            "heart_rate_variability": 48,
            "ans_balance": 1,
            "resonant_breathing_score": 30,
            "patient": "a84kgh404a",
            "performer": "pa7xb48209",
            "morning_readiness": null,
            "acute_mental_stress_score": 4,
            "mental_health_risk": 4
        },
        {
            "timestamp_epoch": 1678200030,
            "timestamp": "2023-04-06T10:00:00+01:00",
            "heart_rate": 57,
            "respiratory_rate": 12,
            "heart_rate_variability": 48,
            "ans_balance": 1,
            "resonant_breathing_score": 40,
            "patient": "a84kgh404a",
            "performer": "pa7xb48209",
            "morning_readiness": 3,
            "acute_mental_stress_score": 4,
            "mental_health_risk": 4
        }
    ],
    "pagination": {
        "page": 0,
        "page_size": 10,
        "sorted_by": "timestamp",
        "sorting_order": "asc",
        "sorting_options": [
            "timestamp",
            "performer"
        ]
    }
}
{
    "data": [
        {
            "timestamp_epoch": 1678100000,
            "timestamp": "2023-03-06T10:00:00+01:00",
            "heart_rate": 60,
            "respiratory_rate": 13,
            "heart_rate_variability": 48,
            "ans_balance": 1,
            "resonant_breathing_score": 30,
            "patient": "a84kgh404a",
            "performer": "pa7xb48209",
            "morning_readiness": null,
            "acute_mental_stress_score": 4,
            "mental_health_risk": 4
        },
        {
            "timestamp_epoch": 1678200030,
            "timestamp": "2023-04-06T10:00:00+01:00",
            "heart_rate": 57,
            "respiratory_rate": 12,
            "heart_rate_variability": 48,
            "ans_balance": 1,
            "resonant_breathing_score": 40,
            "patient": "a84kgh404a",
            "performer": "pa7xb48209",
            "morning_readiness": 3,
            "acute_mental_stress_score": 4,
            "mental_health_risk": 4
        }
    ],
    "pagination": {
        "page": 0,
        "page_size": 10,
        "sorted_by": "timestamp",
        "sorting_order": "asc",
        "sorting_options": [
            "timestamp",
            "performer"
        ]
    }
}
﻿
Update metadata
If required, you can update the metadata for a measurement after completing processing.
Update the performer and/or patient refernences for a measurement.
PUT
Request Params
Body Parameters
performer-ref
optional
String
An optional reference for the performer of the measurement
patient-ref
optional
String
An optional reference for the patient on whom the measurement was performed
Curl
curl --location --globoff --request PUT 'https://engine.intelliprove.com/v1/results/update/{uuid}' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--data '{"performer-ref":"string","patient-ref":"string"}'
curl --location --globoff --request PUT 'https://engine.intelliprove.com/v1/results/update/{uuid}' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--data '{"performer-ref":"string","patient-ref":"string"}'
Responses
204
400
401
403

﻿
﻿
TABLE OF CONTENTS
Introduction
Results by measurement UUID
GET
Wait for results
List of possible result error codes
Results by patient ID
Update result metadata
Result Error Code	Error Type	Explanation
1	VideoFileError	The device or camera lacks the necessary performance for conducting a high-quality health scan. We recommend using another device with a better quality camera
2	VideoTooShortError	The video is not long enough
21	FpsTooLowError	The video does not meet the minimal FPS threshold.
22	CodecNotSupportedError	The video codec is not in the list of supported codecs.
23	BitrateTooLowError	The video bitrate does not meeting our minimal bitrate threshold.
3	NoFaceDetectedError	A face could not be accurately detected in the video.
4	InsufficientVisibleSkinError	Insufficient skin is visible, e.g. due to the face being partially covered, making an accurate health scan unfeasible.
5	MovedOutOfFrame	The subject's face (partially) moved out of frame during the recording.
99	UnexpectedError	Something unexpected happened. We will look into this.