--- title: Results API slug: technical-docs-v1/results-api description: Learn how to integrate IntelliProve's API into your application and gain insights into mental and physical health. This comprehensive documentation covers everything from obtaining user details to managing patient data. Explore code examples, endpoints, a icon: 🌍 docTags: createdAt: 2022-12-02T16:13:25.000Z --- :::hint{type="danger"} Please note, these docs are for the v1 version of IntelliProve and have been deprecated. They are here for reference of existing customers still using the v1 product. If you are a new customer, refer to the [Technical documentation -v2 ](docId\:qghLDn2mLA8w9rpKEigWn). ::: # 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](docId\:FwRILXhaP81OoJWMWf3TR), 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](docId\:f86CeMBkuJ-Kwr60RtrEv) documentation. :::BlockQuote 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](docId\:FwRILXhaP81OoJWMWf3TR). ::: # 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. ::::ExpandableHeading ### 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: ` :::hint{type="info"} No API key and interested in our product? Contact us (info\@intelliprove.com) or [set up a call](https://calendly.com/joeri-tulkens/30min) ::: :::: :::ExpandableHeading ### 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 ` You can use our [Create action token](docId:-EZ-tag25qIm8ZuCoubyI) 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. :::hint{type="info"} The meaning of the 'results' and 'bucket' objects is further explained in the [Message events](docId\:NHmYw3IgyWBV_WbATHoLB). More information about the actual biomarkers we measure can be found on the following page: [Insights & biomarkers](docId:3PRUszMjT22MzXVKUFpWd) ::: *** 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](docId\:NHmYw3IgyWBV_WbATHoLB), 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. :::ApiMethodV2 ```json { "tab": "examples", "url": "https://engine.intelliprove.com/v1/results/wait/{uuid}", "name": "Wait for results", "method": "GET", "request": { "pathParameters": [ { "kind": "required", "name": "uuid", "type": "string", "children": [], "description": "The uuid of the health check for which to fetch the results" } ], "queryParameters": [], "headerParameters": [], "bodyDataParameters": [], "formDataParameters": [] }, "results": { "languages": [ { "id": "Xr-_rBdKtJ3tm9MpxEtUJ", "code": "{\n \"timestamp_epoch\": 1670921835,\n \"timestamp\": \"2022-12-13T08:57:15+00:00\",\n \"heart_rate\": 112,\n \"respiratory_rate\": 13,\n \"heart_rate_variability\": 161,\n \"ans_balance\": 1,\n \"resonant_breathing_score\": 30,\n \"morning_readiness\": 7,\n \"acute_mental_stress_score\": 3,\n \"mental_health_risk\": 1\n}", "language": "200", "customLabel": "" }, { "id": "6-fdZuGpWH5Tb4YJaYrK4", "code": "{\n \"detail\": \"The results for this video were not found. This could be because the video with the specified UUID was never requested for processing, or because it is still being processed.\"\n}", "language": "202", "customLabel": "" }, { "id": "kKvPZUz_cxWx-5_WyndkG", "code": "{\n \"detail\": \"Missing or invalid authentication credentials.\"\n}", "language": "401", "customLabel": "" }, { "id": "aXSdz6uEV-j_23GvQSx56", "language": "422", "code": "{\n \"errorCode\": 5,\n \"errorType\": 'VideoError'\n \"errorDescription\": \"The subject's face moved (partially) out of frame during the recording.\" \n}", "customLabel": "" } ], "selectedLanguageId": "Xr-_rBdKtJ3tm9MpxEtUJ" }, "examples": { "languages": [ { "id": "ZADglKQo9atLSvmttama5", "code": "curl --location 'https://engine.intelliprove.com/v1/results/wait/your-video-uuid' \\\n--header 'Accept: application/json' \\\n--header 'x-api-key: your-api-key'", "language": "curl", "customLabel": "" } ], "selectedLanguageId": "ZADglKQo9atLSvmttama5" }, "description": "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.", "currentNewParameter": { "label": "Path Parameter", "value": "pathParameters" }, "autoGeneratedAnchorSlug": "wait-for-results", "legacyHash": "F5-34Rj97Zr7AChFpZttX" } ``` ::: 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](docId:3ubJuaxicjGeICClkq13Z), 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). :::ExpandableHeading ### 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. | ::: :::hint{type="info"} 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. :::ApiMethodV2 ```json { "tab": "examples", "url": "https://engine.intelliprove.com/v1/buckets/all/{uuid}", "name": "Get all buckets", "method": "GET", "request": { "pathParameters": [ { "kind": "required", "name": "uuid", "type": "string", "children": [], "description": "The uuid of the health check for which to fetch the buckets" } ], "queryParameters": [], "headerParameters": [], "bodyDataParameters": [], "formDataParameters": [] }, "results": { "languages": [ { "id": "Xr-_rBdKtJ3tm9MpxEtUJ", "code": "{\n \"uuid\": \"4b7b6dc34ddd413e8ce14dbac8e640c4\",\n \"buckets\": [\n {\n \"name\": \"physical\",\n \"timestamp_epoch\": 1707081928,\n \"timestamp\": \"2024-02-04T22:25:28+01:00\",\n \"status\": \"bad\",\n \"biomarkers\": [\n {\n \"name\": \"heart_rate\",\n \"value\": 88.0,\n \"zone\": \"bad\",\n \"unit\": \"bpm\",\n \"range\": [\n 36.0,\n 216.0\n ],\n \"optimum\": \"low\"\n },\n {\n \"name\": \"respiratory_rate\",\n \"value\": 7.0,\n \"zone\": \"good\",\n \"unit\": \"brpm\",\n \"range\": [\n 4.0,\n 48.0\n ],\n \"optimum\": \"middle\"\n }\n ],\n \"history\": [\n {\n \"biomarkers\": {\n \"heart_rate\": 77.0,\n \"respiratory_rate\": 15.0\n },\n \"timestamp_epoch\": 1708030833,\n \"timestamp\": \"2024-02-15T22:00:33+01:00\"\n },\n {\n \"biomarkers\": {\n \"heart_rate\": 62.0,\n \"respiratory_rate\": 11.0\n },\n \"timestamp_epoch\": 1708029278,\n \"timestamp\": \"2024-02-15T21:34:38+01:00\"\n },\n }\n ]\n },\n {\n \"name\": \"mental\",\n \"timestamp_epoch\": 1707081928,\n \"timestamp\": \"2024-02-04T22:25:28+01:00\",\n \"status\": \"good\",\n \"biomarkers\": [...],\n \"history\": [...]\n },\n ...\n ]\n}", "language": "200", "customLabel": "" }, { "id": "SAQ9gIQAApyf4-1aThvT0", "language": "400", "code": "{\n \"detail\": \"Measurement with UUID not found!\"\n}", "customLabel": "" }, { "id": "kKvPZUz_cxWx-5_WyndkG", "code": "{\n \"detail\": \"Missing or invalid authentication credentials.\"\n}", "language": "401", "customLabel": "" }, { "id": "aa9ZxZ7YaikmSFSQTqSPl", "language": "422", "code": "{\n \"errorCode\": 5,\n \"errorType\": 'VideoError'\n \"errorDescription\": \"The subject's face moved (partially) out of frame during the recording.\" \n}", "customLabel": "" } ], "selectedLanguageId": "Xr-_rBdKtJ3tm9MpxEtUJ" }, "examples": { "languages": [ { "id": "ZADglKQo9atLSvmttama5", "code": "curl --location 'https://engine.intelliprove.com/v1/results/wait/your-video-uuid' \\\n--header 'Accept: application/json' \\\n--header 'x-api-key: your-api-key'", "language": "curl", "customLabel": "" } ], "selectedLanguageId": "ZADglKQo9atLSvmttama5" }, "description": "Get all the buckets corresponding to a health check. ", "currentNewParameter": { "label": "Path Parameter", "value": "pathParameters" }, "autoGeneratedAnchorSlug": "get-all-buckets", "legacyHash": "I_xzpa8HGEgcP-Vkkbtjn" } ``` ::: *** The below endpoint allows you to fetch the summary and tips corresponding to each bucket. :::ApiMethodV2 ```json { "tab": "examples", "url": "https://engine.intelliprove.com/v1/buckets/summary/{UUID}", "name": "Get bucket summaries", "method": "GET", "request": { "pathParameters": [ { "kind": "required", "name": "uuid", "type": "string", "children": [], "description": "The uuid of the health check for which to fetch the buckets" } ], "queryParameters": [ { "name": "include_tips", "kind": "optional", "type": "Boolean", "description": "Whether to include a tip for each bucket", "children": [] }, { "name": "language", "kind": "optional", "type": "string", "description": "The language in which to return the results", "children": [] } ], "headerParameters": [], "bodyDataParameters": [], "formDataParameters": [] }, "results": { "languages": [ { "id": "Xr-_rBdKtJ3tm9MpxEtUJ", "code": "{\n \"uuid\": \"5059844c0c3441e28bda2679995622b5\",\n \"summaries\": [\n {\n \"name\": \"physical\",\n \"summary\": \"Your heart rate is 80 beats per minute, which indicates good cardiovascular health. In a normal range for healthy adults without stress. We've detected a breathing frequency of 12 breaths per minute which is very normal.\",\n \"tip\": \"Based on your heart rate and respiratory rate, a healthy habit you could incorporate is practicing mindfulness meditation for 10 minutes each day to reduce stress and promote mental well-being.\"\n },\n {\n \"name\": \"mental\",\n \"summary\": \"Your HRV is in a very good range, indicating a non-stressful condition. Your Autonomic Nervous System is relatively balanced, suggesting good regulation between the sympathetic and parasympathetic systems. You have a low mental health risk.\",\n \"tip\": \"To further improve your mental health, consider engaging in activities like mindfulness meditation, deep breathing exercises, or regular physical exercise. These practices can help enhance relaxation and promote overall well-being.\"\n },\n {\n \"name\": \"energy_sleep\",\n \"summary\": \"Your ANS balance of 1 suggests a relatively balanced activity between your sympathetic nervous system (SNS) and parasympathetic nervous system (PNS). Good overall energy and sleep.\",\n \"tip\": \"You are doing a great job maintaining a balanced autonomic nervous system activity. Keep up the good work and continue prioritizing your energy and sleep for optimal well-being.\"\n },\n {\n \"name\": \"mindfulness\",\n \"summary\": \"Your autonomic nervous system balance is relatively balanced, which is a good sign. However, your resonant breathing score indicates that there is room for improvement in synchronizing your breathing and heart rate variability. Your respiratory rate and heart rate are within normal ranges but slightly elevated, suggesting a moderate level of stress or lower conditioning.\",\n \"tip\": \"To improve your resonant breathing score and further synchronize your breathing and heart rate variability, try practicing slower and deeper breaths at a pace of around 6 breaths per minute. This can help promote relaxation and enhance the balance of your autonomic nervous system.\"\n }\n ]\n}", "language": "200", "customLabel": "" }, { "id": "3bxnprVZ1Ne-z-eOejswH", "language": "400", "code": "{\n \"detail\": \"Measurement with UUID not found!\"\n}", "customLabel": "" }, { "id": "kKvPZUz_cxWx-5_WyndkG", "code": "{\n \"detail\": \"Missing or invalid authentication credentials.\"\n}", "language": "401", "customLabel": "" }, { "id": "782NODpQpPaCUAaA8QwFZ", "language": "404", "code": "{\n \"detail\": \"Resource not found.\" // we currently do not provide feedback/tips for this scenario\n}", "customLabel": "" }, { "id": "SAQ9gIQAApyf4-1aThvT0", "language": "406", "code": "{\n \"detail\": \"The requested langauge is currently unavailable. Available languages: fr, en, nl.\"\n}", "customLabel": "" }, { "id": "HCrpsksFwzyFsyQdCk7oE", "language": "422", "code": "{\n \"detail\": \"This measurement did not process successfully. We cannot summarize this measurement!\"\n}", "customLabel": "" } ], "selectedLanguageId": "782NODpQpPaCUAaA8QwFZ" }, "examples": { "languages": [ { "id": "ZADglKQo9atLSvmttama5", "code": "curl --location 'https://engine.intelliprove.com/v1/results/wait/your-video-uuid' \\\n--header 'Accept: application/json' \\\n--header 'x-api-key: your-api-key'", "language": "curl", "customLabel": "" } ], "selectedLanguageId": "ZADglKQo9atLSvmttama5" }, "description": "Get the summary and tip for each of the buckets of a health check. ", "currentNewParameter": { "label": "Query Parameter", "value": "queryParameters" }, "autoGeneratedAnchorSlug": "get-bucket-summaries", "legacyHash": "0Itzh25gdSIxo9zIcrJwh" } ``` ::: # Results by patient ID Use this endpoint to obtain results related to a patient (user) and/or performer. :::ApiMethodV2 ```json { "tab": "examples", "url": "https://engine.intelliprove.com/v1/patient/history", "name": "Get History", "method": "GET", "request": { "pathParameters": [], "queryParameters": [ { "kind": "optional", "name": "patient-ref", "type": "string", "children": [], "description": "Patient for which the health checks are retrieved." }, { "kind": "optional", "name": "performer-ref", "type": "string", "children": [], "description": "Additional filter on performer reference." }, { "kind": "required", "name": "start", "type": "String", "children": [], "description": "Date time string value in ISO 8601 format" }, { "kind": "required", "name": "page", "type": "Integer", "children": [], "description": "Page of pagination" }, { "kind": "optional", "name": "page_size", "type": "Integer", "children": [], "description": "Number of items to return per page of pagination" } ], "headerParameters": [], "bodyDataParameters": [], "formDataParameters": [] }, "results": { "languages": [ { "id": "Bg9pQCkWQxZbo5auenQtZ", "code": "{\n \"data\": [\n {\n \"timestamp_epoch\": 1678100000,\n \"timestamp\": \"2023-03-06T10:00:00+01:00\",\n \"heart_rate\": 60,\n \"respiratory_rate\": 13,\n \"heart_rate_variability\": 48,\n \"ans_balance\": 1,\n \"resonant_breathing_score\": 30,\n \"patient\": \"a84kgh404a\",\n \"performer\": \"pa7xb48209\",\n \"morning_readiness\": null,\n \"acute_mental_stress_score\": 4,\n \"mental_health_risk\": 4\n },\n {\n \"timestamp_epoch\": 1678200030,\n \"timestamp\": \"2023-04-06T10:00:00+01:00\",\n \"heart_rate\": 57,\n \"respiratory_rate\": 12,\n \"heart_rate_variability\": 48,\n \"ans_balance\": 1,\n \"resonant_breathing_score\": 40,\n \"patient\": \"a84kgh404a\",\n \"performer\": \"pa7xb48209\",\n \"morning_readiness\": 3,\n \"acute_mental_stress_score\": 4,\n \"mental_health_risk\": 4\n }\n ],\n \"pagination\": {\n \"page\": 0,\n \"page_size\": 10,\n \"sorted_by\": \"timestamp\",\n \"sorting_order\": \"asc\",\n \"sorting_options\": [\n \"timestamp\",\n \"performer\"\n ]\n }\n}", "language": "200", "customLabel": "" }, { "id": "y8vii-vSoxSUBBV9jx-Np", "code": "{\n \"detail\": \"Please provide a patient reference.\"\n}", "language": "400", "customLabel": "" }, { "id": "EbUZ3ITn1fO76Cv96I3dp", "language": "401", "code": "{\n \"detail\": \"Missing or invalid authentication credentials.\"\n}", "customLabel": "" } ], "selectedLanguageId": "Bg9pQCkWQxZbo5auenQtZ" }, "examples": { "languages": [ { "id": "Os4e3JEuPlsboxgcVxqdg", "code": "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' \\\n--header 'x-api-key: your-api-key'", "language": "curl", "customLabel": "" } ], "selectedLanguageId": "Os4e3JEuPlsboxgcVxqdg" }, "description": "Get the history of results for one or more patients based on patient and/or performer reference.", "currentNewParameter": { "label": "Query Parameter", "value": "queryParameters" }, "autoGeneratedAnchorSlug": "get-history", "legacyHash": "HdEbE_neFEooCJWILxE11" } ``` ::: # Update metadata If required, you can update the metadata for a measurement after completing processing. :::ApiMethodV2 ```json { "tab": "examples", "url": "https://engine.intelliprove.com/v1/results/update/{uuid}", "name": "Update result metadata", "method": "PUT", "request": { "pathParameters": [], "queryParameters": [], "headerParameters": [], "bodyDataParameters": [ { "name": "performer-ref", "kind": "optional", "type": "string", "description": "An optional reference for the performer of the measurement", "children": [] }, { "name": "patient-ref", "kind": "optional", "type": "string", "description": "An optional reference for the patient on whom the measurement was performed", "children": [] } ], "formDataParameters": [] }, "results": { "languages": [ { "id": "IsElKfXcaCcayJfW6Ed3J", "language": "204", "code": "", "customLabel": "" }, { "id": "matK83VTSyZMuKheE_jrx", "language": "400", "code": "{\n \"detail\": \"No results were found found for this UUID\"\n}", "customLabel": "" }, { "id": "EbUZ3ITn1fO76Cv96I3dp", "language": "401", "code": "{\n \"detail\": \"Missing or invalid authentication credentials.\"\n}", "customLabel": "" }, { "id": "EmwOFPUwCXpFEPHgGzYrM", "language": "403", "code": "{\n \"detail\": \"You are not allowed to overwrite the performer for this measurement\"\n}", "customLabel": "" } ], "selectedLanguageId": "IsElKfXcaCcayJfW6Ed3J" }, "examples": { "languages": [ { "id": "Hnj94k2Po3FiJKP8ghXVq", "language": "curl", "code": "curl --location --globoff --request PUT 'https://engine.intelliprove.com/v1/results/update/{uuid}' \\\n--header 'Accept: application/json' \\\n--header 'Content-Type: application/json' \\\n--data '{\"performer-ref\":\"string\",\"patient-ref\":\"string\"}'", "customLabel": "" } ], "selectedLanguageId": "Hnj94k2Po3FiJKP8ghXVq" }, "description": "Update the performer and/or patient refernences for a measurement.", "currentNewParameter": { "label": "Body Parameter", "value": "bodyDataParameters" }, "autoGeneratedAnchorSlug": "update-result-metadata", "legacyHash": "U7eh12dbFGdBBZB1LGe7p" } ``` :::