Match Selfie Endpoint
Method and URL Details
The URL for this API call is fixed and there are no path parameters passed through this endpoint.
| HTTP Method | URL |
|---|---|
| POST |
Copy
|
Header Parameters
| Parameter Name | Type | Description |
|---|---|---|
|
Accept Optional |
string |
application/JSON Default: application/JSON |
|
Location Optional
|
string |
This always sends an exact location code. If the wrong location is sent, an error occurs. The location code is also referred to as an Account code. The code is used to differentiate between sub-accounts within a merchant account. Your implementation manager can provide this code. Note: Exclude parameters unless your stakeholder has elected to use multiple decision models in IDE
Default: Configured for the Merchant in IDE. |
|
UID Optional |
string |
This is a user identifier Merchant configurable string. This helps you correlate transactions to your internal systems. Example: Some Clients use telephone numbers or the customer’s user identifier number. |
Body Parameters
The following table explains body parameters for MatchSelfie and MatchLiveness Selfie.
| Parameter Name | Type | Description |
|---|---|---|
|
SelfieBase64 Required |
string |
The selfie image in the base64 format. |
|
TransactionId Required |
string |
TransactionId of the document with which the selfie must be matched. This TransactionId is returned in the Authenticate Document Response. |
|
LivenessSelfie Required |
boolean |
Indicates whether the image submitted should be treated as a regular selfie or a liveness selfie. Set it to 'true' for processing the liveness selfie.
Default: False |
|
EnablePeriocularRecognition Optional |
boolean |
A parameter when enabled, will allow the selfie to be matched with a mask on. |
Success Response
| HTTP Code | URL |
|---|---|
| 200 |
MatchSelfie result is displayed. |
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 |
|---|---|---|
|
500 |
1005 |
Error Processing Selfie Request/Internal Server Error/Error Retrieving Image Data (TransactionId of request) |
|
500 |
1009 |
This error is triggered when metadata from the front of the submitted document is not readable. “Error Reading Metadata.” (TransactionId of request) |
|
400 |
1010 |
This error is triggered when the TransactionId does not have enough data for a minimal check. “Error doing the minimal check.” (TransactionId of request) |
|
400 |
1026 |
This error is triggered when no faces or multiple faces were detected greater than the configured number. (TransactionId of request) |
|
400 |
1028 |
This error is triggered when the location code is not found. Check to see if the Location Code is enabled or disabled. “Location Code Inactive/Not Found/Default Location Not found.” (TransactionId of request) |
|
400 |
1029 |
This error is triggered when No Location Code exists for transactionId. (TransactionId of request) |
|
400 |
1030 |
This error is triggered when there is a Location Code Mismatch for transactionId. (TransactionId of request) |
|
400 |
1034 |
This error is triggered when a Merchant account is no longer active. “Inactive Merchant.” (TransactionId of request) |
|
400 |
1042 |
This error is triggered when the submitted image is invalid. Make sure the image is sent in png format. “Invalid Image Format.” (TransactionId of request) |
|
401 |
2001 |
This error is triggered when the customer's account License contract has expired. “CatfishAIR License Expired.” (TransactionId of request) |
Sample Response
MatchSelfie Sample Response
The following example describes the response structure and values returned by Match Selfie API when the user processes an authentication request.
MatchSelfie Sample Response
{
"AccessKey": "#xxxxx",
"ActionCodes": {
"actionMessage": "Failed transaction, but take no action",
"cat": "Environment",
"code": 60
},
"ApiRequestHeaders": {
"CONTENT-LENGTH": "1614773",
"ENROLLFACE": "false",
"HOST": "api.di.catfishair.io:xx",
"RAW-REQUEST-URI": "/AirApi/2.0/MatchSelfie",
"REMOTE-ADDRESS": "xxx.xxx.x.xxx:xxxxx",
"TIMEOUT-ACCESS": "<function1>",
"TLS-SESSION-INFO": "[Session-1, SSL_NULL_WITH_NULL_NULL]",
"USER-AGENT": "python-requests/2.23.0",
"X-AMZN-TRACE-ID": "xxxxxx-xxxxxxxx-xxxxxxxxxxxxxxxxxxxxxxxx",
"X-FORWARDED-FOR": "xxx.xxx.xxx.xxx",
"X-FORWARDED-PORT": "xx",
"X-FORWARDED-PROTO": "https"
},
"ApiVersion": 2.0,
"ErrorCodes": {
"1101": "Error occurred for Front DPI Resolution",
"1102": "Error occurred for Front Colorspace Analysis",
"1131": "Error occurred for Allowable Country",
"1134": "Error occurred for Allowable Document Type",
"1501": "Error occurred for Camera Used - Front",
"1504": "Error occurred for Capture Type - Front",
"1805": "Error occurred for Expiration Date Integrity",
"1807": "Error occurred for Personal Information Analysis",
"1813": "Error occurred for Issue Date Integrity",
"2002": "Error occurred for Barcode Integrity",
"2110": "Document found in Your Company Document Watchlist"
},
"LivenessSelfieScores": [],
"MatchedSegmentAlgorithms": [
"UnprocessedImages",
"AdvancedPaperDetection",
"MissingFullnameData",
"ExpiredID",
"FacialRecognition1"
],
"MerchantId": "xxxx-xxxx-xxxx",
"ProcessingTimeInMilliSeconds": 3937,
"SegmentName": "Fraud Review",
"SegmentUiSettings": "color:#FFFFFF;background:#FF0000;",
"SelfieDemographicData": {
"HeadShot": {
"age": 00
"chinX": 000,
"chinY": 000,
"ethnicity": "xxxxxxx",
"faceScore": 0.8430569171905518,
"gender": "xxx",
"glasses": "None",
"iod": 138.0,
"leftEyeX": 314,
"leftEyeY": 251,
"lips": "Together",
"pitch": 3.0,
"rightEyeX": 176,
"rightEyeY": 251,
"roll": 0.0,
"spoof": 0.0,
"yaw": 2.0
},
"Selfie": {
"age": 00,
"chinX": 553,
"chinY": 1104,
"ethnicity": "xxxxx",
"faceScore": -0.1920628547668457,
"gender": "xxxx",
"glasses": "None",
"iod": 250.0,
"leftEyeX": 717,
"leftEyeY": 632,
"lips": "Together",
"pitch": -14.0,
"rightEyeX": 469,
"rightEyeY": 610,
"roll": 0.0,
"spoof": 0.0,
"yaw": -2.0
}
},
"SelfieImageAnalysis": {
"Result": "Passed",
"Selfie": {
"ColorSpace": "24-bit Color",
"Height": 1763,
"NumFaces": 1,
"Width": 1410
}
},
"SelfieImageIntegrityAnalysis": {
"CredentialDetector": {
"Selfie": {
"Natural": 100.0,
"Result": "Passed",
"Tampered": 0.0,
"Threshold": 101.0
}
},
"NaturalCapture": {
"Selfie": {
"Natural": 100.0,
"Result": "Passed",
"Tampered": 0.0,
"Threshold": 101.0
}
},
"PhotoBorderDetector": {
"Selfie": {
"Natural": 99.98,
"Result": "Passed",
"Tampered": 0.02,
"Threshold": 101.0
}
},
"PrintDetector": {
"Selfie": {
"Natural": 99.49,
"Result": "Passed",
"Tampered": 0.51,
"Threshold": 75.0
}
},
"Result": "Passed"
},
"SelfieRiskConditions": {
"BradDebug": {
"Address": "xxxxxxx, xxxx",
"add": 00,
"add1": 00,
"dev": 2.0,
"dev1": 2.0,
"equal": "false",
"equal1": "false",
"greater": "true",
"greater1": "true",
"greater_equal": "true",
"greater_equal1": "true",
"less": "false",
"less1": "false",
"less_equal": "false",
"less_equal1": "false",
"logical_and": "false",
"logical_or": "true",
"mod": 0.0,
"mod1": 0.0,
"mul": 18.0,
"mul1": 18.0,
"not_equal": "true",
"not_equal1": "true",
"outputNum": "6-3",
"outputNum1": "63",
"outputNum2": "6/3",
"outputNum3": "6%3",
"outputNum5": "6==3",
"outputString": "abc-efg",
"sub": 3.0,
"sub1": 3.0
}
},
"SelfieRiskVectorAnalysis": {
"AuthenticityAnalysis": {
"Selfie": {
"Display": "",
"Result": "Disabled"
}
},
"CameraUsed": {
"Selfie": {
"Display": "",
"Result": "Disabled"
}
},
"CaptureMethod": {
"Selfie": {
"Display": "",
"Result": "Disabled"
}
},
"CaptureTime": {
"Selfie": {
"Display": "",
"Result": "Disabled"
}
},
"CaptureType": {
"Selfie": {
"Display": "",
"ExifData": null,
"Result": "Disabled"
}
},
"DeviceOrientation": {
"Selfie": {
"Display": "",
"Result": "Disabled"
}
},
"LocationAnalysis": {
"Selfie": {
"Display": "No GPS data available",
"Result": "Disabled"
}
},
"Result": "Disabled"
},
"SelfieRiskVectorData": {
"Selfie": {
"Exif": {},
"MobileSDK": {}
}
},
"SelfieScores": [
{
"Name": "HeadShot",
"VerificationScore": 4.5387983322143559
}
],
"TransactionDate": "06/Jul/2020 11:14:39",
"TransactionId": "xxxxx"
}MatchLiveness Selfie Sample Response
The following example describes the response structure and values returned by the MatchSelfie API when a user processes an authentication request using a liveness selfie.
MatchLiveness Selfie Sample Response
{
"AccessKey": "#xxxxx",
"ActionCodes": {
"actionMessage": "Failed transaction, but take no action",
"cat": "Environment",
"code": 60
},
"ApiRequestHeaders": {
"CONTENT-LENGTH": "1614772",
"ENROLLFACE": "false",
"HOST": "api.di.catfishair.io:xx",
"RAW-REQUEST-URI": "/AirApi/2.0/MatchSelfie",
"REMOTE-ADDRESS": "xxx.xxx.x.xxx.xxxxx",
"TIMEOUT-ACCESS": "<function1>",
"TLS-SESSION-INFO": "[Session-1, SSL_NULL_WITH_NULL_NULL]",
"USER-AGENT": "python-requests/2.23.0",
"X-AMZN-TRACE-ID": "Root=1-5f030a1d-ec0eda6744420ac619041a88",
"X-FORWARDED-FOR": "xxx.xxx.xxx.xxx",
"X-FORWARDED-PORT": "xx",
"X-FORWARDED-PROTO": "https"
},
"ApiVersion": 2.0,
"ErrorCodes": {
"1101": "Error occurred for Front DPI Resolution",
"1102": "Error occurred for Front Colorspace Analysis",
"1131": "Error occurred for Allowable Country",
"1134": "Error occurred for Allowable Document Type",
"1401": "Error occurred for Passive Selfie Analysis",
"1501": "Error occurred for Camera Used - Front",
"1504": "Error occurred for Capture Type - Front",
"1805": "Error occurred for Expiration Date Integrity",
"1807": "Error occurred for Personal Information Analysis",
"1813": "Error occurred for Issue Date Integrity",
"2002": "Error occurred for Barcode Integrity",
"2110": "Document found in Your Company Document Watchlist"
},
"LivenessSelfieScores": [
{
"Name": "Selfie0",
"VerificationScore": 100.0
}
],
"MatchedSegmentAlgorithms": [
"UnprocessedImages",
"AdvancedPaperDetection",
"MissingFullnameData",
"ExpiredID",
"FacialRecognition1"
],
"MerchantId": "xxxxx-xxxxx-xxxxx",
"ProcessingTimeInMilliSeconds": 4323,
"SegmentName": "Fraud Review",
"SegmentUiSettings": "color:#FFFFFF;background:#FF0000;",
"SelfieDemographicData": {
"LivenessSelfie": {
"age": 00,
"chinX": 553,
"chinY": 1104,
"ethnicity": "xxxxx",
"faceScore": -0.1920628547668457,
"gender": "xxxx",
"glasses": "None",
"iod": 250.0,
"leftEyeX": 717,
"leftEyeY": 632,
"lips": "Together",
"pitch": -14.0,
"rightEyeX": 469,
"rightEyeY": 610,
"roll": 0.0,
"spoof": 0.0,
"yaw": -2.0
}
},
"SelfieImageAnalysis": {
"Result": "Passed",
"Selfie": {
"ColorSpace": "24-bit Color",
"Height": 1763,
"NumFaces": 1,
"Width": 1410
}
},
"SelfieImageIntegrityAnalysis": {
"CredentialDetector": {
"Selfie": {
"Natural": 100.0,
"Result": "Passed",
"Tampered": 0.0,
"Threshold": 101.0
}
},
"NaturalCapture": {
"Selfie": {
"Natural": 100.0,
"Result": "Passed",
"Tampered": 0.0,
"Threshold": 101.0
}
},
"PhotoBorderDetector": {
"Selfie": {
"Natural": 99.98,
"Result": "Passed",
"Tampered": 0.02,
"Threshold": 101.0
}
},
"PrintDetector": {
"Selfie": {
"Natural": 99.49,
"Result": "Passed",
"Tampered": 0.51,
"Threshold": 75.0
}
},
"Result": "Passed"
},
"SelfieRiskConditions": {
"BradDebug": {
"Address": "xxxxxxxx, xxxxx",
"add": 00,
"add1": 00,
"dev": 2.0,
"dev1": 2.0,
"equal": "false",
"equal1": "false",
"greater": "true",
"greater1": "true",
"greater_equal": "true",
"greater_equal1": "true",
"less": "false",
"less1": "false",
"less_equal": "false",
"less_equal1": "false",
"logical_and": "false",
"logical_or": "true",
"mod": 0.0,
"mod1": 0.0,
"mul": 18.0,
"mul1": 18.0,
"not_equal": "true",
"not_equal1": "true",
"outputNum": "6-3",
"outputNum1": "63",
"outputNum2": "6/3",
"outputNum3": "6%3",
"outputNum5": "6==3",
"outputString": "abc-efg",
"sub": 3.0,
"sub1": 3.0
}
},
"SelfieRiskVectorAnalysis": {
"AuthenticityAnalysis": {
"Selfie": {
"Display": "",
"Result": "Disabled"
}
},
"CameraUsed": {
"Selfie": {
"Display": "",
"Result": "Disabled"
}
},
"CaptureMethod": {
"Selfie": {
"Display": "",
"Result": "Disabled"
}
},
"CaptureTime": {
"Selfie": {
"Display": "",
"Result": "Disabled"
}
},
"CaptureType": {
"Selfie": {
"Display": "",
"ExifData": null,
"Result": "Disabled"
}
},
"DeviceOrientation": {
"Selfie": {
"Display": "",
"Result": "Disabled"
}
},
"LocationAnalysis": {
"Selfie": {
"Display": "No GPS data available",
"Result": "Disabled"
}
},
"Result": "Disabled"
},
"SelfieRiskVectorData": {
"Selfie": {
"Exif": {},
"MobileSDK": {}
}
},
"SelfieScores": [],
"TransactionDate": "06/Jul/2020 11:25:19",
"TransactionId": "xxxxxxxxxxxx"
}Response Parameters
The below table explains the parameters of MatchSelfie and MatchLiveness Selfie API Call:
| Parameter Name | Type | Description |
|---|---|---|
|
SelfieDemographicData |
object |
Contains the demographic data of the submitted selfie image (Gender, Age, Mouth, Spoof, and Glasses). Currently not available for Liveness Selfie Images. This data is available if the FR provider configured in CatfishAIR is RankOne. |
|
SelfieScores |
object |
An array containing the Verification Score based on comparison between selfie to selfie or Selfie to Headshot. The Name field in the array element will define if the comparison was done to Headshot or Selfie. If LivenessSelfie is set to true this array will be empty. If set to false the array will contain SelfieScores. |
|
LivenessSelfieScores |
object |
An array containing the verification scores based on comparison between Liveness selfie to selfie. The Name field in the array element will define to which selfie the comparison was done. If LivenessSelfie is set to false this array will be empty. If set to true the array will contain LivenessSelfieScores. |
|
ApiVersion
|
string |
This displays the API version that used to perform the MatchSelfie. |
|
AccessKey |
string |
This displays the Accesskey used to perform the matchselfie. |
|
SelfieRiskVectorAnalysis |
object |
The Risk Vector Analysis contains the Testsrun on the images submitted and theResults. For more information, please refer to the RiskVector Analysis Parameter. |
|
SelfieRiskConditions |
object |
This section displays the results executed based on the DQL conditions written in the DQL file that is being used. These results may vary for the different documents processed and the DQL file is being used. |
|
SelfieImageAnalysis
|
object |
The image analysis displays ColorSpaceand DPIvalues calculated on the submitted selfie image. A child of the DocumentInfo object. |
|
SelfieImageIntegrityAnalysis |
object |
This displays the result of Tamper/Image integrity analysis on the selfie as Pass or Failed. |
|
APIRequestHeaders
|
string |
This displays all the request parameters sent in the request headers with values. |
|
SelfieRiskVectorData |
object |
This displays the risk vector data of a captured Selfie along with its Exif data. |
|
ProcessingTimeInMilliSeconds |
number |
This displays the time taken to process the MatchSelfie in milliseconds. |
|
MerchantId |
string |
The MerchantId corresponds to the transaction |
|
ErrorCode |
number |
The ErrorCode if the transaction fails and is sent only when the Transaction fails. |
|
ErrorCodes |
object |
This section contains the list of error codes that run against each algorithm during Selfie processing. |
|
ErrorMessage |
string |
The ErrorMessage corresponds to the ErrorCode above and is sent only when the Transaction fails. |
|
Status |
string |
This displays the transaction processing status as Success, Failed, or Unknown. |
|
StatusCode |
string |
This displays the Status as: Empty/Null: When the transaction is successful. Error Code (3010, 3000, 3020): Actual Error Code. |
|
TransactionID |
string |
TransactionID is submitted. |
|
Description |
string |
The displays a description result: Example:
|
|
MatchScore
|
integer |
A final score displaying the results of Selfie to Headshot match and/or Selfie to LivenessSelfie match. A score will show a match score percentage. Example: 44.9779331684113. |
|
SegmentName
|
string |
This is the name of the segment to which the transaction has been assigned. |
|
SegmentUiSettings
|
string |
This is the color of the segment to which the transaction has been assigned. |
|
MatchedSegmentAlgorithms
|
object |
This JSON array object contains the names of algorithms configured, which are responsible for mapping the transaction to the segment assigned. |
|
ActionCodes
|
object |
This determines the action code (code) assigned to the segment name. |
