MobbScan Server | Identity verification

Video identity verification

MobbScan permits verifying the identity of the user carrying out the onboarding process by checking that they indeed are the owner of the ID card and are also present during the registration flow. The system accepts as inputs a video-selfie of the user in which a side to side head movement is required in addition to the picture of the ID card side containing the headshot. MobbScan will check that the facial crop from the ID corresponds to the same person that appears in the video and also the genuineness of the recording itself, detecting presentation attacks of different nature such as masks, impersonation or replaying.

MobbScan also offers an integration with MobbID, through which it is possible to register users biometrically into MobbID's applications.

Requirements

License

A license key bounded to your application is needed to start using the API. Please, contact with us to obtain one.

Example of use

Video identification request

/identityVerification

Parameter	Type	Mandatory	Comments
`licenseId`	`String`	yes	License key
`scanId`	`String`	no	MobbScan process UUID. In case of having generated it previously as part of the registration flow just use it here. In case of not, leave it empty and the system will generate a new one
`livenessMethod`	`Integer`	yes	Method used to detect liveness. Corresponds to the gesture or challenge asked to the user during the video selfie recording. Possible values: `0 (default)` : Head movement `1` : Passive `2` : Passive and random movement
`video`	`Multipart File`	yes	Recording of the user during the identity verification process
`documentImage`	`Multipart File`	yes	Image of the ID card side containing the headshot
`returnFaceImages`	`Boolean`	no	Flag indicating whether face crops (ID and selfie) are desired to be returned in the output JSON file

Video identification response

{
    "code": 0,
    "description": "Identity verification transaction finished successfully",
    "timestamp": "2020-03-03 18:05:31.129",
    "scanId": "0e76e708-1dff-47d8-80fe-12b40043f86d",
    "scores": {
        "liveness": 0.92,
        "faceMatching": 0.78,
        "identityVerification": 0.78
    },
    "validations": {
        "liveness": "VALID",
        "faceMatching": "VALID",
        "identityVerification": "VALID"
    },
    "faceDocument": "imageBase64",
    "faceSelfie": "imageBase64",
    "resultScanProcessValidation": {
        "enabledProcess": true,
        "scanProcessValidationResult": "VALID",
        "scanProcessFailedValidations": []
    },
    "mobbIdRegistration": {
        "completed": true,
        "details": "The user was successfully registered"
    }
}

code description : transaction result details. Possible values:
- 0: Identity verification transaction finished successfully
- -1: Input video file has not a valid format
- -2: Error while processing input video
- -3: Provided livenessMethod is not a valid one
- -4: Error connecting to liveness detection service
- -5: Error connecting to facial matching service
- -6: Provided scanId does not correspond to a valid started process
- -7: Error while creating a directory from an auto-generated scanId
- -8: Error while generating output JSON file
- -9: Valid face not found in input video
- -10: Movement not found in input video
- -11: Multiple faces found in input video
- -12: Valid face not found in input ID image
- -13: The list of frames, with which the video must be compound, can not be empty
- -14: Allowed values for "lastFrames" parameter are "false" or "true"
- -15: Provided scanId corresponds to a process invalidated by the validation matrix
- -16: Environment detected to be too bright in input video
- -17: Environment detected to be too dark in input video
- -18: Backlighting detected in input video
- -101: Face is too close to one or more border in input video
- -102: Face is cropped in input video
- -103: Face is too close to the camera in input video
- -200: MobbID service connection error
- -201: MobbID service was interrupted
- -202: MobbID application or api key is invalid
- -203: MobbID could not find valid face in input video
- -204: MobbID found mulitple faces in input video
- -205: MobbID indicates insufficient quality in the video input
- -206: MobbID indicates that an attack is suspected
- -299: MobbID service error
timestamp: transaction date and time details
scanId: MobbScan process UUID. In case of having previously started a scan process the value will be the same informed as input. If no scanId was provided, the system returns the auto generated one. This code is necessary to access all samples generated during the identity verification transaction.
scores: Object containing the result scores after evaluating input resources. Numerical values in the range [0-1]:
- liveness: confidence in the liveness detection process after evaluating collaborative measures (small gesture or movement) as well as non-cooperative ones (presentation attack detection).
- faceMatching: confidence in the facial matching between ID card headshot and a face image extracted from the input video stream.
- identityVerification: overall identity verification process confidence.
validations: Object containing the validations after thresholding result scores. These values are provided taking into consideration a standard security scenario, but integrators are free to use different thresholds based on their own security requirements (in this later case please contact Mobbeel support team in order to get advise).
- liveness: validation result after thresholding liveness score
- faceMatching: validation result after thresholding faceMatching score
- identityVerification: validation result after thresholding identityVerification score

Possible validation values:

VALID the evaluation was carried out and confidence is above threshold.
NOT_VALID the evaluation was carried out and confidence is below threshold.
NOT_CHECKED the evaluation was not carried out due to some error.

faceDocument: base64 image string of the facial crop extracted from the input document.
faceSelfie: base64 image string of the facial crop extracted from the input video.

Samples generated during identity verification process:

An identity verification transaction generates a number of samples that can be recovered once the process has finished. These resources are stored in the server side and can be accessed by using relevant MobbScan methods:

/{scanId}/images: GET method that returns all images generated during a MobbScan transaction

/{scanId}/images/{imageType}: GET method that returns a single image (indicated with imageType) generated during a MobbScan transaction. Possible imageType:

FACE-NOW: face extracted from the input video (selfie)

FACE-DOCUMENT: face extracted from the input document

resultScanProcessValidation: Object containing the matrix validation results.
- enabledProcess: boolean indicating whether the matrix validation is enabled or not
- scanProcessValidationResult: matrix validation result
- scanProcessFailedValidations: array of failed matrix validations

Possible scanProcessValidationResult values:

VALID the process has passed the validation matrix..
NOT_VALID the process has failed the validation matrix.
NOT_CHECKED the process was not evaluated because it was disabled.

mobbIdRegistration: Object containing the result of MobbID registration integration. It is included in the response only if the integration with MobbID is enabled.
- completed: boolean indicating whether the registration was performed and completed
- details: details of the operation