API: Face enrolment

Introduction
Call
Response

Introduction

Face-enrolment is the first step in facial-biometric authentication process. In this step, a mathematical representation of main characteristics of a person's face is taken, by analysing a selfie image (or a document-originated image) of that person. This representation is called "faceprint" and in this process, such faceprint is resulting in a face-vector (a series/array of numerical values), used later in comparison with the actual face of a person trying to authorize.

As mentioned, such vector (faceprint) is a non-PII (non Personally Identifiable Information). This means that by itself, it cannot be used to reconstruct the face-image from which it was created.

Initially, MachineSense customer/partner sends a selfie image (or a document-originated image) of their end-user from their website or mobile app to their own servers (this step is completely independent of MachineSense), and than call the MachineSense API, including that image and some parameters.
In order to help customers start quickly with such client-side (web-based) implementation, MachineSense offers a set of examples and code, ready for copy/paste into your applications and be customized/modified. Basic operations with capuring the image, setting up parameters, etc. will be already present in those examples.
Examples are written in vanilla JavaScript, and can be used in any web-based application.
You can find them on our Demo page .

Customer creates own client-side page or app, including capturing of the user's selfie image. Exception to this might be if customer is using MachineSense whitelabel client-side, in which case this is already done for them, or MachineSense WASM component. The latter process, however is a two-step process and is related to pre-built / ready-to-use modules.

Note: With most of the other biometric providers, option to choose for liveness detection is not presented during the enrolment process. MachineSense gives you this possibility, in order to avoid possible spoofed enrolments (person enroling someone else with a photo or video feed instead of live person claiming to be of that identity).

More details about single-step and two-step processes.

Call

(Call from your server to our API.)

POST /face-api/v1/enroll

Parameters / body:

            {
                "images": [
                  "string"
                ],
                "api_key": "string",
                "ref": "string",
                "liveness": false,
                "save_image_mode": 0
                
            }

Parameters explained:

  • "images" = (mandatory) Array of images encoded as b64 (hence strings)
  • "api_key" = (mandatory) Your developer key found in your Settings
  • "ref" = (optional) Any string you wish to send back to yourself, that you will receive with the later response to your webhook.
  • "liveness" = (optional, default=false) If true, liveness detection will be active, and than at least 3 images should be provided.
  • "save_image_mode" = (default = 0). If image(s) returned together with the vector(s).

Response

Code: 200

Default response:

            {
                "result": "Ok",
                "code": 0,
                "message": "string",
                "data": {
                  "ref": "string",
                  "vector": [
                    0
                  ],
                  "liveness_score": 100,
                  "liveness_result": "string",
                  "img_index": 0
                  "images": [
                    "string"
                  ]
                }
            }

Response explained:

  • "result" = "Ok" or "Err" (error)
  • "code" = 0 or error code (int)
  • "message" = If result "Err" - textual description (string)
  • "data" = JSON object with data
    • "ref" = (Optional) Referential free-form string.
    • "vector" = Array of vectors responding to each image sent on call/request (response to "images" array from the call).
    • "liveness_score" = Liveness detection score (int), can have values 0-100. Higher the number - better the score.
    • "liveness_result" = Liveness detection result (string), with descriptive values.
    • "img_index" = Index of image in the "images" array that was used for liveness detection.
    • "images" = Array of images encoded as b64 (hence strings), if requested in the call.

Top of the Page