All Products
Search

This Product

    ID Verification:Initialize

    Document Center

    ID Verification:Initialize

    Last Updated:Mar 24, 2026

    This topic describes how to call the Initialize operation to initiate an electronic Know Your Customer (eKYC) request.

    Initiate verification

    • API: Initialize

    • Method: HTTPS POST

    • Description: Before you start each eKYC verification process, call this API to obtain a transactionId and a transactionUrl. These parameters link the API calls for a single verification request.

    • This API operation has a dedicated QPS limit. For more information, see QPS limits for ID Verification server-side API operations.

    • Endpoints:

      Note

      • Benefits of internal network access: An internal network is a private communication network between Alibaba Cloud products within the same region. If your business server is deployed in the corresponding Alibaba Cloud region, you can use the internal same-region endpoint to access the ID Verification service. This provides more secure and stable communication.

      • Optimization suggestions for access from outside China: Network environments outside China can be complex. To optimize your integration solution, reduce network latency, and minimize request failures, see Server-side network latency analysis and optimization.

      China (Hong Kong)

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

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

    Online debugging and integration

    Note

    Before you debug and integrate an API operation, see Debug and integrate server-side API operations using OpenAPI Explorer for information about how to call API operations and obtain SDKs and sample code in OpenAPI Explorer.

    You can run this API directly in OpenAPI Explorer to debug and generate SDK code examples.

    Request parameters

    Parameter

    Type

    Required

    Description

    Example

    ProductCode

    String

    Yes

    The solution to use. Valid value:

    eKYC: The eKYC solution. Users complete both document recognition and face liveness verification.

    eKYC

    MerchantBizId

    String

    Yes

    A unique business identifier that you define for troubleshooting purposes. The value can be a combination of up to 32 letters and digits.

    Note

    Alibaba Cloud does not check the uniqueness of this value. To simplify troubleshooting, ensure this value is unique.

    e0c34a77f5ac40a5aa5e6ed20c35****

    MetaInfo

    String

    Yes

    The MetaInfo environment parameter. You must call the getMetaInfo() function through the JS file to obtain it. For more information about how to obtain MetaInfo, see the client integration document for the corresponding platform.

    Important

    • Do not modify the return value. Pass it through directly.

    • The server-side uses this parameter to identify the mobile or PC runtime environment and sends different verification URLs. Obtain this parameter from a real runtime environment as described in the function description.

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

    MerchantUserId

    String

    Yes

    A user ID that you customize, or another identifier that can identify a specific user, such as a mobile number or email address. We strongly recommend desensitizing this value (for example, by hashing it).

    123456789

    ReturnUrl

    String

    No

    The redirect URL for your business page.

    Important

    This parameter is optional for iframe-based integrations only.

    https://www.alibabacloud.com

    DocType

    String

    Yes

    An 8-digit value that uniquely identifies the document type. For more information, see the table below.

    01000000

    SceneCode

    String

    No

    A custom verification scenario ID that you can use to query related records in the console. The value can be a combination of up to 10 letters, digits, or underscores (_).

    1234567890

    IdSpoof

    String

    No

    Specifies whether to enable anti-spoofing detection for documents:

    • Y: Enables the feature.

    • N: Disables the feature. This is the default value.

    Y

    Authorize

    String

    No

    Specifies whether to enable identity verification against official databases:

    • T: Enables the feature.

    • F: Disables the feature. This is the default value.

    Note

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

    F

    LanguageConfig

    String

    No

    The custom language configurations. Convert the language configurations that you want to add to a JSON string based on the configuration template. Then, specify this parameter to add the custom language configurations. For more information, see Internationalization language and custom text support.

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

    SecurityLevel

    String

    No

    The mode that represents different security levels of the verification flow. Valid values:

    • 01: Standard mode. This mode is applicable only to low-threat scenarios with restrictions on device information collection.

    • 02: Safe mode. A relatively strict mode (default).

      Note

      • Safe mode uses the new Device Guard module in the SDK to identify the security of the face-scanning environment based on device information. This effectively enhances the ability to intercept injection attacks. Enable this mode.

      • During development and testing, the environmental characteristics of a test device may cause Device Guard to assess it as a threat, which triggers a verification failure (Subcode 206). To improve testing efficiency, set the mode to '01 Standard mode' during the testing phase. When you go live, switch to '02 Safe mode' to enhance verification security.

    02

    StyleConfig

    String

    No

    The custom UI configurations. Convert the UI configurations that you want to add to a JSON string based on the configuration template. Then, specify this parameter to add the custom UI configurations. For more information, see IDV UI style customization.

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

    IdThreshold

    String

    No

    The custom OCR quality detection threshold mode:

    • 0: Standard mode

    • 1: Strict mode

    • 2: Loose mode

    • 3: Disable quality detection (default)

    0

    Model

    String

    No

    The type of liveness detection to perform:

    • LIVENESS: Blinking liveness detection (default).

    • PHOTINUS_LIVENESS: Blinking liveness detection and color-based liveness detection (not supported on PCs).

    • SILENT: Passive liveness detection. This feature is currently supported only for Web SDK (Mobile / PC) integrations.

    Note

    For information about the supported SDK versions, see SDK release notes.

    PHOTINUS_LIVENESS

    DocVideo

    String

    No

    Specifies whether to save a verification video.

    • N: No (default).

    • Y: A video of the user's face-scanning process (a 1 to 2 second video file) is collected during the verification and returned through the query API operation.

    Note

    Because the video file is large, the system may discard it if the network is unstable to prioritize the transmission of essential verification images.

    N

    ShowBlbumIcon

    String

    No

    Specifies whether to display the option to upload a photo from an album during document OCR:

    • 1: Displays the entry. This is the default value.

    • 0: Does not display the entry.

    1

    ShowOcrResult

    String

    No

    Specifies whether to display the recognition result page during document OCR:

    • 1: Displays the page. This is the default value.

    • 0: Does not display the page.

    1

    ShowGuidePage

    String

    No

    Specifies whether to display the guide page:

    Note

    This setting is not supported on PCs.

    • 1: Displays the page. This is the default value.

    • 0: Does not display the page.

    1

    ProcedurePriority

    String

    No

    Specifies whether to offer a fallback option if compatibility issues occur during verification on a mobile H5 page.

    • url (default): Fallback is supported. The page displays the verification URL, which the user can copy to another browser to continue the process.

    • keep: Fallback is not supported. The system directly returns the cause of the error and ends the verification process.

    Note

    • This setting is not supported on PCs.

    • If your use case involves completing the verification on a webpage embedded within an application, we recommend setting this parameter to keep to disallow the URL fallback.

    url

    CallbackUrl

    String

    No

    The webhook address for verification result notifications. The callback request method is GET by default. The webhook address must start with https. After the verification is complete, the platform sends a callback to this address and automatically adds the following parameters:

    • transactionId

    • passed

    • subcode

    Warning

    • The system checks whether this address is accessible before the API operation is called. If the address is not accessible over the public network, a 400 error is returned.

    • The callback is executed immediately after the verification is complete, but may be delayed due to network issues. We recommend that you first receive the verification completion notification on the client and then call the query API operation to obtain the verification details.

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

    CallbackToken

    String

    No

    A security token that you generate for anti-replay and anti-tampering verification.

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

    NMjvQanQgplBSaEI0sL86WnQplB

    AppQualityCheck

    String

    No

    Specifies whether to enable strict face quality detection:

    Important

    This feature is not supported by the Web SDK.

    • Y: Enables the feature. This is the default value.

    • N: Disables the feature.

    Y

    EditOcrResult

    String

    No

    Specifies whether users can edit information on the OCR result page.

    • 1: Supported. This is the default value.

    • 0: Not supported.

    0

    Document types

    DocType

    Document

    01000000

    Passport

    00000006

    Hong Kong (China) Identity Card (2003 version)

    00000008

    Hong Kong (China) Identity Card (2018 version)

    00000007

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

    00000009

    Mainland Travel Permit for Hong Kong and Macao Residents

    000000011

    Macao (China) Identity Card

    000000012

    Mainland Travel Permit for Taiwan Residents

    00000001

    Chinese mainland second-generation resident ID card

    Response data

    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

    For more information, see Response codes.

    Success

    Message

    String

    A detailed description of the response code.

    success

    Result.TransactionId

    String

    The unique identifier for the entire verification flow. This parameter is used for billing statistics and to initiate a CheckResult API operation request.

    Important

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

    • Attach the TransactionId to the business ID of your current business flow and store it on the server-side. When calling CheckResult, retrieve this verification ID from your server-side storage to initiate the result query.

    • After you obtain the TransactionId or TransactionUrl, you must complete the verification within 30 minutes. After this period, the ID or URL will automatically become invalid and cannot be used for verification.

    hksb7ba1b28130d24e015d********

    Result.TransactionUrl

    String

    The web verification URL. After the verification is complete, the user is redirected to the ReturnUrl specified in the request parameters.

    Important

    • During integration, do not modify the TransactionUrl. Modifying it may cause the verification to fail.

    • To ensure a secure and effective verification process, the TransactionUrl can be used only once. Reusing the URL causes the verification to fail.

    • After you obtain the TransactionId or TransactionUrl, you must complete the verification within 30 minutes. The ID or URL expires after this period.

    https://www.alibabacloud.com/index.html?clientcfg=****

    Result.Protocol

    String

    The standard encrypted protocol for verification.

    We recommend that you obtain this parameter and pass it to the client-side SDK. The client-side SDK uses this parameter to reduce network interactions and supports dynamic network switching to improve user experience.

    Note

    This field is required for iframe-based H5 integrations.

    hksb7ba1b28130d24e015d*********

    Response codes

    HTTP status code

    Code

    Description

    200

    Success

    Request successful.

    400

    MissingParameter

    Parameter cannot be empty.

    InvalidParameter

    Invalid parameter.

    401

    Forbidden.ExceptionRepeatedInvoke

    The number of repeated abnormal calls exceeds the limit.

    403

    Forbidden.RAMUserAccessDenied

    You need to grant the RAM user the AliyunAntCloudAuthFullAccess permission. For more information, see Authorize RAM users to access the service.

    Forbidden.AccountAccessDenied

    Ensure that you have activated ID verification and your account has no overdue payment.

    Throttling.Api

    API request is blocked due to throttling.

    500

    InternalError

    Internal system error. Provide feedback to engineers for troubleshooting.

    503

    ServiceUnavailable

    The service is unavailable. Contact engineers for troubleshooting.