Rest API

introduction the intelliprove api is organised around rest http //en wikipedia org/wiki/representational state transfer our api has predictable resource oriented urls, accepts json encoded request bodies, returns json encoded http //www json org/ responses, and uses standard http response codes, authentication, and verbs https //engine intelliprove com examples post https //engine intelliprove com/v2/users get https //engine intelliprove com/v2/users if you're new to this developer portal, we recommend starting with the overview docid\ d z1x fglae 0r7hcnuth to get familiar with the main product concepts and functionalities to integrate the plug in into your platform and get started performing health check docid\ mw6gpbzekcj lzrqjll , follow our initial integration docid\ qghldn2mla8w9rpkeigwn guide authentication the intelliprove api supports api keys and jwt action tokens to authenticate http requests all api requests must be made over https http //en wikipedia org/wiki/http secure 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 docid\ qwgcrvhpzblwc 1uvkj5l 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) company name 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 rest api docid\ biupvixvhltbukklr2ati 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 rest api /#the user object 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 you likely already have a unique user identifier (uuid, email, etc ) in your application, we provide the option of using that when rest api docid\ biupvixvhltbukklr2ati , via the external user id parameter you can use this external user id in most api calls, so that you do not have to store the intelliprove internal user id (the user id ) summary authentication methods api key action token type of communication your backend to intelliprove backend only your 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!" } 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" } ] } users the user object a user is a unique end user accessing intelliprove's services through your platform or app each user must be created once, enabling intelliprove to track their face scans and build a personalized user health profile when creating a user intelliprove assigns a unique user id , also reffered to as the "intelliprove internal user id" you also choose your own external user id , also reffered to as "external user id" you can use this id in most api calls, so that you do not have to store the intelliprove internal user id when choosing the external user id , make sure it is an url encoded value (i e if using an email or other number, url encode it first) this ensures that the value is received as expected on our end for example, you can use the encodeuri function ( ref ) for javascript to create a url encoded string property description user id uuid unique, intelliprove internal user id, assigned to each enduser external user id nullable string the unique id you choose when creating an intelliprove user stored in your own backend and used when requesting user data referred to as "external user id" in the documentation customer read only string your company's name, which the end user is linked to 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", "da", "sv" once created, you can reference users by both their user id or their external user id { "tab" "examples", "url" "https //engine intelliprove com/v2/users", "name" "create new user", "method" "post", "request" { "pathparameters" \[], "queryparameters" \[], "headerparameters" \[ { "name" "x api key", "kind" "required", "type" "string", "description" "your api key", "value" "qvsz3xnpr48hzrhze4hoo5x7tebpwcrswejcpb05", "" "your api key" }, { "name" "content type", "kind" "required", "type" "string", "description" "application/json", "value" "application/json", "" "application/json" } ], "bodydataparameters" \[ { "name" "external user id", "kind" "optional", "type" "string", "description" "external user id, chosen when creating the user", "value" "brecht test", "" "external user id, chosen when creating the user" }, { "name" "birth date", "kind" "optional", "type" "string", "description" "user birth date in yyyy mm dd notation", "value" "1997 11 03", "" "1997 11 03" }, { "name" "sex", "kind" "optional", "type" "string", "description" "sex at birth value (m or f)", "value" "m", "" "m" }, { "name" "language", "kind" "optional", "type" "string", "description" "two letter language code for preferred user language (default en)", "children" \[] } ], "formdataparameters" \[] }, "results" { "languages" \[ { "id" "xr rbdktj3tm9mpxetuj", "code" "{\n \\"user id\\" \\"df55e9ab 77b9 4b32 bd83 d76de23f6f3d\\",\n \\"customer\\" \\"\<your company name>\\",\n \\"external user id\\" \\"your user id\\",\n \\"birth date\\" \\"1964 01 12\\",\n \\"sex\\" \\"m\\",\n \\"language\\" \\"en\\"\n}", "language" "201", "customlabel" "" }, { "id" "tbozok npo3vfdxlbbih9", "language" "401", "code" "{\n \\"detail\\" \\"missing or invalid authentication credentials \\"\n}", "customlabel" "" } ], "selectedlanguageid" "xr rbdktj3tm9mpxetuj" }, "examples" { "languages" \[ { "id" "tx21iy5fxprfpr243fmyk", "language" "json", "code" "", "customlabel" "request body" } ], "selectedlanguageid" "tx21iy5fxprfpr243fmyk" }, "description" "create a new user with the provided user details ", "currentnewparameter" { "label" "body parameter", "value" "bodydataparameters" }, "hastryitout" true } the external user id parameter is your own unique id for the user the language parameter can be used to set the user's preferred language if it is, this language will be used as default language for that user, e g when displaying widgets or for a plug in url docid\ wcs2y1mg2pqnl4r4mgg z component, without having to explictly provide it there anymore { "name" "get user details", "method" "get", "url" "https //engine intelliprove com/v2/users", "description" "get user details by user id or external user id ", "tab" "examples", "examples" { "languages" \[ { "id" "bj8ks 8 oqu8g1kvjv0ik", "language" "json", "code" "", "customlabel" "request body" } ], "selectedlanguageid" "bj8ks 8 oqu8g1kvjv0ik" }, "results" { "languages" \[ { "id" "mexa4 txpzuv r bx741v", "language" "200", "customlabel" "", "code" "{\n \\"user id\\" \\"df55e9ab 77b9 4b32 bd83 d76de23f6f3d\\",\n \\"customer\\" \\"\<customer name>\\",\n \\"birth date\\" \\"1964 01 12\\",\n \\"sex\\" \\"m\\",\n \\"language\\" \\"en\\"\n}" }, { "id" " peprbnt2vyuklv8sr4hs", "language" "401", "code" "{\n \\"detail\\" \\"missing or invalid authentication credentials \\"\n}", "customlabel" "" } ], "selectedlanguageid" "mexa4 txpzuv r bx741v" }, "request" { "pathparameters" \[], "queryparameters" \[ { "name" "user id", "kind" "optional", "type" "string", "description" "intelliprove internal user id", "" "intelliprove internal user id" }, { "name" "external user id", "kind" "optional", "type" "string", "description" "external user id, chosen when creating the user", "" "external user id, chosen when creating the user" } ], "headerparameters" \[ { "name" "x api key", "kind" "required", "type" "string", "description" "your api key", "" "your api key" } ], "bodydataparameters" \[], "formdataparameters" \[] }, "currentnewparameter" { "label" "header parameter", "value" "headerparameters" }, "hastryitout" true } 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 { "name" "update existing user", "method" "put", "url" "https //engine intelliprove com/v2/users/\ user id", "description" "update a user's information all fields that are not provided will be left unchanged ", "tab" "examples", "examples" { "languages" \[ { "id" "bj8ks 8 oqu8g1kvjv0ik", "language" "json", "code" "", "customlabel" "request body" } ], "selectedlanguageid" "bj8ks 8 oqu8g1kvjv0ik" }, "results" { "languages" \[ { "id" "mexa4 txpzuv r bx741v", "language" "200", "customlabel" "", "code" "{\n \\"user id\\" \\"df55e9ab 77b9 4b32 bd83 d76de23f6f3d\\",\n \\"customer\\" \\"\<customer name>\\",\n \\"birth date\\" \\"1964 01 15\\",\n \\"sex\\" \\"f\\",\n \\"language\\" \\"nl\\"\n}" }, { "id" "2ynlhmc4b7yo8qe3utw3t", "language" "401", "code" "{\n \\"detail\\" \\"missing or invalid authentication credentials \\"\n}", "customlabel" "" } ], "selectedlanguageid" "mexa4 txpzuv r bx741v" }, "request" { "pathparameters" \[ { "name" "user id", "kind" "required", "type" "string", "description" "intelliprove internal user id", "" "intelliprove internal user id" } ], "queryparameters" \[], "headerparameters" \[ { "name" "x api key", "kind" "required", "type" "string", "description" "your api key", "" "your api key" } ], "bodydataparameters" \[ { "name" "external user id", "kind" "optional", "type" "string", "description" "external user id, chosen when creating the user", "" "external user id, chosen when creating the user" }, { "name" "birth date", "kind" "optional", "type" "string", "description" "user birth date in yyyy mm dd notation", "children" \[] }, { "name" "sex", "kind" "optional", "type" "string", "description" "sex at birth value (m or f)", "children" \[] }, { "name" "language", "kind" "optional", "type" "string", "description" "two letter language code for preferred user language (default en)", "children" \[] } ], "formdataparameters" \[] }, "currentnewparameter" { "label" "body parameter", "value" "bodydataparameters" }, "hastryitout" true } you can obtain the intelliprove user id via the the 'get user details' api endpoint, providing your own unique id for the user via the external user id parameter { "tab" "examples", "url" "https //engine intelliprove com/v2/users/authenticate", "name" "create user action token", "method" "post", "request" { "pathparameters" \[], "queryparameters" \[], "headerparameters" \[ { "name" "x api key", "kind" "required", "type" "string", "description" "your api key", "" "your api key" } ], "bodydataparameters" \[ { "name" "user id", "kind" "optional", "type" "string", "description" "intelliprove internal user id", "" "intelliprove internal user id" }, { "name" "external user id", "kind" "optional", "type" "string", "description" "external user id, chosen when creating the user", "" "external user id, chosen when creating the user" } ], "formdataparameters" \[] }, "results" { "languages" \[ { "id" "kctn4gzlot sdn t cyop", "code" "{\n \\"token\\" \\"\<action token>\\"\n}", "language" "201", "customlabel" "" }, { "id" "a5j1ma31hq8yya mchn3o", "language" "401", "code" "{\n \\"detail\\" \\"missing or invalid authentication credentials \\"\n}", "customlabel" "" } ], "selectedlanguageid" "kctn4gzlot sdn t cyop" }, "examples" { "languages" \[ { "id" "s0mcduwkinbnrg9pa thb", "code" "", "language" "json", "customlabel" "request body" } ], "selectedlanguageid" "s0mcduwkinbnrg9pa thb" }, "description" "create a new action token for a user based on the intelliprove user id or your own (external) user id ", "currentnewparameter" { "label" "body parameter", "value" "bodydataparameters" }, "hastryitout" true } 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 the external user id is what you chose when creating the user (see 'create new user' endpoint) { "tab" "examples", "url" "https //engine intelliprove com/v2/users/", "name" "delete user", "method" "delete", "request" { "pathparameters" \[], "queryparameters" \[ { "name" "user id", "kind" "required", "type" "string", "description" "intelliprove internal user id", "" "intelliprove internal user id" } ], "headerparameters" \[ { "name" "x api key", "kind" "required", "type" "string", "description" "your api key", "" "your api key" } ], "bodydataparameters" \[], "formdataparameters" \[] }, "results" { "languages" \[ { "id" "kctn4gzlot sdn t cyop", "code" "", "language" "204", "customlabel" "" }, { "id" "3hfdvo9hjtkesgfjmuccr", "language" "401", "code" "{\n \\"detail\\" \\"missing or invalid authentication credentials \\"\n}", "customlabel" "" } ], "selectedlanguageid" "kctn4gzlot sdn t cyop" }, "examples" { "languages" \[ { "id" "s0mcduwkinbnrg9pa thb", "code" "", "language" "json", "customlabel" "request body" } ], "selectedlanguageid" "s0mcduwkinbnrg9pa thb" }, "description" "delete all user data, including user profiles and face scan results, based on the user id ", "currentnewparameter" { "label" "query parameter", "value" "queryparameters" }, "hastryitout" true } user journeys to request a face scan url, the user performing the scan must be created with intelliprove this only needs to be done once for each user and can be done with the rest api docid\ biupvixvhltbukklr2ati api endpoint to create 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 { "name" "get face scan url", "method" "get", "url" "https //engine intelliprove com/v2/userjourneys/scan", "description" "get the face scan url for a specific user based on the user id or external user reference ", "tab" "examples", "examples" { "languages" \[ { "id" "se4aed7spl3rfavynybk9", "language" "json", "code" "", "customlabel" "request body" } ], "selectedlanguageid" "se4aed7spl3rfavynybk9" }, "results" { "languages" \[ { "id" "wzseovy zhyimuelnr d", "language" "200", "customlabel" "", "code" "\\"\<facescan plug in url>\\"" }, { "id" "shm5uzeclvrg1hjjdzzbk", "language" "401", "code" "{\n \\"detail\\" \\"missing or invalid authentication credentials \\"\n}", "customlabel" "" } ], "selectedlanguageid" "wzseovy zhyimuelnr d" }, "request" { "pathparameters" \[], "queryparameters" \[ { "name" "user id", "kind" "optional", "type" "string", "description" "intelliprove internal user id", "" "intelliprove internal user id" }, { "name" "external user id", "kind" "optional", "type" "string", "description" "external user id, chosen when creating the user", "" "external user id, chosen when creating the user" }, { "name" "language", "kind" "optional", "type" "string", "description" "two letter language code for overriding user level preferred language", "children" \[] }, { "name" "expire at", "kind" "optional", "type" "string", "description" "expiry datetime timestamp in iso format (e g 2025 04 01t00 00 00)", "" "expiry datetime timestamp in iso format (e g 2025 04 01t00 00 00)" } ], "headerparameters" \[ { "name" "x api key", "kind" "required", "type" "string", "description" "your api key", "" "your api key" } ], "bodydataparameters" \[], "formdataparameters" \[] }, "currentnewparameter" { "label" "query parameter", "value" "queryparameters" }, "hastryitout" true } note the url provided in the response may change over time this applies not only to the action token , which is unique for each request, but also to the subdomain, which may update with new versions of the plug in to prevent issues, avoid hardcoding any part of the url always use the full response url as provided additionally, ensure that your html security headers (e g , content security policy headers) allow all intelliprove com subdomains this is essential for the proper functioning of the intelliprove plug in and future updates 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 rest api /#the user object documentation above please note that the language , when specified here, overrides the default language set for the user, specified when rest api docid\ biupvixvhltbukklr2ati face scans { "name" "get face scan biomarkers", "method" "get", "url" "https //engine intelliprove com/v2/face scans/\ face scan id", "description" "get biomarkers for a specific face scan, using the face scan id ", "tab" "examples", "examples" { "languages" \[ { "id" "zxqm3vyigfrnc3vs3312k", "language" "json", "code" "", "customlabel" "request body" } ], "selectedlanguageid" "zxqm3vyigfrnc3vs3312k" }, "results" { "languages" \[ { "id" "9bmcznqvm1yn2yyvkhgyu", "language" "200", "customlabel" "", "code" "{\n \\"face scan id\\" \\"ea23e5cd 22c8 1e54 bd82 e89de12a7e1b\\"\n \\"heart rate\\" 65,\n \\"respiratory rate\\" 12,\n \\"heart rate variability\\" 123,\n \\"resonant breathing score\\" 18,\n \\"systolic blood pressure\\" 128,\n \\"diastolic blood pressure\\" 77,\n \\"timestamp epoch\\" 1742919213,\n \\"timestamp\\" \\"2025 03 25t17 13 33 147258+01 00\\"\n}" } ], "selectedlanguageid" "9bmcznqvm1yn2yyvkhgyu" }, "request" { "pathparameters" \[ { "name" "face scan id", "kind" "required", "type" "string", "description" "face scan uuid", "children" \[] } ], "queryparameters" \[], "headerparameters" \[ { "name" "authorization", "kind" "required", "type" "string", "description" "user action token obtained using the 'create user action token' endpoint, with added \\"token \\" prefix", "children" \[] } ], "bodydataparameters" \[], "formdataparameters" \[] }, "currentnewparameter" { "label" "header parameter", "value" "headerparameters" }, "hastryitout" true } make sure that the user action token you're providing in the authorization field, corresponds to the user that performed the face scan, and prepend the "token " prefix { "name" "get mutliple face scan biomarkers", "method" "get", "url" "https //engine intelliprove com/v2/face scans/", "description" "get the biomarkers from multiple face scans of a user by specifying start date, end date and count the user is specified through the action token ", "tab" "examples", "examples" { "languages" \[ { "id" "zxqm3vyigfrnc3vs3312k", "language" "json", "code" "", "customlabel" "request body" } ], "selectedlanguageid" "zxqm3vyigfrnc3vs3312k" }, "results" { "languages" \[ { "id" "9bmcznqvm1yn2yyvkhgyu", "language" "200", "customlabel" "", "code" "\[\n {\n \\"face scan id\\" \\"ea23e5cd 22c8 1e54 bd82 e89de12a7e1b\\"\n \\"heart rate\\" 65,\n \\"respiratory rate\\" 12,\n \\"heart rate variability\\" 123,\n \\"resonant breathing score\\" 18,\n \\"systolic blood pressure\\" 128,\n \\"diastolic blood pressure\\" 77,\n \\"timestamp epoch\\" 1742919213,\n \\"timestamp\\" \\"2025 03 25t17 13 33 147258+01 00\\"\n },\n \n]" } ], "selectedlanguageid" "9bmcznqvm1yn2yyvkhgyu" }, "request" { "pathparameters" \[], "queryparameters" \[ { "name" "start", "kind" "optional", "type" "string", "description" "start date, all returned face scans will be after this date time iso format", "" "start date, all returned face scans will be after this date time iso format" }, { "name" "end", "kind" "optional", "type" "string", "description" "end date, all returned face scans will be before this date time iso format", "" "end date, all returned face scans will be before this date time iso format" }, { "name" "order", "kind" "optional", "type" "string", "description" "order of the returned face scans 'asc' or 'desc' default 'asc'", "" "order of the returned face scans 'asc' or 'desc' default 'asc'" }, { "name" "count", "kind" "optional", "type" "string", "description" "max number of face scans to return defaults to 10 ", "" "max number of face scans to return defaults to 10 " } ], "headerparameters" \[ { "name" "authorization", "kind" "required", "type" "string", "description" "user action token obtained using the 'create user action token' endpoint, with added \\"token \\" prefix", "children" \[] } ], "bodydataparameters" \[], "formdataparameters" \[] }, "currentnewparameter" { "label" "query parameter", "value" "queryparameters" }, "hastryitout" true } { "name" "get latest face scan biomarkers", "method" "get", "url" "https //engine intelliprove com/v2/face scans/latest", "description" "get the biomarkers from the latest face scan(s) of a user the user is specified through the action token the count can be specified to request more than one face scan ", "tab" "examples", "examples" { "languages" \[ { "id" "zxqm3vyigfrnc3vs3312k", "language" "json", "code" "", "customlabel" "request body" } ], "selectedlanguageid" "zxqm3vyigfrnc3vs3312k" }, "results" { "languages" \[ { "id" "9bmcznqvm1yn2yyvkhgyu", "language" "200", "customlabel" "", "code" "\[\n {\n \\"face scan id\\" \\"ea23e5cd 22c8 1e54 bd82 e89de12a7e1b\\"\n \\"heart rate\\" 65,\n \\"respiratory rate\\" 12,\n \\"heart rate variability\\" 123,\n \\"resonant breathing score\\" 18,\n \\"systolic blood pressure\\" 128,\n \\"diastolic blood pressure\\" 77,\n \\"timestamp epoch\\" 1742919213,\n \\"timestamp\\" \\"2025 03 25t17 13 33 147258+01 00\\"\n },\n \n]" } ], "selectedlanguageid" "9bmcznqvm1yn2yyvkhgyu" }, "request" { "pathparameters" \[], "queryparameters" \[ { "name" "count", "kind" "optional", "type" "string", "description" "last x number of measurements \ndefault = 1", "" "last x number of measurements \ndefault = 1" } ], "headerparameters" \[ { "name" "authorization", "kind" "required", "type" "string", "description" "user action token obtained using the 'create user action token' endpoint, with added \\"token \\" prefix", "children" \[] } ], "bodydataparameters" \[], "formdataparameters" \[] }, "currentnewparameter" { "label" "query parameter", "value" "queryparameters" }, "hastryitout" true } user health profiles { "name" "get health metrics", "method" "get", "url" "https //engine intelliprove com/v2/userprofiles/\ profile", "description" "get metrics of a user, per health profile the user is specified through the action token ", "tab" "examples", "examples" { "languages" \[ { "id" "se4aed7spl3rfavynybk9", "language" "json", "code" "", "customlabel" "request body" } ], "selectedlanguageid" "se4aed7spl3rfavynybk9" }, "results" { "languages" \[ { "id" "wzseovy zhyimuelnr d", "language" "200", "customlabel" "", "code" "{\n \\"score\\" 0 84,\n \\"last updated epoch\\" 1741316400,\n \\"last updated\\" \\"2025 03 07t03 00 00 527237+01 00\\",\n \\"metrics\\" {\n \\"resting heart rate\\" 65,\n \\"resting respiratory rate\\" 14,\n \\"general fitness level\\" 92,\n \n }\n}" }, { "id" "gzixu0bl 853tkvon2ybg", "language" "204", "code" "// user has no data (yet) for this profile", "customlabel" "" } ], "selectedlanguageid" "wzseovy zhyimuelnr d" }, "request" { "pathparameters" \[ { "name" "profile", "kind" "required", "type" "string", "description" "which profile to summarize physical, mental or energy sleep", "" "which profile to summarize physical, mental or energy sleep" } ], "queryparameters" \[], "headerparameters" \[ { "name" "authorization", "kind" "required", "type" "string", "description" "user action token obtained using the 'create user action token' endpoint, with added \\"token \\" prefix", "children" \[] } ], "bodydataparameters" \[], "formdataparameters" \[] }, "currentnewparameter" { "label" "path parameter", "value" "pathparameters" }, "response" \[ { "name" "score", "kind" "optional", "type" "number", "description" "overall user profile score (0 1)" }, { "name" "last updated epoch", "kind" "optional", "type" "integer", "description" "epoch timestamp of last time the user profile was updated", "children" \[] }, { "name" "last updated", "kind" "optional", "type" "integer", "description" "iso formatted datetime string of last time the user profile was updated", "children" \[] }, { "name" "metrics", "kind" "optional", "type" "object", "description" "dynamic object containing the user profile metrics", "children" \[] } ], "hastryitout" true } the path parameter profile refers to a health profile user health profile docid\ z2qnaeg2ru 3t3hbhw8rh { "name" "summarize profile", "method" "get", "url" "https //engine intelliprove com/v2/userprofiles/summary/\ profile", "description" "get a personalised summary, including feedback and tip, for the health profile of a user the user is specified through the action token ", "tab" "examples", "examples" { "languages" \[ { "id" "se4aed7spl3rfavynybk9", "language" "json", "code" "", "customlabel" "request body" } ], "selectedlanguageid" "se4aed7spl3rfavynybk9" }, "results" { "languages" \[ { "id" "wzseovy zhyimuelnr d", "language" "200", "customlabel" "", "code" "{\n \\"feedback\\" \\"\<personalized feedback>\\",\n \\"tip\\" \\"\<personalized tip>\\"\n}" } ], "selectedlanguageid" "wzseovy zhyimuelnr d" }, "request" { "pathparameters" \[ { "name" "profile", "kind" "required", "type" "string", "description" "which profile to summarize physical, mental or energy sleep", "" "which profile to summarize physical, mental or energy sleep" } ], "queryparameters" \[ { "name" "language", "kind" "required", "type" "string", "description" "provide the language for the summary ", "" "provide the language for the summary " } ], "headerparameters" \[ { "name" "authorization", "kind" "required", "type" "string", "description" "user action token obtained using the 'create user action token' endpoint, with added \\"token \\" prefix", "children" \[] } ], "bodydataparameters" \[], "formdataparameters" \[] }, "currentnewparameter" { "label" "query parameter", "value" "queryparameters" }, "hastryitout" true } { "name" "get wellbeing scores", "method" "get", "url" "https //engine intelliprove com/v2/userprofiles/wellbeing", "description" "get all the wellbeing scores for a user a score is a value between 0 100, representing a percentage, per profile the user is specified through the action token ", "tab" "examples", "examples" { "languages" \[ { "id" "se4aed7spl3rfavynybk9", "language" "json", "code" "", "customlabel" "request body" } ], "selectedlanguageid" "se4aed7spl3rfavynybk9" }, "results" { "languages" \[ { "id" "wzseovy zhyimuelnr d", "language" "200", "customlabel" "", "code" "{\n \\"mental\\" \<mental score>,\n \\"physical\\" \<physical score>,\n \\"energy sleep\\" \<energy sleep score>\n}" } ], "selectedlanguageid" "wzseovy zhyimuelnr d" }, "request" { "pathparameters" \[], "queryparameters" \[], "headerparameters" \[ { "name" "authorization", "kind" "required", "type" "string", "description" "user action token obtained using the 'create user action token' endpoint, with added \\"token \\" prefix", "children" \[] } ], "bodydataparameters" \[], "formdataparameters" \[] }, "currentnewparameter" { "label" "path parameter", "value" "pathparameters" }, "hastryitout" true } important note on the scores a score around 50% means average for that user, taking into account their age and sex a score below 50% is considered below average, i e suboptimal a secore above 50% is considered above average, i e optimal take this into account when visualizing the scores in your app user details the following endpoints are related to user details such as age, weight or sex these are used build an accurate baseline profile for each user and are essential for the calculation of metrics questions during the face scan allow the user to directly provide this information however, if you already have this information, you can provide it to us via the api the question will then not be asked in the face scan flow anymore refer to the plug in solution docid\ djhyobp 3w 87jkk0o1ho documentation for more information { "name" "get all question lookup keys", "method" "get", "url" "https //engine intelliprove com/v2/questions/all", "description" "get a list of all supported question lookup keys ", "tab" "examples", "examples" { "languages" \[ { "id" "ly k8enkjy3xdfr9fl8n0", "language" "json", "code" "", "customlabel" "request body" } ], "selectedlanguageid" "ly k8enkjy3xdfr9fl8n0" }, "results" { "languages" \[ { "id" "exkhp1cp6mnfc8lacxnpm", "language" "200", "customlabel" "", "code" "\[\n \\"height\\",\n \\"weight\\",\n \\"balance coordination\\",\n \\"hours sport week\\",\n \\"daily activities\\",\n \\"nightly wake ups\\",\n \\"feeling stressed last month\\",\n \\"struggling irritations last month\\",\n \\"things your way last month\\",\n \\"average sleep hours\\",\n \n]" } ], "selectedlanguageid" "exkhp1cp6mnfc8lacxnpm" }, "request" { "pathparameters" \[], "queryparameters" \[], "headerparameters" \[ { "name" "x api key", "kind" "required", "type" "string", "description" "your api key", "" "your api key" } ], "bodydataparameters" \[], "formdataparameters" \[] }, "currentnewparameter" { "label" "header parameter", "value" "headerparameters" }, "hastryitout" true } this endpoint returns all availble lookup keys and is not customer or user specific { "name" "save question answer", "method" "post", "url" "https //engine intelliprove com/v2/questions/answer", "description" "save an answer to a question for one of your users", "tab" "examples", "examples" { "languages" \[ { "id" "ly k8enkjy3xdfr9fl8n0", "language" "json", "code" "{\n \\"value\\" 24,\n \\"lookup key\\" \\"age\\",\n \\"timezone\\" \\"europe/brussels\\"\n}", "customlabel" "request body" } ], "selectedlanguageid" "ly k8enkjy3xdfr9fl8n0" }, "results" { "languages" \[ { "id" "exkhp1cp6mnfc8lacxnpm", "language" "201", "customlabel" "", "code" "{\n \\"lookup key\\" \\"age\\",\n \\"value\\" 24,\n \\"user id\\" \\"df55e9ab 77b9 4b32 bd83 d76de23f6f3d\\"\n}" } ], "selectedlanguageid" "exkhp1cp6mnfc8lacxnpm" }, "request" { "pathparameters" \[], "queryparameters" \[ { "name" "user id", "kind" "optional", "type" "string", "description" "the uuid of the user you want to answer a question for", "" "optional" } ], "headerparameters" \[ { "name" "x api key", "kind" "required", "type" "string", "description" "your api key", "" "your api key" } ], "bodydataparameters" \[], "formdataparameters" \[] }, "currentnewparameter" { "label" "query parameter", "value" "queryparameters" }, "hastryitout" true } for more information on the different lookup keys and possible values , refer to the intelliprove admin tool { "name" "save multiple question answers", "method" "post", "url" "https //engine intelliprove com/v2/questions/answer/many", "description" "save an answer to a question for one of your users", "tab" "examples", "examples" { "languages" \[ { "id" "ly k8enkjy3xdfr9fl8n0", "language" "json", "code" "\[\n {\n \\"value\\" 24,\n \\"lookup key\\" \\"age\\",\n \\"timezone\\" \\"europe/brussels\\"\n },\n \n]", "customlabel" "request body" } ], "selectedlanguageid" "ly k8enkjy3xdfr9fl8n0" }, "results" { "languages" \[ { "id" "exkhp1cp6mnfc8lacxnpm", "language" "201", "customlabel" "", "code" "\[\n {\n \\"lookup key\\" \\"age\\",\n \\"value\\" 24,\n \\"user id\\" \\"df55e9ab 77b9 4b32 bd83 d76de23f6f3d\\"\n },\n \n]" } ], "selectedlanguageid" "exkhp1cp6mnfc8lacxnpm" }, "request" { "pathparameters" \[], "queryparameters" \[ { "name" "user id", "kind" "required", "type" "string", "description" "the uuid of the user you want to answer a question for", "" "required" } ], "headerparameters" \[ { "name" "x api key", "kind" "required", "type" "string", "description" "your api key", "" "your api key" } ], "bodydataparameters" \[], "formdataparameters" \[] }, "currentnewparameter" { "label" "query parameter", "value" "queryparameters" }, "hastryitout" true } for more information on the different lookup keys and possible values , refer to the intelliprove admin tool widgets use these endpoints to obtain the necessary data to create a widget displaying a biomarker, metric or graph deprecated this endpoint is deprecated and will be removed in a future version of intelliprove we advise to use the endpoints rest api docid\ biupvixvhltbukklr2ati and rest api docid\ biupvixvhltbukklr2ati to request biomarkers and metrics { "name" "request biomarker widget data deprecated", "method" "post", "url" "https //engine intelliprove com/v2/widgets/biomarker", "description" "request biomarker widget json data for specific face scan id ", "tab" "examples", "examples" { "languages" \[ { "id" "ly k8enkjy3xdfr9fl8n0", "language" "json", "code" "{\n \\"data\\" {\n \\"face scan id\\" \\"c2f728c6 2f74 4d8c 83b9 fb4245cff2f9ll\\",\n \\"parameter\\" \\"heart rate\\"\n }\n}", "customlabel" "request body" } ], "selectedlanguageid" "ly k8enkjy3xdfr9fl8n0" }, "results" { "languages" \[ { "id" "exkhp1cp6mnfc8lacxnpm", "language" "200", "customlabel" "", "code" "{\n \\"data\\" {\n \\"value\\" 61,\n \\"name\\" \\"heart rate\\",\n \\"unit\\" \\"bpm\\",\n \\"range\\" \[\n 36,\n 216\n ],\n \\"percentage\\" 0 3388888888888889,\n \\"zone\\" 1,\n \\"optimum\\" \\"low\\",\n \\"gradientstops\\" \[\n 0 47,\n 0 55\n ],\n \\"title\\" \\"biomarker\\"\n },\n \\"config\\" {\n \\"face scan id\\" \\"c2f728c6 2f74 4d8c 83b9 fb4245cff2f9\\",\n \\"parameter\\" \\"heart rate\\"\n }\n}" } ], "selectedlanguageid" "exkhp1cp6mnfc8lacxnpm" }, "request" { "pathparameters" \[], "queryparameters" \[], "headerparameters" \[ { "name" "accept", "kind" "required", "type" "string", "description" "application/json", "children" \[] }, { "name" "authorization", "kind" "required", "type" "string", "description" "user action token obtained using the 'create user action token' endpoint, with added \\"token \\" prefix", "children" \[] } ], "bodydataparameters" \[ { "name" "face scan id", "kind" "required", "type" "string", "description" "face scan id", "children" \[] }, { "name" "parameter", "kind" "required", "type" "string", "description" "biomarker parameter of choice", "children" \[] } ], "formdataparameters" \[] }, "currentnewparameter" { "label" "header parameter", "value" "headerparameters" }, "hastryitout" false } 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 docid 3twbyjpm7m9a7dftx0xng deprecated this endpoint is deprecated and will be removed in a future version of intelliprove we advise to use the endpoints rest api docid\ biupvixvhltbukklr2ati and rest api docid\ biupvixvhltbukklr2ati to request biomarkers and metrics { "name" "request metric widget data deprecated", "method" "post", "url" "https //engine intelliprove com/v2/widgets/metric", "description" "request metric widget json data for a user ", "tab" "examples", "examples" { "languages" \[ { "id" "ly k8enkjy3xdfr9fl8n0", "language" "json", "code" "{\n \\"data\\" {\n \\"parameter\\" \\"mental health risk\\"\n }\n}", "customlabel" "request body" } ], "selectedlanguageid" "ly k8enkjy3xdfr9fl8n0" }, "results" { "languages" \[ { "id" "exkhp1cp6mnfc8lacxnpm", "language" "200", "customlabel" "", "code" "{\n \\"data\\" {\n \\"title\\" \\"metric\\",\n \\"name\\" \\"mental health risk\\",\n \\"value\\" 1, // nullable\n \\"value str\\" \\"low\\", // nullable\n \\"unit\\" \\"\\", // nullable\n \\"range\\" \[ // nullable\n 1,\n 3\n ],\n \\"percentage\\" 0 5, // nullable\n \\"zone\\" 1, // nullable\n \\"optimum\\" \\"low\\", // nullable\n \\"locked\\" false\n },\n \\"config\\" {\n \\"parameter\\" \\"mental health risk\\"\n }\n}" } ], "selectedlanguageid" "exkhp1cp6mnfc8lacxnpm" }, "request" { "pathparameters" \[], "queryparameters" \[], "headerparameters" \[ { "name" "accept", "kind" "required", "type" "string", "description" "application/json", "children" \[] }, { "name" "authorization", "kind" "required", "type" "string", "description" "user action token obtained using the 'create user action token' endpoint, with added \\"token \\" prefix", "children" \[] } ], "bodydataparameters" \[ { "name" "parameter", "kind" "required", "type" "string", "description" "metric parameter of choice", "children" \[] } ], "formdataparameters" \[] }, "currentnewparameter" { "label" "header parameter", "value" "headerparameters" }, "hastryitout" false } 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 docid 6b 0cnu5cm5uyzx4jjbxp 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 docid\ zwndc2jafp0x zki sgdr documentation { "name" "request graph widget data", "method" "post", "url" "https //engine intelliprove com/v2/widgets/graph", "description" "request graph widget json data for a user ", "tab" "examples", "examples" { "languages" \[ { "id" "ly k8enkjy3xdfr9fl8n0", "language" "json", "code" "{\n \\"data\\" {\n \\"parameter\\" \\"heart rate\\",\n \\"title\\" \\"custom graph title\\",\n \\"start\\" \\"2024 12 21t00 00 00\\",\n \\"stop\\" \\"2024 12 31t23 59 59\\" \n }\n}", "customlabel" "request body" } ], "selectedlanguageid" "ly k8enkjy3xdfr9fl8n0" }, "results" { "languages" \[ { "id" "exkhp1cp6mnfc8lacxnpm", "language" "200", "customlabel" "", "code" "{\n \\"data\\" \[\n {\n \\"value\\" 60, // nullable\n \\"hint\\" \\"\\",\n \\"label\\" \\"25/09\\",\n \\"timestamp\\" \\"2024 09 25t10 30 00\\"\n },\n ,\n ],\n \\"config\\" {\n \\"title\\" \\"custom graph title\\",\n \\"y range\\" \[\n null,\n null\n ]\n }\n}" } ], "selectedlanguageid" "exkhp1cp6mnfc8lacxnpm" }, "request" { "pathparameters" \[], "queryparameters" \[], "headerparameters" \[ { "name" "accept", "kind" "required", "type" "string", "description" "application/json", "children" \[] }, { "name" "authorization", "kind" "required", "type" "string", "description" "user action token obtained using the 'create user action token' endpoint, with added \\"token \\" prefix", "children" \[] } ], "bodydataparameters" \[ { "name" "parameter", "kind" "required", "type" "string", "description" "insight or biomarker parameter of choice", "children" \[] }, { "name" "title", "kind" "optional", "type" "string", "description" "optionally override the graph title with a string value of choice", "children" \[] }, { "name" "start", "kind" "optional", "type" "string", "description" "start date for the range of historical data to be retrieved\nformat yyyy mm dd\ndefault today 8 days", "children" \[] }, { "name" "stop", "kind" "optional", "type" "string", "description" "stop date for the range of historical data to be retrieved\nformat yyyy mm dd\ndefault today", "children" \[] } ], "formdataparameters" \[] }, "currentnewparameter" { "label" "body parameter", "value" "bodydataparameters" }, "hastryitout" true } for a list of possible values for parameter , refer to the sections biomarker widget docid 3twbyjpm7m9a7dftx0xng and metric widget docid 6b 0cnu5cm5uyzx4jjbxp dashboards these api endpoints provide easy ways to generate urls to personalised user dashboards each generated url includes a temporary, user specific access token that grants limited time access to the dashboard all the dashboard endpoints can only be accessed using the api key { "name" "get health dashboard url", "method" "post", "url" "https //engine intelliprove com/v2/dashboards/health", "description" "request a one time url for the users personal health dashboard by user id or external user id ", "tab" "examples", "examples" { "languages" \[ { "id" "ly k8enkjy3xdfr9fl8n0", "language" "json", "code" "{\n \\"external user id\\" \\"user email\@example com\\",\n \\"language\\" \\"en\\",\n \\"disabled sections\\" \[ \\"recommendations\\" ]\n}", "customlabel" "request body" } ], "selectedlanguageid" "ly k8enkjy3xdfr9fl8n0" }, "results" { "languages" \[ { "id" "exkhp1cp6mnfc8lacxnpm", "language" "201", "customlabel" "", "code" "\\"https //dashboard intelliprove com?action token=\<generated action token>\&language=en\\"" } ], "selectedlanguageid" "exkhp1cp6mnfc8lacxnpm" }, "request" { "pathparameters" \[], "queryparameters" \[], "headerparameters" \[ { "name" "x api key", "kind" "required", "type" "string", "description" "your api key", "" "your api key" } ], "bodydataparameters" \[ { "name" "user id", "kind" "optional", "type" "string", "description" "intelliprove internal user id", "" "intelliprove internal user id" }, { "name" "external user id", "kind" "optional", "type" "string", "description" "external user id, chosen when creating the user", "" "external user id, chosen when creating the user" }, { "name" "language", "kind" "optional", "type" "string", "description" "two letter language code override default user language", "" "two letter language code override default user language" }, { "name" "disabled sections", "kind" "optional", "type" "array", "description" "add section ('main', 'metrics', 'biomarkers' or 'recommendations') to list to disable it default empty list ", "" "add section ('main', 'metrics', 'biomarkers' or 'recommendations') to list to disable it default empty list " } ], "formdataparameters" \[] }, "currentnewparameter" { "label" "body parameter", "value" "bodydataparameters" }, "hastryitout" true } regulatory { "name" "get ce label", "method" "get", "url" "/v1/regulatory/ce label", "description" "request the intelliprove medical device label as png image ", "tab" "examples", "examples" { "languages" \[ { "id" "gle 59oy3czqvmz78ns1q", "language" "json", "code" "", "customlabel" "request body" } ], "selectedlanguageid" "gle 59oy3czqvmz78ns1q" }, "results" { "languages" \[ { "id" "dp tooukgypxpbotgfpbc", "language" "200", "customlabel" "", "code" "// returns 'image/png' content type image" } ], "selectedlanguageid" "dp tooukgypxpbotgfpbc" }, "request" { "pathparameters" \[], "queryparameters" \[], "headerparameters" \[], "bodydataparameters" \[], "formdataparameters" \[] }, "currentnewparameter" { "label" "body parameter", "value" "bodydataparameters" }, "hastryitout" false } refer to our instructions for use docid\ jmsmbxwfyqbsttsluvw00 for more information related to our medical device's product description and intended use