Basic Identify

Biometric identification consists of determining the identity of a person. The aim is to capture an item of biometric data from this person. It can be a photo of their face, a record of their voice, or an image of their fingerprint. This data is then compared to the biometric data of several other persons kept in a database. In this mode, the question ​is simple: “Who are you?”

Face Identification

To perform a face identification check and create a new enrolment if a duplicate is not found.

This API currently supports basic authentication. All endpoints require an Authentication header in the following form:

Authorization: 'Basic ' + Base64.encode(username + ':' + password)

Send a HTTP POST request to:

  • /api/v1/basic/face/identify

The following parameters are used for requests and responses:

ParameterDirectionDescription
sessionIdrequestunique, short-lived code to be generated by the client to track specific sessions
subjectIdrequestunique subject identifier in case enrolment is needed
faceImageBaserequestonboarded person photo, Base64 format or URL link to it
passiveLivenessrequestboolean parameter to perform/not perform passive liveness check, i.e. to detect if photo is genuine or a spoof
sessionIdresponseunique, short-lived code to be generated by the client to track specific sessions. Same as in request
subjectIdresponseunique subject identifier in case enrolment is needed. Same as in request
hitsresponsearray of persons reached identification threshold (i.e. “duplicates found”
hits/subjectIdresponseunique duplicate subject identifier
hits/scoreresponseidentification score of the subject. Higher score means higher matching level
hasErrorresponseboolean parameter - true - identification process ended up with some error; false - no errors
errorresponseerror message in case of hasError set to true, informing about type of error: FACE_IMAGE_MISSING, INTERNAL_ERROR etc.
isUniqueresponseboolean parameter - true - no hits; false - hits (matching person(s) were found)
passiveLivenessScoreresponsenumeric result of Passive Liveness check in range [0;1], default threshold is 0.8 (i.e. <0.8 is a potential spoof)
Request:
{
  "faceImageBase": "data:image/png;base64,/9j/4AAQSkZJRgABAQAAAQABAAD/2wBDAAIBAQEBAQIBAQECAgICAgQDAgICAgUEBAMEBgUGBgYFBgYGBwkIBgcJBwYGCAsICQoKCgoKBggLDAsKDAkKCgr
...
+SSyDCtmmrGoXzc8AcrURjKEjNOK6DII0ZyJFVgepUdKv26X0WVhuGcMPlBP3RVeFluDiNdvY8VbEUnO2UjaOTnrXoUZc8dTOdSUZEotL7A/eD/AL6oqVLJCoJmk6f3qKv2Rz+0if/Z",
  "sessionId": "bbbf9002-c3a2-4308-b103-d80b9f5a2b84",
  "subjectId": "John Doe-12345-23124",
  "passiveLiveness": true
}

Response - passive liveness passed, no duplicates, person enrolled:
{
  "sessionId": "bbbf9002-c3a2-4308-b103-d80b9f5a2b84",
  "subjectId": "John Doe-12345-23124",
  "passiveLivenessScore": 0.9997104,
  "isUnique": true,
  "hasError": false
}

Response - passive liveness passed, duplicate found, no enrollment:
{
  "sessionId": "bbbf9002-c3a2-4308-b103-d80b9f5a2b84",
  "subjectId": "John Doe-12345-23124",
  "passiveLivenessScore": 0.9997104,
  "isUnique": false,
  "hits": [
  {
    "subjectId": "John Smith-55555-23222",
    "score": 144
  }
],
  "hasError": false
}

Response - passive liveness not passed
{
"sessionId": "bbbf9002-c3a2-4308-b103-d80b9f5a2b84",
"subjectId": "John Doe-12345-23124",
"passiveLivenessScore": 2.1067458E-06,
"hasError": false
}

Response - error
{
  "sessionId": "bbbf9002-c3a2-4308-b103-d80b9f5a2b84",
  "hasError": true,
  "error": "TOO_MANY_FACES"
}

List of errors

ErrorDescription
TOO_MANY_FACESMore than one face on the image
FACE_TOO_CLOSEFace too close, distance to be increased
FACE_CLOSE_TO_BORDERFace too close to border, face to be placed in the middle of the image
FACE_CROPPEDPart of the face is not visible
FACE_IS_OCCLUDEDPart of the face is coveered by some object
FACE_NOT_FOUNDFace not detected
FACE_TOO_SMALLFace too close, distance to be decreased
FACE_ANGLE_TOO_LARGEYaw/pitch/roll angle is too big
ENROLMENT_REJECTED_SUBJECT_EXISTSThe same subjectId sent for the enrolment. subjectId should be unique
ENROLMENT_REJECTED_DUPLICATE_FOUNDInternal error, contact us
ENROLMENT_REJECTEDInternal error, contact us
IMAGE_INVALIDImage broken
ENROLL_ERRORInternal error, contact us
IDENTIFY_ERRORInternal error, contact us
INTERNAL_ERRORInternal error, contact us

Certn ID Face Quality Requirements for Uncontrolled Face Capture

As biometrics is an inherently probabilistic operation, ensuring high quality images are sent to our API is important to achieve the best possible accuracy. Below is a description of the basic requirements for accurate biometric operation. Don’t worry - the system likely won’t return errors if some of these requirements are not exactly met; rather the accuracy will proportionally drop. If too many requirements are not met, the API may return an error message.

NameDescriptionRequirement
PitchA face attribute representing the rotation angle of the head towards the camera reference frame around X-axis as per DIN9300.± 15 degrees
YawA face attribute representing the rotation angle of the head towards the camera reference frame around Y-axis as per DIN9300.± 30 degrees
RollA face attribute representing the rotation angle of the head towards the camera reference frame around Z-axis as per DIN9300.± 15 degrees
Eye DistanceDistance between the eyes (interpupillary distance) in pixels.Minimum 80 pixels
Face SizeNumber of pixels in the image consisting of the face.Minimum 250 pixels
Face Image RatioThe percentage of the overall image taken up by the face.Minimum 25%
Max FacesThe maximum number of faces present in the image.1
PaddingThe number of pixels between the edges of the face and the edge of the image.Minimum 25 pixels
SunglassesPresence of sunglassesRecommended to remove
SharpnessA face attribute for evaluating whether an area of the face image is blurred.Avoid blur
Fisheye lensesIf the image was captured using a fisheye lens.Not supported
BrightnessA face attribute for evaluating whether an area of the face is correctly exposed.Capture in a well lit space