Liveness Validation

This endpoint allows the Liveness validation process on the any face related request.

Liveness Validation

POST Https://api.biometrid.com/api/1.1/liveness/validate

Validate document process

Headers

Name	Type	Description
x-zoom-version	string	Possible values: custom-v2. Required for newer versions of liveness engine.
Content-type	string	Request content type (This is not required to be set. Referenced only to show how we expect data to be sent). { "Content-Type": "multipart/form-data" }
x-biometrid-key	string	Application Client Key
x-biometrid-secret	string	Application Client Secret

Request Body

Name	Type	Description
auditTrailImage	string	Required only for specific liveness engine version. Ask for more details.
zoomSessionId	string	Session identifier of the liveness zoom process.
facemap	string	String base64 containing necessary information for the validation process. Extracted with the mobile SDK's only.
zoomSessionData	object	Data file containing the necessary information for the validation process. Extracted with the web SDK's only.
processId	string	Optional process id. Setup a specific process id.

200 Success 200 types

HTTP/1.1 200 OK

//Validate Document Process
{
  "status": true,
  "data": {
    "livenessId": "2d2faa50-d3e9-11e9-bcfc-a346419aa7ef",
    "livenessResult": {
      "meta": {
        "ok": true,
        "code": 200,
        "mode": "dev",
        "m": {
          "bt": 1255,
          "zb": 1291,
          "zp": 1332,
          "zw": 1349,
          "st": 1568133406.759338
        },
        "message": "The facemap exhibited liveness."
      },
      "data": {
        "livenessResult": "passed",
        "livenessScore": 86,
        "glassesScore": 5,
        "glassesDecision": false,
        "retryFeedbackSuggestion": 1,
        "facemapIsLowQuality": false,
        "creationStatusFromZoomServer": "The facemap was created successfully.",
        "errorFromZoomServer": null
      }
    }
  }
}

//Failed Liveness Detection

{
  "status": true,
  "data": {
    "livenessId": "2d2faa50-d3e9-11e9-bcfc-a346419aa7ef",
    "livenessResult" : {
        "meta" : {
            "ok" : true,
            "code" : 200,
            "mode" : "dev",
            "m" : {
                "bt" : 1067,
                "zb" : 1089,
                "zp" : 1103,
                "zw" : 1116,
                "st" : 1571051011.2923
            },
            "message" : "The facemap did not exhibit liveness."
        },
        "data" : {
            "livenessResult" : "undetermined",
            "livenessScore" : 5,
            "glassesScore" : 5,
            "glassesDecision" : false,
            "retryFeedbackSuggestion" : 3,
            "facemapIsLowQuality" : false,
            "creationStatusFromZoomServer" : "The facemap was created successfully.",
            "errorFromZoomServer" : null
        }
    }
  }
}

400 Bad Request types

HTTP/1.1 400 Bad Request

// Invalid Session Id
    {
        "status": false,
        "data": {
            "message": "INVALID_ZOOMSESSIONID"
        }
    }


// No liveness files detected on request. Not sent or invalid format
    {
        "status": false,
        "data": {
            "message": "NO_FILE_OR_INVALID_FORMAT"
        }
    }
    
// Missing Headers
 {
    "status": false,
    "data": {
        "message": "AUTHENTICATION_HEADERS_MISSING"
    }
}

// Invalid Facemap
    {
        "status": false,
        "data": {
            "message": "INVALID_FACEMAP_FILE"
        }
    }

// Missing auditTrailImage
    {
        "status": false,
        "data": {
            "message": "MISSING_AUDITTRAILIMAGE"
        }
    }

// Invalid auditTrailImage
    {
        "status": false,
        "data": {
            "message": "INVALID_AUDITTRAILIMAGE"
        }
    }

401 Invalid Headers.

HTTP/1.1 401 Unauthorized

{
    "status": false,
    "data": {
        "message": "INVALID_AUTHENTICATION_HEADERS"
    }
}

402 Payment Required - Request Limit Reached for Client Plan.

HTTP/1.1 402 Payment Required

{
    "status": false,
    "data": {
        "message": "REQUEST_LIMIT_REACHED"
    }
}

404 Not Found

HTTP/1.1 404 Not Found

//Client not found by given key.
{
    "status": false,
    "data": {
        "message": "CLIENT_NOT_FOUND/CHECK_AUTHENTICATION_HEADERS"
    }
}

405 No active engine configuration for this provider.

HTTP/1.1 405 Method Not Allowed

{
    "status": false,
    "data": {
        "message": "NO_LIVENESS_ENGINE_CONFIGURATION_AVAILABLE"
    }
}

504 Request timeout - algorithm unable to process the image file.

HTTP/1.1 504 Gateway Timeout

{
    "status": false,
    "data": {
        "message": "REQUEST_TIMEOUT_EXCEEDED"
    }
}

Example (JSON)

// Mobile SDK's
{
    "zoomSessionId": "d3213-23dds2-75rgu6-ds3434",
    "facemap": String base64 here,
    "processId": "123"
}

// Web SDK's
{
    "zoomSessionId": "d3213-23dds2-75rgu6-ds3434",
    "zoomSessionData": file.zip here,
    "processId": "123"
}

// Usage example for optional
{
    "zoomSessionId": "d3213-23dds2-75rgu6-ds3434",
    "facemap": String base64 here,
    "auditTrailImage": String base64 here,
    "processId": "123"
}

Success 200

Field	Type	Description
status	Boolean	Response status.
data	Object	Response main data.
livenessId	String	Liveness Process Identifier necessary for upcoming requests.
livenessResult	Object	Object containing the result of the liveness validation process.