# Compare

# Version

5.0.0

# Description

This interface is used to upload customer image data and obtain the 1:1 face comparing results.

# Request URL

Singapore: POST https://api-sgp.yljz.com/finauth/v5/compare

Indonesia: POST https://api-idn.yljz.com/finauth/v5/compare

Note : In a production environment, please use HTTPS communication method. HTTP communication is an unsafe link and involves security risks. Please do not use it in a production environment. If you use HTTP in a production environment, service reliability cannot be guaranteed.

# Permission

Only when the user accesses the FinAuth product can the FinAuth Web APIs be called. Please consult FinAuth business personnel for the process of accessing FinAuth.

# Parameters

Optional/mandatory			Parameter name	Parameter type	Parameter description
Mandatory			sign	String	Customer's signature for invoking this API. Please refer to the "Authentication Guide" document for the specific method of generating the signature.
Mandatory			sign_version	String	Please pass the signature algorithm version number as "hmac_sha1"
Optional			biz_no	String	"Default is empty". Customer's business serial number, recommended to be set as a unique serial string related to your business. It will be returned to your server as is during the 'return' process, helping you confirm the ownership of the corresponding business. This field should not exceed 128 bytes.
Mandatory			compare_id	String	Compare Scene ID: The configuration related to this verification request can be set in the "Console Compare Scene", and the generated ID number will be used in the interface
Mandatory			encryption_type	String	Whether to enable data encryption during transmission: 0: Not open 2: RSA For detailed information, please refer to the "Encryption Guide" document.
Mandatory			image	File	Verify by uploading your own photo
Mandatory			image_ref1	File	The reference face photo provided by the application. If no face is found in image_ref1, error code 400 (NO_FACE_FOUND) will be returned; If there are multiple faces in the image, the largest face will be selected for comparison
Optional			uuid	String	It is used to mark the unique ID of the user corresponding to this recognition, with a length not exceeding 128 bytes. Continuously using the same ID for the same user facilitates result tracing and data report optimization.

# Return Values

Parameter category	Parameters	Type	Remarks
#Basic return information	request_id	String	Unique character string used to distinguish each request.
	biz_no	String	The business serial number passed in will be returned as is.
	time_used	Int	Time spent for the whole request (unit: millisecond). This field must be returned.
	error	String	This character string will be returned only in case of failed request. Detailed return is included in the following error section. Otherwise, this field does not exist.
#code	result_code	Int	Indicate the status code of the result of this verification. Specific results and reasons can be obtained by combining with the fields "result_code" and "result_message": The 1000 series status code indicates that the liveness has passed the verification and is the same person The 2000 series status code indicates that the comparison has been completed and the liveness has passed the verification, but at least one of the images to be compared with the reference image or one of the reference images is not the same person For other results, please reserve a processing scheme. For possible errors in the future, we may continue to increase the error code
#Status code description	result_message	String	The specific reason can be known through this field information. For details, please refer to the comparison table of result_code & result_message.
#Comparison results	verification	Json	"ref1"： comparison results between the image and image_ref1 uploaded "confidence"：Float type, with a value of [0,100]. A larger number indicates a lower risk. “thresholds”：a set of confidence thresholds for reference; Object type; consisting of four fields (all of Float type), with a value of [0,100]: “1e-3”：confidence threshold with a risk of 1/1000 (corresponding to the comparison strictness = loose in the Console compare scenario configuration) confidence threshold with a risk of 1/10000 (corresponding to the comparison strictness = conventional (default value) in the Console compare scenario configuration) confidence threshold with a risk of 1/100000 (corresponding to the comparison strictness = strict in the Console compare scenario configuration) confidence threshold with a risk of 1/1000000 (corresponding to the comparison strictness = very strict in the Console compare scenario configuration) Note: The comparison reference threshold configured in the "Comparison Strictness" of the compare scenario in the Console will directly affect the comparison status code result_code; if the Confidence Level of the comparison result is greater than the set comparison threshold, the comparison passes (result_code=1000), and if it is less than the set comparison threshold, the comparison fails (result_code=2000).
#Additional return information	images	Json	A list of images: corresponding image fields will be added based on the collected images in the future. image_best: a photo of liveness (base64 coding). image_faceshot: Close-up photo of the face, base64 encoded (this parameter is returned and needs to be enabled in the console)
	video_key	String	Decryption key: used to obtain videos and images saved on the SDK (not a mandatory return field, with permission required).
	visual_attributes	Json	Additional Attributes: “age”: estimated age of the person being verified “gender”: estimated gender of the person being verified。0: male; 1:female “age_image_ref1”: estimated age of reference face image ref1 “gender_image_ref1”: estimated gender of reference face image ref1。0: male; 1:female
	verify_risk_info	Json	Comparison risk warning results: "verify_info_tags"：Json type；indicates the risk type of image comparison Comparison risk tag Explanation is_gender_risk string type, 0: indicates that the gender prediction of the image is consistent with the image_ref1; 1: indicates that the gender prediction of the image is inconsistent with the image_ref1; is_age_risk string type, 0: indicates that the age prediction difference between the image and the image_ref1 is not significant; 1: indicates that the age prediction difference between the image and the image_ref1 is significant (usually referring to an age gap of 10 years or more, depending on the threshold setting) Note：The parameter is returned only when "Comparison risk detection" is turned on in the console compare scenario.
	face	Json	When using the "rawimage" method, the attributes of the verification image are returned, including: "quality"：Face quality. "quality_threshold"：Face quality threshold. "rect"：Face coordinate points in JSON format. "orientation"：Face orientation.

# Sample Response

Example of correct request for return

{
   "request_id":"1531397565,39b19451-393c-4fc4-8fae-6dc74b2b00d7",
   "biz_no":"",
   "time_used":1448,
   "result_code":1000,
   "result_message":"SUCCESS",
   "verification":{
      "ref1":{
         "confidence":86.63057,
         "thresholds":{
            "1e-3":62.168713,
            "1e-4":69.31534
            "1e-5":74.39926,
            "1e-6":78.038055
         }
      }
   },
   "face":{
      "quality":38.221,
      "quality_threshold":30.1,
      "rect":{
         "left":0.18,
         "top":0.18,
         "width":0.596,
         "height":0.596
       },
      "orientation":90
   },
  "visual_attributes":{
      "age":20,
      "gender":0,
      "age_image_ref1":38,
      "gender_image_ref":0,
   },
  "verify_risk_info":{
      "verify_info_tags":{
         "is_gender_risk":0,
         "is_age_risk":1,
       }
   } 
}

Example of wrong request

{
    "error": "AUTHORIZATION_ERROR: INVALID_SIGN"
}

# Comparison table of result_code & result_message

result_code	result_message	Explanation of meaning	Whether to charge
1000	SUCCESS	The person in the image to be compared is the same person as in the other images.	yes
2000	PASS_LIVING_NOT_THE_SAME	The person in the image to be compared was not the same person as in at least one of the other images after verification.	yes

# Error Message

Status Code	Error Message	Description
400	MISSING_ARGUMENTS:<key>	One mandatory parameter is missing.
400	IMAGE_ERROR_UNSUPPORTED_FORMAT:<param>	Corresponding image of <param> cannot be analyzed, It may not be an image file or relevant data is damaged. <param>may be image_ref1 or image. Attention: There will only be one item for <param>, which is the first name that meets the condition.
400	NO_FACE_FOUND:<param>	Indicate that no face was found in the uploaded images of "image_ref" and "image".
400	INVALID_IMAGE_SIZE:<param>	The uploaded image is too large, that is, the length or width of the pixel size exceeds 4096 pixels. <param> may be image_ref1 or image. Attention: There will only be one item for <param>, which is the first name that meets the condition.
400	LOW_QUALITY	The image quality is too low.
400	MULTIPLE_FACES	There are multiple faces in the image.
400	KEY_NOT_FOUND	encryption_type is enabled for encryption, but encryption public key and decryption private key are not configured.
403	AUTHENTICATION_ERROR	Invalid signature.
403	AUTHORIZATION_ERROR:<reason>	The API key has been deactivated, the call limit has been exceeded, there is no permission to access this API, or there is no permission to access this API in the current manner. Possible values for  <reason>: API_KEY_BE_DISCONTINUED：The API key has been deactivated. IP_NOT_ALLOWED：The accessing IP is not allowed (reserved design). LIMIT_REACHED：The call limit for this API with the given API key has been reached. Only applicable for test keys. MORE_RETRY_TIMES：The maximum retry attempts for comparison have been reached. DENIED：There is no permission to call the current API. EXPIRED_SIGN：The signature has expired. INVALID_SIGN：The signature is invalid. Please prepare handling solutions for other possible error codes as well.
403	CONCURRENCY_LIMIT_EXCEEDED	The concurrent number of requests has exceeded the limit.
404	API_NOT_FOUND	The API called does not exist.
413	Request Entity Too Large	The request sent by the customer exceeds the 10MB limit. The return for this error will be plain text, not in "json" format.
500	INTERNAL_ERROR	Internal server error. Please retry your request when such errors occur. If you continue to experience this issue, please contact FinAuth customer support or your business representative for assistance.