All Products
Search

This Product

    ID Verification:Initialize

    Document Center

    ID Verification:Initialize

    Last Updated:Nov 18, 2025

    This topic describes how to call the Initialize API operation to start the certificate Optical Character Recognition (OCR) process.

    Initiate an authentication request

    • API operation: Initialize

    • Request method: HTTPS POST

    • Description: Before starting the certificate OCR process, call this API operation to obtain a transactionId and a transactionUrl. These values are used to link the various API operations in the authentication request.

    • QPS limit: 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 between Alibaba Cloud products in the same region. If your application server is deployed in an Alibaba Cloud region, you can use the internal endpoint to access the ID Verification service. This provides a more secure and stable network connection.

      China (Hong Kong)

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

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

    Online debugging and integration

    Note

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

    In OpenAPI Explorer, you can directly debug this API operation and generate SDK code examples.

    Request parameters

    Name

    Type

    Required

    Description

    Example

    ProductCode

    String

    Yes

    The product solution to use. Set the value to ID_OCR.

    ID_OCR

    MerchantBizId

    String

    Yes

    A unique business ID that you define. It is used to locate and troubleshoot issues. The ID can be a combination of letters and digits, up to 32 characters long. Make sure the ID is unique.

    Note

    Alibaba Cloud servers do not check this field for uniqueness. For better tracking, we strongly recommend that you ensure this field 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 phone number or email address. We strongly recommend that you desensitize the value of this field in advance, for example, by hashing the value.

    123456789

    ReturnUrl

    String

    No

    The target address to which your business page redirects.

    Important

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

    https://www.alibabacloud.com

    DocType

    String

    Yes

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

    01000000

    SceneCode

    String

    No

    An authentication scenario ID that you define. You can use this ID to query related records in the console. The ID can be a combination of letters, digits, and underscores (_), up to 10 characters long.

    1234567890

    IdSpoof

    String

    No

    Specifies whether to enable the anti-spoofing check for certificates:

    • Y: Enable

    • N: Disable (default)

    Y

    IdThreshold

    String

    No

    Custom OCR quality detection threshold mode:

    • 0: Standard mode

    • 1: Strict mode

    • 2: Loose mode

    • 3 (default): Disable quality detection

    0

    ShowAlbumIcon

    String

    No

    Specifies whether to show the album upload entry during the certificate OCR step:

    • 1: Show (default)

    • 0: Hide

    1

    ShowOcrResult

    String

    No

    Specifies whether to show the recognition result page during the certificate OCR step:

    • 1: Show (default)

    • 0: Hide

    1

    ShowGuidePage

    String

    No

    Specifies whether to show the guide page:

    • 1: Show (default)

    • 0: Hide

    1

    CallbackUrl

    String

    No

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

    • transactionId

    • passed

    • code

    • subcode

    Warning

    The system checks if this address is accessible before calling the API operation. If the address is not accessible over the Internet, a 400 error is returned.

    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.

    NMjvQanQgplBSaEI0sL********

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

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

    Certificate type list

    DocType

    Corresponding certificate

    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 (China) Identity Card

    000000012

    Mainland Travel Permit for Taiwan Residents

    00000001

    Second-generation resident identity card of the Chinese mainland

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

    Code

    String

    The return code.

    Success

    Message

    String

    A detailed description of the return 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 page redirects based on the ReturnUrl request parameter.

    Important

    • During integration, do not modify the TransactionUrl. Doing so may cause authentication exceptions.

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

    • After you obtain the TransactionId or TransactionUrl, you must complete the authentication within 30 minutes. After 30 minutes, the ID or URL expires and can no longer 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*********

    Return 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.