API flow
Intro
This article describes how to use the API as a whole to perform health checks. Throughout the article a demo application implementing this series of actions - the API flow - is used as an example. The importance of each call and set of consecutive calls, needed to perform a typical health check, are clarified. Actions and UI elements in the front-end that can facilitate the process for the end user are also discussed, these can serve as an example or guide for integration of the API into existing platforms.
The figure below, which shows the flow to complete a health check in the demo app, will be referenced in each of the steps.
App launch
When the app is launched, the user first receives a series of instructions on how to perform the health check correctly. Refer to the Product instructions for a comprehensive overview.
Measurement screen
After pressing continue, the user arrives at the measurement screen, where the video recording can be started.
Quality check
When pressing the red record button, the recording conditions are first reviewed. This check, also referred to as 'quality check', ensures that the recording setup meets a few requirements for a qualitative measurement. This includes, for example, checking if there is sufficient lighting, checking the face-camera distance or analyzing the user's motion. The quality check is performed based on a single frame of the user's face.
To perform the quality check, the API docs endpoint of the API can be used. In the app, a loading sign indicates the quality check is in progress.
The response of the request can be used to show relevant instructions to the user when the conditions are not met - in that case, the UI element that outlines the face will turn red in the demo app - as shown in the figures below.
The quality check is non-blocking, in other words, the measurement can be started although the response indicates that the conditions are not met. However, for a qualitative measurement, it is highly recommended to only allow the user to start the measurement when all quality conditions are met.
Performing the measurement
When the quality check succeeds, the UI element outlining the face turns green and the app automatically starts recording. The recommended recording time is 30 seconds (also see the Technical requirements). A timer indicates the remaining recording time to the user. During the measurement, the user keeps his face still and looks straight into the camera. More information can be found in the Product instructions
Once the recording is finished, the video needs to be processed in the cloud.
For the user, this is a seamless process. The app shows a loading sign while uploading the video and automatically sends a request to process it once the upload is finished, as shown below. As soon as the processing is done, the app shows the results, which is outlined in the next section.
Behind the scenes, this part consists of three steps in the API.
Request a URL to upload the video
In order to register a new measurement with the cloud and have the video processed, it first needs to be uploaded to our cloud. The API docs endpoint can be used to do this. The response of this request includes the URL, which will be used to upload the video; the unique identifier (UUID) for this measurement, which will be needed for the consecutive requests; and authentication information needed in the next step.
Upload video
With the obtained URL and authentication info, the video can now be uploaded using the API docs endpoint.
Process video
With the video now uploaded, a request can be sent to start the actual processing of the video. To specify which video to process, the UUID obtained before is sent as a path parameter with the request. Refer to the API docs endpoint in the API docs for more detailed information.
When the processing is done, the results are securly stored in a database and the video file is removed. For more information about how we treat privacy and how we handle your data, refer to the Privacy policy
Results screen
With the processing now finished, the results can be fetched from the database and displayed in the app. Use the API docs endpoint and pass the UUID in the request path parameter. The results are returned in json format. The demo app displays the results as shown below.
Keep in mind that if the UUID that was passed refers to a video that is still being processed, the API will poll the database for up to 20 seconds while waiting for the results to become available, and will send the response as soon as the results are available. This means that the API docs request can be send immediately after the API docs request; the API will take care of the polling for results. Only when the results are still not available after 20 seconds - for example in case the video just hasn't been processed yet - the API responds with a HTTP 204, indicating that no results were found.