All Products
Search

This Product

    ID Verification:Initialize

    Document Center

    ID Verification:Initialize

    Last Updated:Dec 10, 2025

    This topic describes how to use the Initialize operation to initiate an authentication request.

    Initiate an authentication request

    • Operation: Initialize

    • Request method: HTTPS POST

    • Description: Before each authentication process, call this operation to obtain a transactionId and a transactionUrl. Use these to link all operations in the authentication request.

    • This API is subject to an exclusive queries per second (QPS) limit. For more information, see ID Verification server-side API QPS limits.

    • Endpoints:

      Note

      An internal network is a private communication network for Alibaba Cloud products within the same region. If your application server is deployed in an Alibaba Cloud region, you can use the VPC endpoint to access the ID Verification service for a more secure and stable network connection.

      China (Hong Kong)

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

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

    Online debugging and integration

    Note

    Before you debug and integrate, read Use OpenAPI Explorer to debug and integrate server-side API operations. This document explains how to call API operations on the OpenAPI platform and how to obtain the SDK and its sample code.

    You can call this operation in OpenAPI Explorer to test it and generate the SDK code examples.

    Request parameters

    Name

    Type

    Required

    Description

    Example

    ProductCode

    String

    Yes

    The product solution to use. The only valid value is FACE_LIVENESS.

    FACE_LIVENESS

    MerchantBizId

    String

    Yes

    A unique business ID that you define. Use this ID to track and troubleshoot issues. The ID can be up to 32 characters long and can contain letters and digits. Make sure that the ID is unique.

    Note

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

    e0c34a77f5ac40a5aa5e6ed20c35****

    MetaInfo

    String

    Yes

    The MetaInfo environment parameter. In a real environment, you need to obtain it by calling the getMetaInfo() function via a JS file. Refer to the client integration document for the corresponding platform to obtain the MetaInfo.

    Important

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

    • The server identifies the Mobile or PC running environment based on this parameter and issues different authentication URLs. Refer to the function description for real-time acquisition.

    {
  "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 define, or another identifier for a specific user, such as a mobile number or email address. We strongly recommend that you desensitize this value in advance, for example, by hashing the value.

    123456789

    ReturnUrl

    String

    No

    The target URL to which the user is redirected.

    Important

    This parameter is optional only when you use an iframe for encapsulation.

    https://www.alibabacloud.com

    SceneCode

    String

    No

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

    1234567890

    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 representing different security levels of the authentication process. Valid values:

    • 01: Standard mode. This mode is only applicable 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 and device. This effectively enhances interception of injection attacks. We strongly recommend selecting this mode.

    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": {****},
}

    Model

    String

    No

    The type of liveness detection to perform:

    • LIVENESS (default): Blink action liveness detection.

    • PHOTINUS_LIVENESS: Blink action liveness detection and colorful liveness detection (not supported on PC).

    • SILENT: Passive liveness detection. Currently supported only for Mobile / PC integration.

    Note

    For 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 authentication and returned through the query API operation.

    Note

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

    N

    ShowGuidePage

    String

    No

    Specifies whether to show the guide page:

    Note

    This switch is not supported on PC.

    • 1: Show the page (default).

    • 0: Do not show the page.

    1

    ProcedurePriority

    String

    No

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

    • url (default): Supports fallback. The page displays the authentication URL. The user can copy the URL to open it or switch to another browser to continue authentication.

    • keep: Does not support fallback. The system directly returns the error cause and ends the authentication process.

    Note

    • This switch is not supported on PC.

    • If the application scenario is to complete authentication in a web page embedded in an app, set this parameter to keep to disallow URL fallback.

    url

    CallbackUrl

    String

    No

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

    • transactionId

    • passed

    • subcode

    Warning

    • This value is checked for accessibility before the API operation is called. If the provided address cannot be accessed from the Internet, a 400 error is returned.

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

    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 value, the CallbackToken field is included in the CallbackUrl webhook.

    NMjvQanQgplBSaEI0sL********

    AppQualityCheck

    String

    No

    Specifies whether to enable strict face quality check:

    Important

    This feature is not supported by the Web SDK.

    • Y: Enable (default).

    • N: Disable.

    Y

    Return 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

    Back to Code.

    Success

    Message

    String

    A detailed description of the response code.

    success

    Result.TransactionId

    String

    The unique identifier for the entire authentication process. This field is used for billing statistics and for initiating CheckResult API operation requests.

    Important

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

    • We recommend that you bind and store the TransactionId with your business process ID on the server. When calling CheckResult, retrieve this authentication ID from your server storage to initiate the result query.

    • After you successfully obtain the TransactionId or TransactionUrl, you must complete the authentication within 30 minutes. After this period, the ID or URL automatically expires and cannot be used for authentication.

    hksb7ba1b28130d24e015d6********

    Result.TransactionUrl

    String

    The web authentication URL. After authentication, the user is redirected based on the ReturnUrl input parameter.

    Important

    • During integration, do not modify the TransactionUrl. Modifying it may cause authentication exceptions.

    • To ensure a secure and effective authentication process, the TransactionUrl can be used only once. Accessing it more than once causes authentication exceptions.

    • After you obtain the TransactionId or TransactionUrl, you must complete the authentication within 30 minutes. After 30 minutes, the ID or URL automatically expires and cannot be used for authentication.

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

    Result.Protocol

    String

    Standard encrypted authentication protocol.

    Note

    This field is required when you integrate H5 web pages using the iframe embedding integration mode.

    hksb7ba1b28130d24e015d*********

    Response codes

    HTTP status code

    Code

    Message

    200

    Success

    Request successful.

    400

    MissingParameter

    Parameter cannot be empty.

    InvalidParameter

    Invalid parameter.

    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.