All Products
Search

This Product

    ID Verification:InitializeV2

    Document Center

    ID Verification:InitializeV2

    Last Updated:Jul 10, 2026

    Call the InitializeV2 operation to start an eKYC verification session and obtain a transactionId for subsequent API calls.

    Initiate a verification request

    • API operation: InitializeV2

    • Request method: HTTPS POST

    • Description: Before you start an eKYC verification flow, call this API operation to obtain a transactionId. This ID is used to link all API operations in the verification request.

    • QPS limit: Each API has a dedicated QPS limit. For details, see QPS limits of ID Verification server-side APIs.

    • Service endpoints:

      Note

      • Benefits of internal network access: An internal network enables private communication between Alibaba Cloud services in the same region. If your application server is also in the same region, use the internal network endpoint to access the ID Verification service for a more secure and stable connection. 

      • Optimization for overseas access: Network conditions outside the Chinese mainland can be complex. To reduce latency and minimize request failures, optimize your integration by following the best practices in Server-side Network Latency Analysis and Optimization.

      China (Hong Kong)

      • Public endpoint: cloudauth-intl.cn-hongkong.aliyuncs.com

      • Internal endpoint: cloudauth-intl-vpc.cn-hongkong.aliyuncs.com

    Online debugging and integration

    Note

    Before you debug or integrate, read the Use OpenAPI guide to understand how to call APIs on the OpenAPI platform and how to obtain the SDK.

    You can run this API operation directly in OpenAPI Explorer to perform debugging and generate SDK code examples for this API operation.

    Request parameters

    Name

    Type

    Required

    Description

    Example

    ProductCode

    String

    Yes

    The product solution to integrate. Valid value:

    eKYC: With the eKYC solution, your users must complete the certificate detection and liveness detection flow.

    eKYC

    SceneCode

    String

    No

    A custom verification scenario ID. You can use this ID to query related records in the console. The ID can be up to 10 characters in length and can contain letters, digits, and underscores (_).

    1234567890

    MerchantBizId

    String

    Yes

    A custom unique business identifier. Use it to locate and troubleshoot issues later. The identifier can be up to 32 characters in length and can contain letters and digits. Make sure that the identifier is unique.

    Note

    Alibaba Cloud servers do not check the uniqueness of this value. For better tracking, make sure that the value is unique.

    e0c34a77f5ac40a5aa5e6ed20c35****

    MetaInfo

    String

    Yes

    The MetaInfo parameter is required when you call the initialization API. If you have not integrated the client software development kit (SDK), you must provide a static value for this parameter. You must accurately specify the deviceType field and leave the other fields unspecified.

    Example code:

    {
  "deviceType": "h5"
}

    deviceType valid values:

    • Native Android app: android

    • Native iOS app: ios

    • Embedded H5 page: h5

    • PC web page: web

    Important

    Use the authentication SDK to obtain MetaInfo. This provides more accurate and detailed client information for scenarios such as authentication URL delivery, log investigation, and security verification. If you provide a static value for MetaInfo, ensure that deviceType matches the actual environment. An incorrect value will cause authentication URL delivery to fail.

    {
  "zimVer": "3.0.0",
  "appVersion": "1",
  "bioMetaInfo": "4.1.0:1150****,0",
  "appName": "com.aliyun.antcloudauth",
  "deviceType": "h5",
  "osVersion": "iOS 10.3.2",
  "apdidToken": "",
  "deviceModel": "iPhone9,1"
}

    MerchantUserId

    String

    Yes

    A custom user ID or another identifier for a specific user, such as a mobile phone number or an email address. We strongly recommend that you desensitize the value in advance, for example, by hashing it.

    123456789

    IdSpoof

    String

    No

    Specifies whether to enable the anti-spoofing detection feature for documents:

    • Y: Enable

    • N: Disable (Default)

    Y

    DocType

    String

    Yes

    The document type. It is uniquely identified by an 8-digit combination. For more information, see the table below.

    01000000

    Authorize

    String

    No

    Specifies whether to enable identity verification against an official database:

    • T: Enable

    • F: Disable (Default)

    Note

    This feature is currently available only for second-generation resident ID cards of the Chinese mainland.

    F

    SecurityLevel

    String

    No

    Specifies the security level for the verification process. Valid values:

    • 01: normal mode. This mode is suitable for low-risk scenarios with restricted device information collection.

    • 02 (default): secure mode.

      Note

      • The secure mode uses the face guard module in the SDK to assess device environment security using device information. This enhances protection against injection attacks. We recommend enabling this mode.

      • During development and testing, the face guard module might flag a test device's environment as a risk. This can cause the verification to fail with Subcode 206. To improve testing efficiency, we recommend setting the mode to "01 normal mode". For production, switch to "02 secure mode" to ensure enhanced security.

    02

    IdThreshold

    String

    No

    Sets the mode for the OCR quality check. Valid values are:

    • 1: strict mode

    • 2: loose mode

    • 3 (default): Disables the quality check.

    3

    Model

    String

    No

    Specifies the type of liveness detection to perform. Valid values:

    • SILENT: Silent liveness detection.

    • LIVENESS: Liveness detection that uses a blinking action (default).

    • PHOTINUS_LIVENESS: Liveness detection that uses a blinking action and a color pattern (not supported on PC).

    Note

    For supported SDK versions, see Client SDK release notes.

    PHOTINUS_LIVENESS

    DocVideo

    String

    No

    Specifies whether to store an evidence video. Valid values:

    • N (default): The evidence video is not stored.

    • Y: Captures a 1- to 2-second evidence video of the user's face during verification. The query operation returns the video.

    Note

    The system may discard large video files during network instability to prioritize the transmission of essential verification images.

    N

    CallbackUrl

    String

    No

    The callback URL for receiving verification results. The callback request uses the GET method by default, and the URL must start with https. After verification completes, the platform invokes this URL and automatically appends the following parameters:

    • transactionId

    • passed

    • subcode

    Warning

    • The service validates this URL for accessibility before processing the API call. If the provided URL is not accessible from the public network, the service returns a 400 error.

    • The callback is triggered immediately after the verification process completes but may be delayed by network conditions. We recommend first handling the completion notification on the client and then calling the query API to retrieve detailed verification results.

    https://www.aliyun.com?callbackToken=100000****&transactionId=shaxxxx&passed=Y&subCode=200

    CallbackToken

    String

    No

    A security token that you generate. It is used for anti-replay and tamper-proofing checks.

    If you set this parameter, the CallbackToken field is included in the CallbackUrl callback.

    NMjvQanQgplBSaEI0sL86WnQplB

    AppQualityCheck

    String

    No

    Specifies whether to enable strict quality detection for faces.

    • Y: Enable (Default)

    • N: Disable

    Important

    • This configuration requires support from the client-side SDK. If you enable this feature, but the client-side SDK does not have the face quality detection module integrated, this configuration is treated as disabled.

    • The client-side SDK must be version 1.2.5 or later.

    N

    DocPageConfig

    String

    No

    A JSON string array.

    OCR_ID_BACK: Collects the back page.

    Note

    Currently, this is supported only for Chinese mainland ID cards.

    OCR_ID_BACK

    ShowGuidePage

    String

    No

    Specifies whether to show the guide page:

    • 1 (Default): Show

    • 0: Do not show

    1

    DocScanMode

    String

    No

    The OCR document scanning mode:

    • shoot (Default): Take a photo

    • scan: scan

    • auto: Automatic switchover between photo and scan

    shoot

    Document types

    DocType

    Document

    01000000

    Global passport

    00000006

    Hong Kong identity card (2003 version)

    00000008

    Hong Kong identity card (2018 version)

    00000007

    Exit-Entry Permit for Travelling to and from Hong Kong and Macao

    00000009

    Mainland Travel Permits for Hong Kong and Macao Residents

    000000011

    Macao identity card

    000000012

    Mainland Travel Permit for Taiwan Residents

    00000001

    Second-generation resident ID card of the Chinese mainland

    Returned data

    Name

    Type

    Description

    Example

    HTTP Status Code

    Integer

    The HTTP status code.

    200

    HTTP Body

    RequestId

    String

    The request ID.

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

    Code

    String

    Return code: For more information, see Server-side HTTP status codes.

    Success

    Message

    String

    A detailed description of the response code.

    success

    Result.TransactionId

    String

    The unique identifier for the authentication process. This field is used for billing statistics and to call the CheckResult API.

    Important

    • If an error occurs during the request, such as an invalid parameter, TransactionId is not returned.

    • Associate the TransactionId with your business process ID and store it on the server side. When calling the CheckResult API, retrieve this ID from your server-side storage to query the result.

    • You must complete the authentication process within 30 minutes of obtaining the TransactionId or TransactionUrl. After this period, the ID expires and cannot be used for authentication.

    hksb7ba1b28130d24e015d6********

    Result.Protocol

    String

    The encrypted string for the standard authentication protocol.

    Passing this parameter to the client SDK reduces network interactions and supports dynamic network switching, which improves the user experience.

    hksb7ba1b28130d24e015d*********