Biometric in Things API

Welcome to the Biometric In Things (BiT) API, an offering within Youverse Services

The BiT API is built as a RESTful API hosted with in a local server running on-premises. All requests and responses are encoded in JSON. The concept of Biometric In Things was designed to bring face authentication to the edge in developer friendly fashion by exposing complex biometric functionalities via a simple REST API that can be integrated virtually in any programming language, in any environment.

Use cases

{primary} Live face capture

Detection and capture of aligned faces using ICAO Token Face Images according to ISO/IEC 19794-5 standard.

{primary} Live face verification

Design to build user authentication/verification in edge devices using reference face images already collected.

Common use cases are face authentication based on a passport collected photo like in our VR-eKiosk project or by providing the picture obtained with the provided face capture endpoint.

{primary} Face images verification

When you need to validate if the two face images belong to the same person you can use this functionality.

For example, when integrating with a passport reader on a Kiosk, you can perform a face verification step between the chip image and the scan passport photo to check for data integrity and increase the security of your applications.

Installation guide.

To start using Youverse BiT, please visit our website and find the subscription that fits your needs. Afterwards, please follow the instruction below that fit best your scenario:

Binaries installation - Windows only

Download the binary files. Use the BiT Zip password available in your dashboard to extract the files. Launch the batch file.
Call the setup API endpoint to install everything automatically. You need to provide the x-api-key key from your subscription in the HTTP request header. This request may take some time depending on your internet connection.

Docker file - Linux only

Contact us to obtained your docker file and launch the docker container.
Call the setup API endpoint to install everything automatically. You need to provide the x-api-key key from your subscription in the HTTP request header. This request may take some time depending on your internet connection.

Image formats

All endpoints that receive images accept jpg/jpeg, png and bmp formats converted in base64 images.

The recommended resolution for optimal results is at least VGA (640×480 px). Smaller resolutions are accepted, but might not provide optimal results. Larger resolutions are also accepted, but won't improve the authentication process significantly and can result in considerable increase of the processing times.

Camera compatibility

The Youverse.BiT supports out of the box the following camera drivers/types:

Video4Linux
UVC cameras
IP cameras (RTSP)
Intel RealSense cameras.

To ask for additional camera support please contact us.

Camera configuration

Changing camera is as simply as change two lines of the configuration file. By default the config is compatible with UVC and Video4Linux.

Use UVC/Video4Linux camera

 {
 "CameraFactory": {
      "TYPE": "Generic",
      "URL": 0
    }
 }

Use IP/RTSP camera

{
   "CameraFactory": {
        "TYPE": "Generic",
        "URL": "<ADD YOUR ENDPOINT HERE>"
    }
}

Use Intel RealSense cameras

{
   "CameraFactory": {
        "TYPE": "RS2",
        "URL": 0
   }
}

Generic endpoints

Monitoring

Endpoint that returns current API availability and processing capabilities status. Check if the camera is currently connected and available for processing.

GET | {base_url}/bit/status

{success} Success

Status	Meaning	Schema
200	OK	No schema

{danger} Error responses

Status	Meaning	Schema
401	Unauthorized	N/A
500	Internal Server Error	N/A
503	Service Unavailable	Error message

{warning} This method activates the camera and disconnects it again. Calling this method too often can resolve in high stress to the device leading to failure. It should not be used before calling processing methods since it will stress the camera and increase processing times.

Setup

Endpoint that configures the Biometric In Things server. Only needs to be call once. Until the setup call does not return a suucess status code, the software will not be operational.

GET | {base_url}/bit/setup

{success} Success

Status	Meaning	Schema
200	OK	No schema

{danger} Error responses

Status	Meaning	Schema
401	Unauthorized	N/A
500	Internal Server Error	N/A

{warning} This method might take sometime to return depending on your internet speed since it s checking-out the latest face authentication models.

Processing endpoints

Live face capture

Endpoint that provides biometric capture capabilities using live stream from the configured camera. This endpoint can be used to capture the face for future reference or verification.

POST | {base_url}/bit/capture

Accepts: Capture Request

{success} Success

Status	Meaning	Schema
200	OK	Capture Response

{danger} Error responses

Status	Meaning	Schema
400	Bad Request	N/A
401	Unauthorized	N/A
500	Internal Server Error	N/A

Live face verification

Endpoint that provides verification capabilities by comparing reference image with the live capture from camera. The request accepts a face picture that can be obtained from passport scanning or any other source, e.g. using the capture endpoint.

POST | {base_url}/bit/verify

Accepts: Verify Request

{success} Success

Status	Meaning	Schema
200	OK	Verify Response

{danger} Error responses

Status	Meaning	Schema
400	Bad Request	N/A
401	Unauthorized	N/A
500	Internal Server Error	N/A

Verification of two images

Endpoint that provides verification capabilities between two face images. The request accepts two pictures, obtained for instance from the passport page scanning and passport chip, and provides a similarity score between the two.

POST | {base_url}/bit/verify_images

Accepts: Verify Images Request

{success} Success

Status	Meaning	Schema
200	OK	Verify Images Response

{danger} Error responses

Status	Meaning	Schema
400	Bad Request	N/A
401	Unauthorized	N/A
500	Internal Server Error	N/A

Schemas

Error message

String with generic error messages.

 "Error message"

{warning} It is strongly advised to not take action based on the text messages, these are meant for logging purposes only. Any action should be implemented based on status codes.

Capture request

Configurations to the face acquisition process.

{
  "capture_time_out": 10,
  "anti_spoofing": true,
  "live_quality_analysis": false
}

Properties

Name	Type	Required	Restrictions	Description
capture_time_out	int	False	None	Capture time out in seconds. Default is 10 seconds.
anti_spoofing	boolean	False	None	Flag to active liveness analysis. Default is true.
live_quality_analysis	boolean	False	None	Flag to activate image quality analysis in the face region. Default is True.

Capture response

Face capture with image and capture status results.

{
  "image": "string",
  "capture_status": [
    "capture_successful"
  ]
}

Properties

Name	Type	Required	Restrictions	Description
image	string	False	None	JPG Base 64 string face crop according to ISO/ICAO 19794-5 Token.
capture_status	array	True	None	Array with one or more enumerable to describe the success or failure during the capture process

Enumerable types

Property	Value	Description
capture_status	capture_successful	Capture successful.
capture_status	capture_timedout	Timeout passed with a face capture.
capture_status	camera_failed	Camera failed to start.
capture_status	live_face_detection_failed	Face was not detected during capture.
capture_status	live_face_quality_failed	Face was detected but without enough quality.
capture_status	liveness_detection_failed	Live face was not detected.

Verify request

Live face verification process request.

{
  "reference_image":"string",
  "capture_time_out": 10,
  "matching_score_threshold": 0.4,
  "anti_spoofing": true,
  "live_quality_analysis": false,
  "reference_live_quality_analysis": false
}

Properties

Name	Type	Required	Restrictions	Description
reference_image	string	True	BMP, PNG or JPG	Base 64 string reference face image.
matching_score_threshold	double	False	None	Configurable face matching threshold. Default is 0.4.
capture_time_out	int	False	None	Capture time out in seconds. Default is 10 seconds.
anti_spoofing	boolean	False	None	Flag to active liveness analysis. Default is true.
live_quality_analysis	boolean	False	None	Flag to activate image quality analysis in the face region. Default is false.
reference_quality_analysis	boolean	False	None	Flag to activate image quality analysis for the reference face image. Default is false.

Verify response

Face verification results.

{
  "matching_score": 0.8,
  "verified_image": "string",
  "verify_status": [
    "matching_successful"
  ]
}

Properties

Name	Type	Required	Restrictions	Description
matching_score	double	False	None	Matching score between live and reference image.
verified_image	string	False	JPG	Base 64 string thumbnail of the live matched image.
verify_status	array	True	None	Array with one or more enumerable to describe the success or failure during the verify process.

Enumerable types

Property	Value	Description
verify_status	matching_successful	Matching successful.
verify_status	matching_failed	Matching failed.
verify_status	capture_timedout	Timeout reached for the face match.
verify_status	camera_failed	Camera failed to start.
verify_status	live_face_detection_failed	Face was not detected during capture.
verify_status	live_face_quality_failed	Face was detected but without enough quality.
verify_status	liveness_detection_failed	Live face was not detected.
verify_status	reference_face_detection_failed	Reference face not detected.
verify_status	reference_face_quality_failed	Reference face without enough quality.

Verify Images Request

Provides two face images for comparison.

{
  "reference_image":"string",
  "probe_image": "string",
  "matching_score_threshold": 0.4,
}

Properties

Name	Type	Required	Restrictions	Description
reference_image	string	True	BMP, PNG or JPG	Base 64 string reference face image.
probe_image	string	True	BMP, PNG or JPG	Base 64 string probe face image.
matching_score_threshold	double	False	minimum:-1	Configurable face matching threshold. Default is 0.4.

Verify Images Response

Face images verification results.

{
  "matching_score": 0.8,
  "verify_images_status": [
    "capture_successful"
  ]
}

Properties

Name	Type	Required	Restrictions	Description
matching_score	double	False	None	Matching score between live and reference image.
verified_image	string	False	None	JPG base 64 string thumbnail of the live matched image.
verify_images_status	array	True	None	Verify images status based.

Enumerable types

Property	Value	Description
verify_images_status	matching_successful	Matching successful.
verify_images_status	matching_failed	Matching failed.
verify_images_status	probe_face_detection_failed	Face was not detected during capture.
verify_images_status	reference_face_detection_failed	Reference face not detected.

Samples & SDKs

Please check our github space for more information about our integration SDKs.
We are looking into expand our current SDK offers, if you want to contribute please contact us.

Get started

Products

IAM Integrations

Biometric in Things API

Use cases

Installation guide.

Binaries installation - Windows only

Docker file - Linux only

Image formats

Camera compatibility

Camera configuration

Generic endpoints

Monitoring

Setup

Processing endpoints

Live face capture

Live face verification

Verification of two images

Schemas

Error message

Capture request

Properties

Capture response

Properties

Enumerable types

Verify request

Properties

Verify response

Properties

Enumerable types

Verify Images Request

Properties

Verify Images Response

Properties

Enumerable types

Samples & SDKs