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 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 solution﻿ 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 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)
CUSTOMER1-DEV
KUsWnp2vRGCfW8XPYJZeQdh-eT!n-Ms.UcyaETy3
CUSTOMER1
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.
They are specifically designed to be used in client-side 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>
User-specific Authentication
Unlike API keys, Action Tokens are linked to an IntelliProve user upon creation. HTTP requests authenticated with these tokens are automatically linked to that user.
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
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
Property
Description
uuid
uuid 
Unique (internal) reference to the user object
external_user_reference
nullable string
Unique external reference to the user object, maintained by the customer
customer
read-only string
Name of the customer 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"
Users can be referenced by both their uuid, often referred to as user_id, or their external_user_reference, sometimes also referred to as user_ref.
Create a new user with the provide user details.
POST
Request
Header Parameters
x-api-key
required
String
Customer API key
Content-Type
required
String
application/json
Body Parameters
external_user_reference
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_reference": "[email protected]",
  "birth_date": "1964-01-12",
  "sex": "M",
  "language": "en"
}
{
  "external_user_reference": "i.am@frank.com",
  "birth_date": "1964-01-12",
  "sex": "M",
  "language": "en"
}
Responses
201
{
    "uuid": "df55e9ab-77b9-4b32-bd83-d76de23f6f3d",
    "customer": "<customer-name>",
    "external_user_reference": "[email protected]",
    "birth_date": "1964-01-12",
    "sex": "M",
    "language": "en"
}
{
    "uuid": "df55e9ab-77b9-4b32-bd83-d76de23f6f3d",
    "customer": "<customer-name>",
    "external_user_reference": "i.am@frank.com",
    "birth_date": "1964-01-12",
    "sex": "M",
    "language": "en"
}
﻿
Get user details by user ID or external user reference.
GET
Request
Query Parameters
user_id
optional
String
User UUID
user_ref
optional
String
External user reference value
Header Parameters
x-api-key
required
String
Customer API key
Request Body

Responses
200
{
    "uuid": "df55e9ab-77b9-4b32-bd83-d76de23f6f3d",
    "customer": "<customer-name>",
    "birth_date": "1964-01-12",
    "sex": "M",
    "language": "en"
}
{
    "uuid": "df55e9ab-77b9-4b32-bd83-d76de23f6f3d",
    "customer": "<customer-name>",
    "birth_date": "1964-01-12",
    "sex": "M",
    "language": "en"
}
﻿
Full replacement of user details for the specified user.
PUT
Request
Path Params
user_id
required
String
User UUID
Query Parameters
external_user_reference
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)
Header Parameters
x-api-key
required
String
Customer API key
Request Body
{
  "external_user_reference": "[email protected]",
  "birth_date": "1964-01-15",
  "sex": "F",
  "language": "nl"
}
{
  "external_user_reference": "i.am@frank.com",
  "birth_date": "1964-01-15",
  "sex": "F",
  "language": "nl"
}
Responses
200
{
    "uuid": "df55e9ab-77b9-4b32-bd83-d76de23f6f3d",
    "customer": "<customer-name>",
    "external_user_reference": "[email protected]",
    "birth_date": "1964-01-15",
    "sex": "F",
    "language": "nl"
}
{
    "uuid": "df55e9ab-77b9-4b32-bd83-d76de23f6f3d",
    "customer": "<customer-name>",
    "external_user_reference": "i.am@frank.com",
    "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
user_ref
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
Get next scan of user journey for a specific user based on the user ID or external user reference.
GET
Request
Query Parameters
user_id
optional
String
User UUID
user_ref
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
"<MEASUREMENT_IFRAME_URL>"
"<MEASUREMENT_IFRAME_URL>"
﻿
﻿
Widgets
Get biomarker widget JSON data for specific measurement UUID.
POST
Request
Header Parameters
Accept
required
String
application/json
Authorization
required
String
Action token with added "Token "-prefix
Body Parameters
uuid
required
String
Measurement UUID
parameter
required
String
Biomarker parameter of choice
Request Body
{
    "data": {
        "uuid": "c2f728c6-2f74-4d8c-83b9-fb4245cff2f9",
        "parameter": "heart_rate"
    }
}
{
    "data": {
        "uuid": "c2f728c6-2f74-4d8c-83b9-fb4245cff2f9",
        "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": {
        "uuid": "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": {
        "uuid": "c2f728c6-2f74-4d8c-83b9-fb4245cff2f9",
        "parameter": "heart_rate"
    }
}
﻿
Get metric widget JSON data for the authenticated user.
POST
Request
Header Parameters
Accept
required
String
application/json
Authorization
required
String
Action token 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"
    }
}
﻿
Note in the response above that 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 the authenticated user.
POST
Request
Header Parameters
Accept
required
String
application/json
Authorization
required
String
Action token 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
        ]
    }
}
﻿
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)
CUSTOMER1-DEV	KUsWnp2vRGCfW8XPYJZeQdh-eT!n-Ms.UcyaETy3
CUSTOMER1	fWeBpZ9CKaKb7pnk@vGtkQDjZFQ_U2g@GZu_Z74X
Status Code	Description
200 - OK	Everything worked as expected
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
uuid uuid	Unique (internal) reference to the user object
external_user_reference nullable string	Unique external reference to the user object, maintained by the customer
customer read-only string	Name of the customer 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"
Customisation
Changelog