All Products
Search

This Product

    ID Verification:InitializeV2

    Document Center

    ID Verification:InitializeV2

    Last Updated:Aug 24, 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 its own QPS limit. For more information, see QPS limits of ID Verification server-side APIs.

    • Service endpoints:

      Note

      • Benefits of internal network access: An internal network is a private communication network connecting Alibaba Cloud products within the same region. If your application server is deployed in the same region, use the internal endpoint to access the ID Verification service for enhanced security and stability.

      • Optimizing overseas access: Overseas network environments can be complex. Refer to Optimize server network latency to tune your integration and reduce network latency and request failures.

      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 debugging and integration, read the Use OpenAPI document to learn how to call APIs on the OpenAPI platform and 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

    Client environment information. Generate this information using the corresponding SDK. If you create it yourself, you must at least pass the correct deviceType value.

    Example code:

    {
  "deviceType": "h5"
}

    Valid values for deviceType:

    • 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 issuance, log investigation, and security checks. If you create a static MetaInfo value, make sure that `deviceType` matches the actual environment. An incorrect value will cause errors when the authentication URL is issued.

    {
  "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 (Default)

    • N: Disable

    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

    The security level. Valid values:

    • 01: Normal mode. Recommended for test environments to improve testing efficiency.

    • 02: Secure mode (default). Strongly recommended for production environments.

    02

    IdThreshold

    String

    No

    OCR card quality check:

    • 1: Enable strict mode

    • 2: Enable loose mode (default)

    • 3: Disable

    3

    Model

    String

    No

    The type of liveness detection:

    • SILENT: Silent liveness detection.

    • LIVENESS: Blink-based detection (Default).

    • PHOTINUS_LIVENESS: Blink-based detection and color-based liveness detection (Not supported on PC).

    Note

    For SDK versions that support integration, see client SDK release notes.

    PHOTINUS_LIVENESS

    DocVideo

    String

    No

    Specifies whether to capture a 1- to 2-second evidence video during the face verification process. Valid values:

    • Y: Yes

    • N (default): No

    Video files are large. On unstable networks, the system may discard the video to prioritize uploading essential images.

    To get the video URL, check the Result.ExtFaceInfo.docVideoUrl parameter in the CheckResult response.

    N

    CallbackUrl

    String

    No

    The callback URL for the authentication result. This URL must start with https. The platform makes a GET request to this URL and appends the transactionId, passed, and subcode parameters.

    The platform returns an HTTP 400 error if the URL is not publicly accessible.

    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

    A unique identifier for the authentication flow. This identifier is used for billing and is required for calls to the CheckResult API.

    Important

    • The init API does not return a TransactionId if the request fails, for example, due to an invalid parameter.

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

    • The TransactionId or TransactionUrl is valid for 30 minutes. You must complete the authentication within this period, after which the ID expires.

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