Rest API

Introduction
The IntelliProve API is organised around REST. Our API has predictable resource-oriented URLs, accepts JSON-encoded request bodies, returns JSON-encoded responses, and uses standard HTTP response codes, authentication, and verbs.
Text
https://engine.intelliprove.com
https://engine.intelliprove.com
﻿
Examples:
POST https://engine.intelliprove.com/v2/users
GET https://engine.intelliprove.com/v2/users
If you are new to this developer portal, we recommend first reading the product documentation﻿, which will get you acquainted with the main product concepts and functionalities. To integrate the plug-in into your platform and get started performing Face Scans﻿, follow our Initial integration﻿ documentation.
Authentication
The IntelliProve API supports API keys and JWT Action Tokens to authenticate HTTP requests.
All API requests must be made over HTTPS. Calls made over plain HTTP will fail. API requests without authentication will also fail. 
All the endpoints described below require an API key or action token in the header for authentication purposes. 
API Keys
API Keys cannot be created manually, but are distributed when you sign up for a plan with IntelliProve.
﻿Contact us or set up a call.
Your API keys carry many privileges and have no expiry date, so be sure to keep them secure! Do not share your secret API keys in publicly accessible areas such as GitHub, client-side code, and so forth.
After agreement, you'll receive at least two API keys. Development API keys, which can be used during development, are aliased with a "-DEV" suffix.
Alias
API Key (non-working examples)
COMPANYNAME-DEV
KUsWnp2vRGCfW8XPYJZeQdh-eT!n-Ms.UcyaETy3
COMPANY-NAME
fWeBpZ9CKaKb7pnk@vGtkQDjZFQ_U2g@GZu_Z74X
Use your API key in the HTTP request header:
x-api-key: <your-api-key>
User Action Tokens
Action tokens can be manually created using the IntelliProve API, and require a valid API key. Use the Create user action token﻿ endpoint to do this.
They are specifically designed to be used in client-side (frontend) code, as they have restricted access and automatically expire after a predefined timespan. However, they may also be used in backend code for certain usecases.
Pass your action token in the HTTP request header:
authorization: Token <your-action-token>
API keys vs User Action Tokens
Unlike API keys, User Action Tokens are linked to a User﻿ upon creation. API requests authenticated with these tokens are automatically linked to that User. An action token should always be created right before a User performs an action in your front-end, hence the name Action Token. This action token can be used while the user is performing the action (e.g. consult the results of a Face Scan). If a user leaves a page and does another action, a NEW action token should be created.
If data for a user needs to be retrieved at a later time, e.g. for building a dashboard or processing some data in the back-end, you have two options:
Get the data in your back-end using the API key, process the data and render it separately. Auth not locked to a user.
Create an action token to fetch the user's data directly from your front-end. The action token can then only be used to fetch data for that user.
In both scenarios for fetching data, you'll often need some unique user identifier if you want to serve the current user his/her own data. Because we understand that customers have their own unique user identifiers (uuid, email, etc.) we provide the option of setting an external_user_id to a custom value when creating a user﻿  so that you do not have to store our (IntelliProve's) UUID.
Summary
                             Authentication method
API key
Action token
Type of communication
Customer backend to IntelliProve backend only
Customer backend OR front-end to IntelliProve backend
Scope
Full access to all data
Access limited to a single user's data
Lifetime and creation
Created when you sign up for a plan. Does not expire.
Created by you using your API key. Expire after a few hours. Recommended to create and use within the scope of a user's action(s) on a page of your application.
When using an API key for authentication, you may need to specify the user separately in certain endpoints (using the user_id or external_user_id parameter), whereas the action token already includes this information.
﻿
Errors
In general, Status Codes in the 2xx range indicate success. Codes in the 4xx range indicate an error that failed given the information provided (e.g., a required parameter was omitted or the request format is invalid, etc.). Codes in the 5xx range indicate an error with IntelliProve’s servers.
Status Code
Description
200 - OK
Everything worked as expected
204 - No Content
The request is correct, but there is no content to be returned
400 - Bad Request
The request was unacceptable
401 - Not Authorized
No valid authentication token provided
403 - Forbidden
No permissions to perform the request
404 - Not Found
The request resource does not exist
422 - Unprocessable
One or more of the request parameters are invalid
500, 502, 503 - Server Errors
Something went wrong on our end
The 4xx and 5xx errors can be handled programmatically and include an error description that briefly explains the error reported.
Error Format
{
    "detail": "User not found!"
}
{
    "detail": "User not found!"
}
﻿
An exception is made for the 422 errors, which give detailed information on which request parameter failed the validation.
Validation Error Format
{
    "detail": [
        {
            "loc": [
                "body",
                "data"
            ],
            "msg": "field required",
            "type": "value_error.missing"
        }
    ]
}
{
    "detail": [
        {
            "loc": [
                "body",
                "data"
            ],
            "msg": "field required",
            "type": "value_error.missing"
        }
    ]
}
﻿
Users
The User Object
A User is a unique end-user accessing IntelliProve's services through your platform or app. Each User must be registered once, enabling IntelliProve to track their Face Scans and build a personalized User Health Profile. Every user is assigned a unique User ID.
When providing the external_user_id as a query or path parameter, make sure to URL encode the value. This ensures that the value is received as expected on our end. You can use the encodeURI function (ref.) for JavaScript to create a URL encoded string.
Property
Description
user_id
uuid 
Unique IntelliProve ID assigned to the user.
external_user_id
nullable string
Your own unique ID for the user. Stored in your own backend.
customer
read-only string
Name of the company to which the user belongs.
birth_date
nullable date object
Date of birth in YYYY-MM-dd format
sex
nullable string enum
Sex at birth
Values: "M", "F"
language
nullable string enum
Two-letter language code
Values: "en", "nl", "fr"
Once registered, you can reference Users by both their user_id or their external_user_id.
﻿
Create a new user with the provided user details.
POST
Request
Header Parameters
x-api-key
required
String
Customer API key
Content-Type
required
String
application/json
Body Parameters
external_user_id
optional
String
External user ID value
birth_date
optional
String
User birth date in YYYY-MM-dd notation
sex
optional
String
Sex at birth value (M or F)
language
optional
String
Two-letter language code for preferred user language (default: en)
Request Body
{
  "external_user_id": "your_user_id",
  "birth_date": "1964-01-12",
  "sex": "M",
  "language": "en"
}
{
  "external_user_id": "your_user_id",
  "birth_date": "1964-01-12",
  "sex": "M",
  "language": "en"
}
Responses
201
{
    "user_id": "df55e9ab-77b9-4b32-bd83-d76de23f6f3d",
    "customer": "<customer-name>",
    "external_user_id": "your_user_id",
    "birth_date": "1964-01-12",
    "sex": "M",
    "language": "en"
}
{
    "user_id": "df55e9ab-77b9-4b32-bd83-d76de23f6f3d",
    "customer": "<customer-name>",
    "external_user_id": "your_user_id",
    "birth_date": "1964-01-12",
    "sex": "M",
    "language": "en"
}
﻿
﻿
Get user details by user ID or external user ID.
GET
Request
Query Parameters
user_id
optional
String
User UUID
external_user_id
optional
String
External user id value
Header Parameters
x-api-key
required
String
Customer API key
Request Body

Responses
200
{
    "user_id": "df55e9ab-77b9-4b32-bd83-d76de23f6f3d",
    "customer": "<customer-name>",
    "birth_date": "1964-01-12",
    "sex": "M",
    "language": "en"
}
{
    "user_id": "df55e9ab-77b9-4b32-bd83-d76de23f6f3d",
    "customer": "<customer-name>",
    "birth_date": "1964-01-12",
    "sex": "M",
    "language": "en"
}
﻿
Note: Although both the user_id and external_user_id are marked as optional, you need to provide exactly one of them in order to identify the user.
﻿
Full replacement of user details for the specified user.
PUT
Request
Path Params
user_id
required
String
User UUID
Header Parameters
x-api-key
required
String
Customer API key
Body Parameters
external_user_id
optional
String
External user reference value
birth_date
optional
String
User birth date in YYYY-MM-dd notation
sex
optional
String
Sex at birth value (M or F)
language
optional
String
Two-letter language code for preferred user language (default: en)
Request Body
{
  "external_user_id": "your_user_id",
  "birth_date": "1964-01-15",
  "sex": "F",
  "language": "nl"
}
{
  "external_user_id": "your_user_id",
  "birth_date": "1964-01-15",
  "sex": "F",
  "language": "nl"
}
Responses
200
{
    "user_id": "df55e9ab-77b9-4b32-bd83-d76de23f6f3d",
    "customer": "<customer-name>",
    "external_user_id": "your_user_id",
    "birth_date": "1964-01-15",
    "sex": "F",
    "language": "nl"
}
{
    "user_id": "df55e9ab-77b9-4b32-bd83-d76de23f6f3d",
    "customer": "<customer-name>",
    "external_user_id": "your_user_id",
    "birth_date": "1964-01-15",
    "sex": "F",
    "language": "nl"
}
﻿
﻿
Create a new action token for a user based on the IntelliProve user ID or your own (external) user ID.
POST
Request
Header Parameters
x-api-key
required
String
Customer API key
Body Parameters
user_id
optional
String
User UUID
external_user_id
optional
String
External user reference value
Request Body

Responses
201
{
    "token": "<ACTION_TOKEN>"
}
{
    "token": "<ACTION_TOKEN>"
}
﻿
﻿
Delete all user data, including user profiles and face scan results, based on the user ID.
DELETE
Request
Query Parameters
user_id
required
String
User UUID
Header Parameters
Authorization
required
String
User action token obtained using the 'Create user action token' endpoint, with added "Token "-prefix
Request Body

Responses
204

﻿
User journeys
To request a Face Scan URL, the user performing the scan must be registered with IntelliProve. This only needs to be done once for each user and can be done with the Register New User﻿ API endpoint. To register the user, you must provide a unique reference for the user as a query parameter: external_user_id. The response of the call will contain the IntelliProve user_id, which is the anonymised version stored at IntelliProve to keep track of the user's health insights. You can use any of these below to specify the user when requesting the Face Scan URL.
Get the Face Scan URL for a specific user based on the user ID or external user reference.
GET
Request
Query Parameters
user_id
optional
String
User UUID
external_user_id
optional
String
External user ID value
language
optional
String
Two-letter language code for overriding user-level preferred language
Header Parameters
x-api-key
required
String
Customer API key
Request Body

Responses
200
"<FaceScan_IFRAME_URL>"
"<FaceScan_IFRAME_URL>"
﻿
Note: Although both the user_id and external_user_id are marked as optional, you need to provide exactly one of them in order to identify the user.
For more information about the user_id and external_user_id query parameters, refer to the User Object﻿ documentation above.
Face Scans
Get biomarkers for a specific face scan by face scan id
GET
Request
Path Params
face_scan_id
required
String
Face Scan UUID
Header Parameters
Authorization
required
String
User action token obtained using the 'Create user action token' endpoint, with added "Token "-prefix
JS

Responses
200
{
  "face_scan_id": "ea23e5cd-22c8-1e54-bd82-e89de12a7e1b"
  "heart_rate": 65,
  "respiratory_rate": 12,
  "heart_rate_variability": 123,
  "resonant_breathing": 45
}
{
  "face_scan_id": "ea23e5cd-22c8-1e54-bd82-e89de12a7e1b"
  "heart_rate": 65,
  "respiratory_rate": 12,
  "heart_rate_variability": 123,
  "resonant_breathing": 45
}
﻿
Make sure that the User Action Token you're providing in the Authorization field, corresponds to the user that performed the Face Scan.
User Health Profiles
Get Metrics of a user, per Health Profile. The user is specified through the action token.
GET
Request
Path Params
profile
required
String
Which profile to summarize: physical, mental or sleep_energy
Header Parameters
Authorization
required
String
User action token obtained using the 'Create user action token' endpoint, with added "Token "-prefix
Request Body

Responses
200
204
{
  "score": "<overall-score>",
  "metrics": {
    "resting_heart_rate": "63",
    "sleep_quality": "75",
    ...
  }
}
{
  "score": "<overall-score>",
  "metrics": {
    "resting_heart_rate": "63",
    "sleep_quality": "75",
    ...
  }
}
﻿
The path parameter profile refers to a Health Profile.
→ More info about the User Health Profile﻿ 
﻿
Get a personalised summary, including Feedback and Tip, for the health profile of a user. The user is specified through the action token.
GET
Request
Path Params
profile
required
String
Which profile to summarize: physical, mental or sleep_energy
Header Parameters
Authorization
required
String
User action token obtained using the 'Create user action token' endpoint, with added "Token "-prefix
Request Body

Responses
200
{
  "feedback": "<personalized-feedback>",
  "tip": "<personalized-tip>"
}
{
  "feedback": "<personalized-feedback>",
  "tip": "<personalized-tip>"
}
﻿
Widgets
Use these endpoint to obtain the necessary data to create a widget displaying a Biomarker, Metric or Graph.
Get biomarker widget JSON data for specific Face Scan ID.
POST
Request
Header Parameters
Accept
required
String
application/json
Authorization
required
String
User action token obtained using the 'Create user action token' endpoint, with added "Token "-prefix
Body Parameters
face_scan_id
required
String
Face Scan ID
parameter
required
String
Biomarker parameter of choice
Request Body
{
    "data": {
        "face_scan_id": "c2f728c6-2f74-4d8c-83b9-fb4245cff2f9ll",
        "parameter": "heart_rate"
    }
}
{
    "data": {
        "face_scan_id": "c2f728c6-2f74-4d8c-83b9-fb4245cff2f9ll",
        "parameter": "heart_rate"
    }
}
Responses
200
{
    "data": {
        "value": 61,
        "name": "Heart Rate",
        "unit": "bpm",
        "range": [
            36,
            216
        ],
        "percentage": 0.3388888888888889,
        "zone": 1,
        "optimum": "low",
        "gradientStops": [
            0.47,
            0.55
        ],
        "title": "biomarker"
    },
    "config": {
        "face_scan_id": "c2f728c6-2f74-4d8c-83b9-fb4245cff2f9",
        "parameter": "heart_rate"
    }
}
{
    "data": {
        "value": 61,
        "name": "Heart Rate",
        "unit": "bpm",
        "range": [
            36,
            216
        ],
        "percentage": 0.3388888888888889,
        "zone": 1,
        "optimum": "low",
        "gradientStops": [
            0.47,
            0.55
        ],
        "title": "biomarker"
    },
    "config": {
        "face_scan_id": "c2f728c6-2f74-4d8c-83b9-fb4245cff2f9",
        "parameter": "heart_rate"
    }
}
﻿
For the full list of possible values for parameter or more documentation on how to interpret the response body,  refer to the section Biomarker Widget﻿.
﻿
Get metric widget JSON data for a user.
POST
Request
Header Parameters
Accept
required
String
application/json
Authorization
required
String
User action token obtained using the 'Create user action token' endpoint, with added "Token "-prefix
Body Parameters
parameter
required
String
Metric parameter of choice
Request Body
{
    "data": {
        "parameter": "mental_health_risk"
    }
}
{
    "data": {
        "parameter": "mental_health_risk"
    }
}
Responses
200
{
    "data": {
        "title": "metric",
        "name": "Mental Health Risk",
        "value": 1,  // Nullable
        "value_str": "Low",  // Nullable
        "unit": "",  // Nullable
        "range": [  // Nullable
            1,
            3
        ],
        "percentage": 0.5,  // Nullable
        "zone": 1,  // Nullable
        "optimum": "low",  // Nullable
        "locked": false
    },
    "config": {
        "parameter": "mental_health_risk"
    }
}
{
    "data": {
        "title": "metric",
        "name": "Mental Health Risk",
        "value": 1,  // Nullable
        "value_str": "Low",  // Nullable
        "unit": "",  // Nullable
        "range": [  // Nullable
            1,
            3
        ],
        "percentage": 0.5,  // Nullable
        "zone": 1,  // Nullable
        "optimum": "low",  // Nullable
        "locked": false
    },
    "config": {
        "parameter": "mental_health_risk"
    }
}
﻿
For the full list of possible values for parameter or more documentation on how to interpret the response body,  refer to the section Metric Widget﻿.
Note that in the response above the locked field may be set to true, meaning that the biomarker has not yet been unlocked by the user within their user journey. In this case, the Nullable fields will be set to Null.
For more information refer to the Health Journey﻿ documentation.
﻿
Get graph widget JSON data for a user.
POST
Request
Header Parameters
Accept
required
String
application/json
Authorization
required
String
User action token obtained using the 'Create user action token' endpoint, with added "Token "-prefix
Body Parameters
parameter
required
String
Insight or biomarker parameter of choice
title
optional
String
Optionally override the graph title with a string value of choice
start
optional
String
Start date for the range of historical data to be retrieved
Format: YYYY-MM-DD
Default: TODAY - 8 days
stop
optional
String
Stop date for the range of historical data to be retrieved
Format: YYYY-MM-DD
Default: TODAY
Request Body
{
    "data": {
        "parameter": "heart_rate",
        "title": "Custom graph title",
        "start": "2024-12-21T00:00:00",
        "stop" "2024-12-31T23:59:59": 
    }
}
{
    "data": {
        "parameter": "heart_rate",
        "title": "Custom graph title",
        "start": "2024-12-21T00:00:00",
        "stop" "2024-12-31T23:59:59": 
    }
}
Responses
200
{
    "data": [
        {
            "value": 60,  // Nullable
            "hint": "",
            "label": "25/09"
        },
        ...,
    ],
    "config": {
        "title": "Custom graph title",
        "y_range": [
            null,
            null
        ]
    }
}
{
    "data": [
        {
            "value": 60,  // Nullable
            "hint": "",
            "label": "25/09"
        },
        ...,
    ],
    "config": {
        "title": "Custom graph title",
        "y_range": [
            null,
            null
        ]
    }
}
﻿
For a list of possible values for parameter, refer to the sections Biomarker Widget﻿ and Metric Widget﻿.
Regulatory
Request the IntelliProve medical device label as PNG image.
GET
Request
Request Body

Responses
200
// Returns 'image/png' content type image
// Returns 'image/png' content type image
﻿
Refer to our Instructions for use﻿ for more information related to our medical device's product description and intended use.
Alias	API Key (non-working examples)
COMPANYNAME-DEV	KUsWnp2vRGCfW8XPYJZeQdh-eT!n-Ms.UcyaETy3
COMPANY-NAME	fWeBpZ9CKaKb7pnk@vGtkQDjZFQ_U2g@GZu_Z74X
Authentication method	API key	Action token
Type of communication	Customer backend to IntelliProve backend only	Customer backend OR front-end to IntelliProve backend
Scope	Full access to all data	Access limited to a single user's data
Lifetime and creation	Created when you sign up for a plan. Does not expire.	Created by you using your API key. Expire after a few hours. Recommended to create and use within the scope of a user's action(s) on a page of your application.
Status Code	Description
200 - OK	Everything worked as expected
204 - No Content	The request is correct, but there is no content to be returned
400 - Bad Request	The request was unacceptable
401 - Not Authorized	No valid authentication token provided
403 - Forbidden	No permissions to perform the request
404 - Not Found	The request resource does not exist
422 - Unprocessable	One or more of the request parameters are invalid
500, 502, 503 - Server Errors	Something went wrong on our end
Property	Description
user_id uuid	Unique IntelliProve ID assigned to the user.
external_user_id nullable string	Your own unique ID for the user. Stored in your own backend.
customer read-only string	Name of the company to which the user belongs.
birth_date nullable date object	Date of birth in YYYY-MM-dd format
sex nullable string enum	Sex at birth Values: "M", "F"
language nullable string enum	Two-letter language code Values: "en", "nl", "fr"
Updated 03 Feb 2025
Widget Appearance
Customisation