ID Verification:InitializeV2

Integration method

Use case

API response

Parameters

App SDK

For verifying users in a native Android or iOS app.

TransactionId, Protocol

Common parameters + App SDK-specific parameters

Web SDK

For verifying users on a mobile H5 page, an embedded H5 page in an app, or a PC browser.

TransactionId, TransactionUrl, Protocol

Common parameters + Web SDK-specific parameters

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

Required

Description

Example

ProductCode

String

Yes

The product code. Set the value to FACE_IDU.

FACE_IDU

SceneCode

String

No

A custom ID for the authentication scenario. Use this ID to retrieve records from the console. The ID can be a 10-character string that consists of letters, numbers, and underscores.

1234567890

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****

MetaInfo

String

Yes

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

CallbackUrl

String

No

CallbackToken

String

No

A custom security token for the merchant. Once set, this token is returned unchanged with the CallbackUrl for anti-replay and tamper-proofing verification.

NMjvQanQgplBSaEI0sL********

SecurityLevel

String

No

02

Model

String

No

Liveness detection type:

• SILENT: Silent (Supported by Naive SDK 1.3.6 and later)

• LIVENESS: Blink (default)

• PHOTINUS_LIVENESS: Blink and color flash (Not supported in PC mode)

• TEMPLATE: Custom liveness detection action (Not supported by Web SDK. Supported by Naive SDK 1.3.6 and later.)

PHOTINUS_LIVENESS

DocVideo

String

No

N

FaceAttributeCheck

String

No

N

VerifyModel

String

No

[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 when VerifyModel is 1 or 2. Choose one of the three upload methods.

[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://***face1.jpeg

TargetFacePictureFile

InputStream

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

See Special Scenarios: Configuring the Advance Interface for File Uploads.

FaceGroupCodes

String

Required when 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

Optional when 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

Optional when 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 when 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

Optional when 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

ShowGuidePage

String

No

UI configuration: Show guide page:

• 1: Show (default)

• 0: Do not show

PC mode does not support this configuration.

Supported in Native SDK version 1.4.0 and above.

1

Parameter

Type

Required

Description

Example

AppQualityCheck

String

No

[Face Scan Configuration] Specifies whether to enable strict face quality detection.

• Y: Enabled (default)

• N: Disabled

Supported only in Native SDK v1.2.5 and later. The face quality detection module must be integrated.

N

TemplateConfig

String

Conditional

01,02,07

TemplateType

String

Conditional

Seq

NeedMultiFaceCheck

String

No

Y

Parameter

Type

Required

Description

Example

LanguageConfig

String

No

{
  "languageContent": {****},
  "ocrResultContent": {****},
  "supportedLanguage": [****],
  "titleTranslate": {****},
}

StyleConfig

String

No

{
  "guidepage:": {****}, 
  "ocrPage": {****},
  "ocrResultPage": [****],
  "facePage": {****},
}

ReturnUrl

String

Conditional

The URL to redirect to after authentication. This is optional for the iframe embedded pattern. Provide this URL for page redirect scenarios that do not use an iframe.

https://www.alibabacloud.com

ProcedurePriority

String

No

Specifies whether to display a fallback method when a compatibility issue occurs during mobile H5 authentication.

• url: Supports fallback. The page displays the authentication URL. Users can copy the URL and open it in a different browser to continue authentication. (Default)

• keep: Does not support fallback. An error reason is returned, and the authentication flow ends. This option is not supported on PCs. Recommended for webpages embedded in an app.

url

Field

App SDK

Web SDK

Note

RequestId / Code / Message

Yes

Yes

General response information.

Result.TransactionId

Yes

Yes

This is the unique identifier for the authentication flow, a field for billing statistics, and a request parameter for the CheckResult operation. Attach this identifier to the merchant business ID and store it only on the server-side.

Result.Protocol

Yes

Yes

Standard authentication and encryption protocol. Pass this through to the client SDK. The Web SDK requires this field for iframe embedding.

Result.TransactionUrl

No

Yes

The Web SDK authentication URL. After authentication, it redirects to the ReturnUrl. This URL cannot be modified and can be accessed only once. You must complete the authentication within 30 minutes of obtaining the URL or TransactionId.