ID Verification:FACE_IDU_MIN

Parameter

Type

Required

Description

Example

ProductCode

String

Yes

The product solution identifier. Set the value to FACE_IDU_MIN.

FACE_IDU_MIN

MerchantBizId

String

Yes

A unique business identifier for the merchant, used to identify and troubleshoot issues. The identifier is a 32-character string of letters and numbers. The server-side does not validate the uniqueness of this ID. The merchant must ensure that the ID is unique.

e0c34a77f5ac40a5aa5e6ed20c35****

MerchantUserId

String

Yes

A custom user identifier, or another recognizable user identifier, such as a mobile phone number or email address. We recommend that you desensitize or hash this field.

123456789

SourceFacePicture

String

Yes (choose one of the three SourceFace parameters)

The source face image for liveness detection, encoded in Base64.

base64

SourceFacePictureUrl

String

A publicly accessible HTTP or HTTPS URL of the source face image.

https://***face1.jpeg

SourceFacePictureFile

String

The file stream of the source face image.

For integration details, see Advanced feature for file uploads.

FaceQualityCheck

String

No

N

FaceAttributeCheck

String

No

N

VerifyModel

String

Yes

[Product settings] The verification mode:

• 1 validation mode: 1:1 verification (default)

• 0 retrieve mode: 1-to-N retrieval

• 2Comprehensive mode: 1:1 verification + 1:N retrieval

0

TargetFacePicture

String

Required if VerifyModel is 1 or 2.

[Product settings - 1:1 validation] The Base64-encoded string of the trusted target face image for 1:1 comparison.

base64

TargetFacePictureUrl

String

[Product settings - 1:1 validation] The URL of the face image. The URL must be a publicly accessible HTTP or HTTPS link.

https://***face2.jpeg

TargetFacePictureFile

String

[Product settings - 1:1 validation] The file stream of the face image.

For integration details, see Advanced feature for file uploads.

FaceGroupCodes

String

Required if VerifyModel is 0 or 2.

[Product settings - 1:N retrieval] The codes of face groups for 1:N retrieval. You can obtain the code when you create a face group in the ID Verification console. You can specify up to 10 face groups at a time. Use commas (,) to separate multiple face group codes.

sg*****xta,s*****uk3j

ReturnFaces

String

Required if VerifyModel is 0 or 2.

[Product settings - 1:N retrieval] The number of matching faces to return when multiple faces exceed the match threshold. Default: 1. Maximum: 5.

1

AutoRegistration

String

Required if VerifyModel is 0 or 2.

[Product settings - 1:N retrieval] Specifies whether to automatically register the face to a face group after successful verification:

• 0: Enable auto-registration.

• 1: Disable auto-registration (default).

0

FaceRegisterGroupCode

String

Required if VerifyModel is 0 or 2 and AutoRegistration is 0.

[Product settings - 1:N retrieval] The code of the target face group for auto-registration.

sg*****xta

UpdateFaceIfUserExists

String

Required if VerifyModel is 0 or 2.

[Product Solution Configuration - 1:N Search] If the MerchantUserId already exists during auto-registration, overwrite the existing face with the new one:

• Y: Overwrite.

• N: Do not overwrite (default). The service returns a "UserId already exists" error.

N

Verification mode

VerifyModel value

Core logic

Use case

Key parameters

Auto-registration condition

Validation mode (default)

1

liveness detection + 1:1 validation

Logins, account recovery, and sensitive action confirmations.

TargetFacePicture, TargetFacePictureUrl, or TargetFacePictureFile (Choose one of the three to specify the target face)

Not applicable

Retrieve mode

0

liveness detection + 1:N retrieval

Preventing duplicate registrations for new users and enforcing one account per person.

FaceGroupCodes (Specifies the face groups to search).
ReturnFaces (Optional. Specifies the number of faces to return that exceed the matching threshold.)

Liveness detection passes, and 1:N retrieval finds no match.

Comprehensive mode

2

liveness detection + 1:1 validation + 1:N retrieval

New user registration that requires both identity confirmation and duplicate checking.

Requires all key parameters for both validation mode (value 1) and retrieve mode (value 0).

Liveness detection passes, 1:1 validation passes, and 1:N retrieval finds no match.

Parameter

Type

Description

Example

HTTP status code

Integer

The HTTP status code.

200

HTTP Body

RequestId

String

The request ID.

130A2C10-B9EE-4D84-88E3-5384FF0****

Code

String

The return code. For more information, see Server-side HTTP status codes.

Success

Message

String

A description of the return code.

success

Result.TransactionId

String

The unique identifier of the verification request.

4ab0b***cbde97

Result.SubCode

String

The sub-code for the verification result. For more information, see Result.SubCode reference.

200

Result.FacePassed

String

The final verification result. Valid values:

• Y: Passed

• N: Failed

Y

Result.FaceAttack

String

Indicates whether a liveness attack was detected. Valid values:

• Y: Yes

• N: No

N

Result.FaceAttributeInfo

String

{
    "gender": 1,
    "glasses": 0,
    "hat": 1,
    "mask": 1,
    "tattoo": 0,
    "smoking": 0,
    "others": 1,
    "env": "office",
    "expression": 1,
    "age": 16
}

Result.ExtFaceInfo

Object

Information about the liveness detection result. For the JSON format, see the example on the right. For more information, see Result.ExtFaceInfo.

{
  "FaceQualityScore": 66.3,
  "OcclusionScore": 100,
  "SharpnessScore": 70.3,
  "KaOcclusionScore": 80,
  "IlluminationScore": 90.79
}

Result.FaceComparisonScore

Double

The face comparison result is returned when VerifyModel=1/2. The comparison score ranges from 0 to 100. The default system threshold is 90. You can also customize the decision based on your business requirements.

98

Result.DuplicateFace

String

Returns the duplicate face search result when VerifyModel is 0 or 2 and a similar face is found.

The returned fields are defined as follows:

• faceGroupCode: The code of the face group that contains the similar face.

• faceId: The ID of the similar face.

• merchantUserId: The unique user ID for a similar face.

• score: The similarity score of the face.

[
  {
    "faceGroupCode": "sg7****uzt",
    "faceId": "f5a921*******9e792ec84c8f0ca592a",
    "merchantUserId": "face0005",
    "score": 93.26
  }
]

Result.FaceRegistrationResult

Integer

Face registration result (returned when VerifyModel=0/2):

• 0: Registration failed due to an issue with the face image.

• 1: Registration successful.

• 2: Registration failed because the auto-registration conditions were not met.

• 3: Registration failed because the user already exists.

• 4: Registration successful, and the face image is updated successfully (This occurs when an entry meets the conditions for automatic registration, but has a duplicate MerchantUserId and UpdateFaceIfUserExists is set to Y).

1

Result.FaceRegistrationId

String

The ID of the registered face, which is returned when VerifyModel=0/2, AutoRegistration=0, and the registration is successful.

9e792******a592a

Name

Type

Description

Example

FaceQualityScore

Double

The liveness face quality score. Valid values: 0 to 100. A higher value indicates better quality.

88.62

OcclusionScore

Double

A quality assessment sub-dimension: the occlusion score. Valid values: 0 to 100. A higher value indicates better quality.

99.99

KaOcclusionScore

Double

A quality assessment sub-dimension: the key area occlusion score. Valid values: 0 to 100. A higher value indicates better quality.

100

IlluminationScore

Double

A quality assessment sub-dimension: the illumination score. Valid values: 0 to 100. A higher value indicates better quality.

97.43

SharpnessScore

Double

A quality assessment sub-dimension: the image sharpness score. Valid values: 0 to 100. A higher value indicates better quality.

60.78

Sub-code

Billable

Description and suggestion

200

Yes

Verification passed.

204

Yes

[1:1 verification result] This may be because the user is not the same person or the face image quality is poor.

205

Yes

[Liveness result] Liveness risk detected, indicating a potential liveness attack.

233

Yes

1:N Search Result: Similar faces detected. Use the information in Result.ExtFaceInfo.duplicateFace to handle the risks of duplicate registration or identity spoofing.