# APP-Verify

# Version

3.0.0

# Description

Upload all the data of FaceID MegLiveStill SDK, and get the result of liveness detection, face comparing and anti-spoofing attack.

Note：

Only FaceID MegLiveStill SDK Version 3.0 or above is supported.

# Request URL

Singapore: POST https://api-sgp.megvii.com/faceid/v3/sdk/verify
Indonesia:  POST https://api-idn.megvii.com/faceid/v3/sdk/verify

Note:

Use HTTPS method in a production environment. Please avoid using HTTP methods as it is an unsecure link which remains security risks. If HTTP methods are used in a production environment, service reliability will not be guaranteed.

# Permission

The FaceID Web APIs can only be called when accessing FaceID product first. Please contact our sales for the accessing process.

# Parameters

Required/Optional	Parameter	Type	Description
Required/Optional	Parameter	Type	Description
Required	sign	String	The signature of the user calling the API. For the specific signature generation method, please refer to the "App-Authentication" document.
Required	sign_version	String	Signature algorithm version, please pass hmac_sha1.
Required	biz_token	String	The biz_token generated from ”App-GetBizToken“ API.
Required	meglive_data	File	The parameter is required if the liveness_type= meglive or liveness_type=still. It needs to upload datas produced by FaceID MegLiveStill SDK Version 3.0 or above, including datas from liveness detection and face detection process. Please directly pass the API, do not make any adjustment to the data packet. The parameter is optional if the liveness_type =raw_image. The comparison result will be returned.

# Return Values

Field

Type

Description

request_id

String

Serial number of API calls.

biz_no

String

Business serial number.

time_used

int

Time that the whole request takes. Unit: millisecond. This field must be returned.

result_code

int

Indicate the status code of the comparison result. You can get the specific result and reason according to result_code and result_message.

status code 1000 Series: Comparison finished, verification pass. The result is that two faces are from the same person.
status code 2000 Series: Comparison finished, liveness verification pass. The result is that two faces are not from the same person according to at least one of authority data or reference photo.
status code 4000 Series: the corresponding result of verification
status code 4100 Series: liveness jugement failed
status code 4200 Series: SDK liveness photo capture failed
Please prepare reservation schemes for other results. We will instantly increase error codes.

Note: the return of status code 9000 has priority over other error codes.

result_message

String

Get the specific reason according the string, please refer to comparison table of result_code & result_message

verification

Json

This filed will be returned when verbose=1, result status code=1000, 2000 Series.

ref1: the comparison result of liveness photo and image_ref1
- "confidence": Float type, value between [ 0,100 ]. Higher confidence indicates higher possibility that two faces belong to same person.
- "thresholds": For reference. Object type, including three fields of Float type, value between [ 0,100 ]：
  - 1e-3: confidence threshold at the 0.1% error rate
  - 1e-4: confidence threshold at the 0.01% error rate
  - 1e-5: confidence threshold at the 0.001% error rate
  - 1e-6: confidence threshold at the 0.0001% error rate
ref2: the comparison result of liveness photo and image_ref2 (only returns when get_biz_token includes image_ref2, the same result as ref1 field）

images

Json

A list of images. The corresponding image field will be added later according to captured images.

image_best: liveness image, base64 encoding。

attack_result

Json

The string will only be returned when the status code is not 4200.

result: int, 0: real face, 1: fake face

score: float, value[0,1], indicates confidence of attack

threshold: float, indicates threshold of attack judgement

risk_info

Json

Device Risk Detection Results.

Detection Logic Specification: The get_biz_token interface enables ‌Device Risk Detection‌ via the device_risk parameter. If this parameter is not enabled, the interface will return null.

"device_info_level": string type, Indicates the device risk level

0: indicates no risk detected
1: indicates medium risk (business verification is recommended)
2: indicates high riskIt will be blocked directly. If "device_risk=1" turns on device risk detection and performs high-risk blocking, such risk requests will be blocked)

"device_info_tags"：Json type; indicating the type of device risk

Each risk tag corresponding to face attack has a binary value of 0/1: returns 1 if the corresponding tag risk is detected, otherwise returns 0
A single request may match multiple device risk tags simultaneously
iOS and Android return different sets of device risk tags: tags that are marked for specific system (iOS only / Android only) will only be returned by devices of the corresponding system; unmarked tags will be returned by both systems
A small number of special tags (e.g. is_anomalous_behavior) will only be returned after you contact the FinAuth technical support team to enable the corresponding policy

Device_info_tags	Specification
is_root	suspected device is rooted
is_hook	suspected device is hooked
is_injection	suspected device is injected
is_virtual_environment	suspected device is running in a virtual environment
is_double_open	suspected device is double-open (only Android device detection)
is_group_control_risk	suspected group control device risk (only Android device detection)
is_non_system_user	suspected non-system user (only Android device detection)
is_location_spoofed	suspected fake location (only Android device detection)
is_using_vpn	suspected VPN software is used
is_using_agent	uspected agent software is used (only IOS device detection)
is_usb_inserted	suspected device is in USB plugged in state (only Android device detection)
is_screen_casting	suspected device is in screen casting state (only IOS device detection)
is_anomalous_behavior	suspected device has abnormal behavior in recent identification
is_other_risks	other device risks

Note："device_info_tags"will be added, modified, deleted, and expanded as the business develops. It is recommended to upgrade to the latest version of the SDK to detect more device risk tags..

video_key

String

Decryption Key, used to retrieve the videos and photos saved on the SDK side.

error

String

This string will not be returned unless request fails , or empty else. For more details, please see the following section on error message.

visual_attributes

Json

“age”: estimated age of the person being verified

“gender”: estimated gender of the person being verified

“age_image_ref1”: estimated age of reference face image ref1

“gender_image_ref1”: estimated gender of reference face image ref1

Note: This parameter is returned when the get_biztoken interface turns on verification risk detection (verify_risk_detect=1).

verify_risk_info

Json

Comparison risk warning results:

"verify_info_tags": Json type; indicates the risk type of liveness image comparison

“is_gender_risk”:string type, 0: indicates that the gender of the liveness image and the comparison image is consistent; 1: indicates that the gender of the liveness image and the comparison image is inconsistent; (gender comparison between the liveness image and the ref1 image)

“is_age_risk”: string type, 0: indicates that the age difference between the liveness image and the comparison image is not significant; 1: indicates that the age difference between the liveness image and the comparison image is significant (usually referring to an age gap of 10 years or more, depending on the threshold setting. The age comparison is between the liveness image and the ref1 image)

Note: This parameter is returned when the get_biztoken interface turns on verification risk detection (verify_risk_detect=1).

# Sample Response

# Sample response when request has succeeded:

{
   "time_used":1448,
   "verification":{
      "ref1":{
         "confidence":86.63057,
         "thresholds":{
            "1e-3":51.244865,
            "1e-5":75.758,
            "1e-4":58.77636,
            "1e-6":79.041
         }
      }
   },
   "attack_result":{
      "score":0.26,
      "threshold":0.5,
      "result":False
   },
   "risk_info":{ 
      "device_info_level": "2", 
      "device_info_tags": {"is_root":0,"is_hook":1,"is_injection":1,"is_virtual_environment":1}
   },
   "request_id":"1531397565,39b19451-393c-4fc4-8fae-6dc74b2b00d7",
   "images":{
      "image_best":"xxxxxxxxxxx"
   },
   "biz_no":"",
   "result_message":"SUCCESS",
   "result_code":1000
}

# Sample response when request has failed:

{
    "error": "AUTHORIZATION_ERROR: INVALID_SIGN"
}

# Comparison table of result_code & result_message

Result_code	Result_message	Description	Cost
Result_code	Result_message	Description	Cost
1000	SUCCESS	Portrait to be compared and authority data, or reference photo, are from the same person.	Yes
2000	PASS_LIVING_NOT_THE_SAME	Liveness detection passed. As for the verification process, the two faces are not from the same person according to at least one of authority data or reference photo.	Yes
4100	FAIL_LIVING_FACE_ATTACK	Failed to pass liveness verification. Possible reason: fake face attack.	No
4100	VIDEO_LACK_FRAMES	The obtained liveness data fault, please retry with another phone.	No
4100	FAIL_EYES_CLOSE_DETECTION	Failed to pass eye close detection	No
4100	DEVICE_RISK	Device attack detected. Failed to pass liveness detection.	No
4200	BIZ_TOKEN_DENIED	Invalid biz_token	No
4200	AUTHENTICATION_FAIL	Authentication failed	No
4200	MOBILE_PHONE_NOT_SUPPORT	Phone not supported	No
4200	SDK_TOO_OLD	SDK version is too old	No
4200	MOBILE_PHONE_NO_AUTHORITY	No authority (motion sensor, storage, camera)	No
4200	USER_CANCELLATION	Liveness verification failed. Possible reasons: user cancellation, verification process timeout, etc.	No
4200	USER_TIMEOUT	Liveness verification failed. Possible reasons: user cancellation, verification process timeout, etc.	No
4200	VERIFICATION_FAILURE	Liveness verification failed. Possible reasons: user cancellation, verification process timeout, etc.	No
4200	UNDETECTED_FACE	Liveness verification failed. Possible reasons: user cancellation, verification process timeout, etc.	No
4200	ACTION_ERROR	Liveness verification failed. Possible reasons: user cancellation, verification process timeout, etc.	No

# ERROR Message

Status Code	Error Message	Description
Status Code	Error Message	Description
400	IMAGE_ERROR_UNSUPPORTED_FORMAT:<param>	The image which <param> indicates can not be resolved. The file format may not be supported or the file is damaged. <param> is one of image_ref1 and image_ref2. Please note that <param> has only one item, that is, the first one that satisfies the condition.
400	MISSING_ARGUMENTS:<key>	Some required arguments missed.
400	BAD_ARGUMENTS:<key>	Error while parsing some arguments. This error may be caused by illegal type or length of argument.
400	NO_FACE_FOUND:<param>	No face is detected in image_ref.
400	INVALID_IMAGE_SIZE:<param>	The size of uploaded image is too large, which is over the 4096x4096 pixel limit. <param> is one of image_ref1 and image_ref2. Please note that <param> has only one item, that is, the first one that satisfies the condition.
400	MEGLIVE_DATA_ERROR	Failed to parse meglive_data packet. Please pass the original data packet directly to the API. Any adjustment to the data packet will cause problems.
400	MEGLIVE_DATA_BIZ_TOKEN_NOT_MATCH	The biz_token of meglive_data is not consistent with biz_token imported.
403	AUTHORIZATION_ERROR:<reason>	api_key is discontinued, rate limit has been exceeded, no permission to call the API, or no permission to call the API according to current method. Values of <reason> are: API_KEY_BE_DISCONTINUED：api_key is discontinued IP_NOT_ALLOWED：IP is not allowed LIMIT_REACHED：the limit of API calls for the api_key(only for test api_key) has been exceeded MORE_RETRY_TIMES：comparison retry limit is reached NO_VERIFY_PERMISSION：no permission for non-data-source comparison, but still calls NO_DATA_SOURCE_PERMISSION：no permission for data-source comparison, but still calls DENIED：no permission to call the API EXPIRED_SIGN：signature is expired INVALID_SIGN：invalid signature Please prepare reservation schemes for other results
429	CONCURRENCY_LIMIT_EXCEEDED	The rate limit for this API Key has been exceeded.
404	API_NOT_FOUND	Requested API can not be found.
413	Request Entity Too Large	The request entity has exceeded the limit 10MB. This error message will be returned in plain text, instead of JSON.
500	INTERNAL_ERROR	Internal error. Please retry the request. If this error keeps occurring, please contact our support team.