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 are new to this developer portal, we recommend first reading the plug in overview docid\ fwrilxhap81oojwmwf3tr , which will get you acquainted 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 documentation 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 us or set up a call your api keys carry many privileges and have no expiry date, so be sure to keep them secure ! do not share your secret api keys in publicly accessible areas such as github, client side code, and so forth after agreement, you'll receive at least two api keys development api keys, which can be used during development, are aliased with a " dev" suffix alias api key (non working examples) 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\ kcnwgx6ec3kytjfbl6n v 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 docid\ biupvixvhltbukklr2ati 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, so that you do not have to store intelliprove's uuid (the user id ) summary authentication method api key action token type of communication customer backend to intelliprove backend only customer backend or front end to intelliprove backend scope full access to all data access limited to a single user's data lifetime and creation created when you sign up for a plan does not expire created by you using your api key expire after a few hours recommended to create and use within the scope of a user's action(s) on a page of your application when using an api key for authentication, you may need to specify the user separately in certain endpoints (using the user id or external user id parameter), whereas the action token already includes this information errors in general, status codes in the 2xx range indicate success codes in the 4xx range indicate an error that failed given the information provided (e g , a required parameter was omitted or the request format is invalid, etc ) codes in the 5xx range indicate an error with intelliprove’s servers status code description 200 ok everything worked as expected 204 no content the request is correct, but there is no content to be returned 400 bad request the request was unacceptable 401 not authorized no valid authentication token provided 403 forbidden no permissions to perform the request 404 not found the request resource does not exist 422 unprocessable one or more of the request parameters are invalid 500, 502, 503 server errors something went wrong on our end the 4xx and 5xx errors can be handled programmatically and include an error description that briefly explains the error reported error format { "detail" "user not found!" } 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 every user is assigned a unique user id when providing the external user id as a query or path parameter, make sure to url encode the value this ensures that the value is received as expected on our end for example, you can use the encodeuri function ( ref ) for javascript to create a url encoded string property description user id uuid unique intelliprove id assigned to the user external user id nullable string your own unique id for the user stored in your own backend customer read only string name of the company to which the user belongs birth date nullable date object date of birth in yyyy mm dd format sex nullable string enum sex at birth values "m", "f" language nullable string enum two letter language code values "en", "nl", "fr" once created, you can reference users by both their user id or their external user id 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 the plug in url docid\ wcs2y1mg2pqnl4r4mgg z , without having to explictly provide it there anymore 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 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 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 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 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 rest api docid\ biupvixvhltbukklr2ati documentation above face scans make sure that the user action token you're providing in the authorization field, corresponds to the user that performed the face scan user health profiles the path parameter profile refers to a health profile user health profile docid\ z2qnaeg2ru 3t3hbhw8rh deprecated the 'update physical user profile' endpoint will no longer be available after july 2025 please use the rest api docid\ biupvixvhltbukklr2ati endpoint to save user profile parameters 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 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 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 for a list of possible values for parameter , refer to the sections biomarker widget docid 3twbyjpm7m9a7dftx0xng and metric widget docid 6b 0cnu5cm5uyzx4jjbxp regulatory refer to our instructions for use docid\ jmsmbxwfyqbsttsluvw00 for more information related to our medical device's product description and intended use questions the following endpoints are related to user questions this endpoint returns all availble lookup keys and is not customer or user specific