The IntelliProve API is your one-stop shop for extracting biomarkers and obtaining insights from facial video data. These API docs describe how to integrate our API into your platform and obtain an objective look into mental and physical health status.
Getting started as a developer
Hi there! You obviously want to know what the quickest way is to get started performing health scans with our API.
We recommend first reading the API flow, a five minute read which will get you acquainted with how the API works through an example and give useful guidelines for integration. It also references back to the API endpoints in this document. If you're just starting out, go there first.
Next, you can try out the process yourself. The easiest way to perform your first health scan through our API is by downloading the OpenAPI spec below and importing it in a tool like Postman. Then, execute the steps in Postman, as layed out below in the sequence diagram. The video below, which walks you through the steps of performing a health scan using Postman from scratch, can help clear any uncertainties during the process.
After this, you should be suffciently acquainted with the API, and able to start the integration into your own platform. You may want to use one of our SDKs for this, depending on your specific platform.
Sequence diagram with API calls
Environments
As a customer, you will receive information about environment (API base URL) to use for testing or 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 or temporary 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: <apikey>
No API key and interested in our product? Contact us (info@intelliprove.com) or set up a call
Auth0 Bearer Token
Use the IntelliProve Auth0 IdP to log in and get a temporary access token. Use this token as Bearer for the API calls.
Bearer tokens are sent in the header of the request:
authorization: Bearer <Token>
Action Tokens
JWT Tokens with an expiry date that only provide access to 'action routes'. These 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>
For security reasons, action tokens only provide access to a restricted set of routes. The available routes are listed below:
"Check conditions" route
"Process video" route
Routes for streaming (SDK only)
"Get results" route
Auth endpoints
Use this endpoint to retrieve user information for the current user. The user information defines to which user group and customer you belong.
{"status":403,"reason":"Missing or invalid authentication credentials."}
Create a new action token with optional custom lifetime and custom metadata. Do not place confidential information in the metadata object.
This endpoint can only be called with an API key.
POST
Params
Body Parameters
expire_in
optional
Integer
Lifetime of the token in seconds. Defaults to 6 hours, maximum 12 hours.
meta
optional
Object
Custom metadata to place in the action token.
Curl
Node.js
JS
Python
Ruby
|
curl --location --request POST 'https://engine.intelliprove.com/v1/auth/action-token'\
--header 'Accept: application/json'\
--data-raw '{"expire_in":"Integer","meta":"Object"}'
Get an upload URL, for uploading a video to be processed;
Process uploaded videos in order to obtain mental biomarkers;
Perform quality checks in order to assess video quality, health check setup and environment
Keep the technical requirements in mind during video recording. See: Technical requirements
Use this endpoint to check wether your video qualifies to perform a health scan, in terms of lighting, subject pose and framing. Take a snapshot image of the video preview, with the patient in the frame and upload this via formdata. Our custom quality check algorithm will return a quality score for your current measurement setup.
In case your conditions are met, you will receive a quality score greater than or equal to 5. You can safely start a measurement with the current conditions.
Insufficient lighting or bad framing will result in quality score that is lower than 5. Follow the instructions in the prompt property or check the quality error code for more information.
POST
Params
Form Parameters
image
required
Object
Frame of the patient's face, to check if conditions are met.
{"detail":"Missing or invalid authentication credentials."}
The table below gives an overview of the different possible quality error codes in the response, with corresponding explanation.
Quality Error Code
Description
0
No error
1
You're too close
2
Move closer
3
Align and center your face with the camera
4
Your chest is not visible enough
5
Point your face to the camera
6
Make sure your face is well lit and the light is evenly spread on your face
7
Lower your face
8
No face detected
9
Make sure your forehead is visible
Get a temporary URL and credentials for our S3 bucket, which you can use to upload your video. This requires a valid signature received from the quality check call. Without a valid signature your request will be rejected.
Mind that these credentials are only valid for 300 seconds. Furthermore, the upload size for your video is restricted to 150MB.
The table below gives more information about the response.
Property
Description
uuid
Unique identifier for the uploaded video. Important throughout following steps, as this uniquely identifies this current health scan.
url
Upload URL to the S3 Bucket.
form_data_fields
Form-properties for multipart uploading to the S3 Bucket.
Use the url and form_data_fields properties from the response to upload the video in the next step.
Upload a video, so that it is ready to be processed. The video should be uploaded as multipart/form-data to the URL you obtained above. Use the form fields from the previous response and add these as form data parameters to the POST request.
POST
Params
Form Parameters
key
required
String
Obtained from the `Get Upload URL` endpoint
x-amz-algorithm
required
String
Obtained from the `Get Upload URL` endpoint
x-amz-credential
required
String
Obtained from the `Get Upload URL` endpoint
x-amz-date
required
String
Obtained from the `Get Upload URL` endpoint
policy
required
String
Obtained from the `Get Upload URL` endpoint
x-amz-signature
required
String
Obtained from the `Get Upload URL` endpoint
file
required
Object
The video file to upload.
Curl
Node.js
JS
Python
Ruby
Postman
|
Body: form-data
key:286049de0ac74ee78cb2e19e1b238bc6
x-amz-algorithm:AWS4-HMAC-SHA256
x-amz-credential:AKIAUSQJHCVO4WD2X4WK/20230510/eu-west-1/s3/aws4_request
x-amz-date:20230510T122340Z
policy:eyJleHBpcmF0aW9uIjogIjIwMjMtMDUtMTBUMTI6Mjg6NDBaIiwgImNvbmRpdGlvbnMiOiBbeyJrZXkiOiAiMjg2MDQ5ZGUwYWM3NGVlNzhjYjJlMTllMWIyMzhiYzYifSwgWyJjb250ZW50LWxlbmd0aC1yYW5nZSIsIDAsIDE1MDAwMDAwMF0sIHsiYnVja2V0IjogIm1haW4tZW5naW5lLWJ1Y2tldC1wcm9kIn0sIHsia2V5IjogIjI4NjA0OWRlMGFjNzRlZTc4Y2IyZTE5ZTFiMjM4YmM2In0sIHsieC1hbXotYWxnb3JpdGhtIjogIkFXUzQtSE1BQy1TSEEyNTYifSwgeyJ4LWFtei1jcmVkZW50aWFsIjogIkFLSUFVU1FKSENWTzRXRDJYNFdLLzIwMjMwNTEwL2V1LXdlc3QtMS9zMy9hd3M0X3JlcXVlc3QifSwgeyJ4LWFtei1kYXRlIjogIjIwMjMwNTEwVDEyMjM0MFoifV19
x-amz-signature:cc75ebcbdff0c8f46f86f4e6035096274baa4a6d4b6497a1acb1f036b84f8558
file: <link_to_your_video_file_object>
// values should match what you receive from the "get upload URL" endpoint.
RESPONSES
204
400
403
|
// video has been succesfully uploaded
The sequence of the form parameters is of importance for the AWS authentication flow. Please preserve the order as listed above. If you're using postman to test, below is how the form data should look like.
Use this endpoint to add the uploaded video, specified by its uuid, to the processing queue. Once done, our IntelliProve processing engine will start extracting the biomarkers.
Use the "/results/wait" endpoint to get the results.
POST
Params
Path Params
uuid
required
String
The uuid of the video to be processed
Query Parameters
timezone
required
String
Provide the timezone of the area where the video was recorded. County code, TZ identifiers and abbreviations are supported.
performer-ref
optional
String
Unique reference to the individual that is performing the health scan.
patient-ref
optional
String
Unique reference to the patient to which the health scan belongs.
Curl
Node.js
JS
Python
Ruby
|
curl --request POST 'https://engine.intelliprove.com/v1/videos/process/{uuid}?performer-ref=string&patient-ref=string'\
--header 'Accept: application/json'\
--header 'x-api-key: string'
RESPONSES
202
400
401
406
422
|
{"detail":"Please provide a valid time zone string." | "Video not found in upload storage."}
The settings you use to record the video in your platform are of great importance. This covers variables like codec, framerate, resolution and bitrate. For more information, refer to the page Technical requirements, section about video requirements.
A full list of timezones can be found here.
An example timezone would be: Europe/Brussels
Result endpoints
Use these endpoints to obtain results for a specific health check based on UUID.
More information about the returned biomarkers and insights can be found on the following page: Insights & biomarkers
Get the results of a single health check, by specifying the UUID of the health scan. The request long-polls the database for up to 20 seconds, returning the results as soon as they are available or returning a http 204 if no results were found after this time has expired.
GET
Params
Path Params
uuid
required
String
The uuid of the health scan for which to fetch the results
Curl
Node.js
JS
Python
Ruby
|
curl --request GET 'https://engine.intelliprove.com/v1/results/wait/{UUID}'\
--header 'Accept: application/json'\
--header 'x-api-key: string'
RESPONSES
200
202
401
422
|
{"errorCode":1,"errorType": 'VideoError'
}
List of possible Error Codes:
Error Code
Short description
Error Type
Explanation
1
Video Format Error
VideoError
The video is corrupt and cannot be used. A video is corrupt when the fps, duration or frames cannot be read from it. Typically, such a video can not be played back either. This is typically related to incorrect encoding or recording settings in your setup.
A video that was not (correctly) uploaded.
2
Video Too Short
VideoError
The video is not long enough. Please record for at least 20 seconds.
3
No Face Detected
VideoError
A face could not be found in (certain parts of) the video.
4
Not Sufficient Skin
VideoError
Insufficient skin is visible, e.g. due to the face being partially covered, making the measurement impossible.
5
Moved Out of Frame
VideoError
The subject's face moved (partially) out of frame during the recording.
10
RGB Quality Error
QualityError
Quality insufficient at the RGB level to calculated any parameters. This can be related to excessive movement (camera or subject) or flickering lights.
11
Signal Quality Error
QualityError
The quality of the PPG signal is insufficient. This can be related to low video quality.
99
Unhandled Exception
UnexpectedError
Something unexpected happen. We will look into this.
In some cases, the video quality or lighting conditions might be insufficient to calculate certain paramters 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
Use this endpoint to get your number of successfully performed health scans. It also returns the number of allowed health scans for your current contract.
GET
Params
Query Parameters
performer-ref
optional
String
Health scan count filtered on performer reference.
patient-ref
optional
String
Health scan count filtered on patient reference.
Curl
Node.js
JS
Python
Ruby
|
curl --request GET 'https://engine.intelliprove.com/v1/results/count?performer-ref=string'\
--header 'Accept: application/json'
RESPONSES
200
401
|
{"detail":"Missing or invalid authentication credentials."}
Patient endpoints
Use these endpoints to obtain or delete results for one or more patients.
Get the history of results for one or more patients based on patient and/or performer reference.
These endpoints provide routes to access and manage information about your account at intelliprove. These are for API Keys only and can contain sensitive data.
Receive information abour your quota and current usage.
GET
Params
Curl
Node.js
JS
Python
Ruby
|
curl --location --request GET 'https://engine.intelliprove.com/v1/account/quota'\
--header 'Accept: application/json'
RESPONSES
200
403
401
|
{"detail":"Missing or invalid authentication credentials."}