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 after agreement between IntelliProve and you, the customer.
﻿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. Test 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
Pass your API key in the HTTP request header:
x-api-key: <your-api-key>
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.
User-specific Authentication
Unlike API keys, Action Tokens are linked to an IntelliProve User upon creation. API requests authenticated with these tokens are automatically linked to that user.
They are specifically designed to be used in client-side (frontend) code, as they have restricted access and automatically expire after a predefined timespan.
Pass your action token in the HTTP request header:
authorization: Token <your-action-token>
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.
Property
Description
user_id
uuid 
Unique IntelliProve ID assigned to the user.
external_user_id
nullable string
Your own unique reference to 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 user ID or external user reference.
POST
Request
Query Parameters
user_id
optional
String
User UUID
external_user_id
optional
String
External user reference value
Header Parameters
x-api-key
required
String
Customer API key
Request Body

Responses
201
{
    "token": "<ACTION_TOKEN>"
}
{
    "token": "<ACTION_TOKEN>"
}
﻿
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 reference 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
}
﻿
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",
    ...
  }
}
﻿
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 a list of possible values for parameter, 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 a list of possible values for parameter, 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
start
required
String
Start time range in ISO format (local time) for data points to include
stop
optional
String
Stop time range in ISO format (local time) for data points to include
page_size
optional
String
Maximum number of data points to include (default: 10)
Request Body
{
    "data": {
        "parameter": "heart_rate",
        "start": "2024-05-01T00:00:00",
        "stop": "2025-05-01T00:00:00",
        "page_size": 10
    }
}
{
    "data": {
        "parameter": "heart_rate",
        "start": "2024-05-01T00:00:00",
        "stop": "2025-05-01T00:00:00",
        "page_size": 10
    }
}
Responses
200
{
    "data": [
        {
            "value": 60,  // Nullable
            "hint": "25 Sep - 10:50",
            "label": "25/09"
        },
        ...,
    ],
    "config": {
        "title": "Graph Title",
        "y_range": [
            null,
            null
        ]
    }
}
{
    "data": [
        {
            "value": 60,  // Nullable
            "hint": "25 Sep - 10:50",
            "label": "25/09"
        },
        ...,
    ],
    "config": {
        "title": "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
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 reference to 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 17 Dec 2024
Widget Appearance
Customisation