Match Face Endpoint

Method and URL Details

The URL for this API call is fixed and there are no path parameters passed through this endpoint. For Match Face API to work, submit all Document images as multipart form data with the Keys described. See the request parameter table below.

HTTP Method	URL
POST	Copy `http://localhost:9000/AirApi/1.0/MatchFace/`

Note:

For Match Face API to work, submit all Document images as multipart form data with the Keys described. See the request parameter table below.

For a correct Document crop, crop without any extra background.
For uncropped images, please set the AutoCrop header parameter to true.

Header Parameters

Match Face API does not have Header Parameters.

Body Parameters

Following are the body parameters of the multipart POST request.

Parameter Name	Type	Description
ProbeImage Required	string	Selfie image that should be validated against the gallery images.
CustomTag1 Required	string	A gallery image that holds a custom name.
CustomTag2 Optional	string	A gallery image that holds a custom name.
CustomTag3 Optional	string	A gallery image that holds a custom name.

Success Response

HTTP Code	URL
200	The verification score is returned in the response.

Sample Response

The Match Face verification score can return a score of -1.0 or -2.0 in a successful response. This means that either there was a failure to create the template for the corresponding submitted image or there was a hard error in the backend when creating the face template from the submitted image.

Note: If you send multiple gallery images you will get all the match scores back. The gallery images are only compared to the probe image, not other gallery images.

Copy

Sample Response

"MatchFaceScores": {
    "ProbeImage": {
            "ImageIntegrityScore": {
                "BiometricTamper": {
                    "Natural": 34.13,
                    "Result": "Failed",
                    "Tampered": 65.87,
                    "Threshold": 0.0
                },
                "CredentialDetector": {
                    "Natural": 99.99,
                    "Result": "Passed",
                    "Tampered": 0.01,
                    "Threshold": 101.0
                },
                "Focus": {
                    "Natural": 97.82,
                    "Result": "Passed",
                    "Tampered": 2.18,
                    "Threshold": 101.0
                },
                "NaturalCapture": {
                    "Natural": 100.0,
                    "Result": "Passed",
                    "Tampered": 0.0,
                    "Threshold": 101.0
                },
                "PhotoBorderDetector": {
                    "Natural": 99.99,
                    "Result": "Passed",
                    "Tampered": 0.01,
                    "Threshold": 101.0
                },
                "PhotoSplice": {
                    "Natural": 4.38,
                    "Result": "Passed",
                    "Tampered": 95.62,
                    "Threshold": 101.0
                },
                "PhotoStitch": {
                    "Natural": 99.29,
                    "Result": "Passed",
                    "Tampered": 0.71,
                    "Threshold": 101.0
                },
                "PrintDetector": {
                    "Natural": 95.56,
                    "Result": "Passed",
                    "Tampered": 4.44,
                    "Threshold": 75.0
                }
            }
        },
        "gallery1": {
            "VerificationScore": 100.0
        },
        "gallery2": {
            "VerificationScore": 100.0
        },
        "gallery3": {
            "VerificationScore": 16.227412223815918
        },
        "gallery4": {
            "VerificationScore": 16.227412223815918
        },
        "gallery5": {
            "VerificationScore": -1.0
        },
        "gallery6": {
            "VerificationScore": 16.227412223815918
        }
    },
    "Result": "Success",
    "TransactionId": "xxxxxxxxxxxx"
   }

Error responses

This section lists how the error/status code is received.

Error Property Name	Type	Description
ErrorCode	number	The error code is indicating what went wrong.
ErrorMessage	string	A brief description of what went wrong.
Result	string	This field is deprecated and will always be “Failed.”
TransactionId	string	This property is only returned if a transaction has been started, but an error is encountered for some reason.

Status & Error Codes

This section lists the status & error codes that are returned. A response with error codes may include an HTTP status code and a secondary error code.

The HTTP status codes are common (200, 400, 500, etc.) to the HTTP layer. The secondary error code in the response provides the necessary information to troubleshoot the issue. The error response includes the error message, error code, and TransactionId (if available).

Therefore, it is recommended that any implementation MUST capture both the HTTP status code and error codes and error messages to help troubleshoot and trace the error.

HTTPS Status Code	Error Code	Error Message
400	1001	This error is triggered when multipart data is empty. “Empty Multipart Data.”
400	1002	This error was triggered because the Access Key/Secret Token/ Probe Image was missing. “Missing Access Key/Secret Token/Probe Image.”
400	1003	This error was triggered because the Access Key was not found. “Access Key Not Found.”
400	1004	This error was triggered because the Secret Token did not correspond to the access key that was submitted. “A secret token does not correspond to the access key submitted.”
500	1045	This error was triggered because the Face Template Creation failed. This can fail when a Selfie or Portrait Headshot image (ProbImage) is found to be unusable. If the image submitted fails the Template Creation will fail also. “Face Template Creation Failed for ProbeImage.”
400	1042	This error is triggered when the image format is not a png file. “Invalid Image Format.”
400	1053	This error is triggered when there are no Face images submitted. “No Gallery Face Images Submitted.”
400	1054	This error is triggered when the user submits more than the maximum images allowed. “More Gallery Face Images Submitted than allowed.”
400	1046	This error is triggered when the Face Image field is null or empty. “Face Image is null or empty.”
500	1005	This error is triggered when there is an error thrown with processing the request. “Error Processing Request.”

Sample Error Response

Copy

{
  "ErrorCode": 1042,
  "ErrorMessage": "Invalid Image Format",
  "Result": "Failed",
  "TransactionId": "xxxxxxxxxxxxxx"
}