This topic explains how to call the Initialize operation to start a verification session with the document optical character recognition (OCR) solution.
Initiate a verification request
Operation: Initialize
Request method: POST
Description: Call this operation to start a document OCR session. A successful call returns a unique transaction ID and transaction URL for the verification flow.
This API operation has a dedicated QPS limit. For more information, see QPS limits for ID Verification server-side API operations.
Endpoints:
NoteBenefits 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.comInternal network:
cloudauth-intl-vpc.cn-hongkong.aliyuncs.com
Online debugging and integration
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 use OpenAPI Explorer to directly run and debug this API, and generate an SDK code sample.
Request parameters
Parameter | Type | Required | Description | Example |
ProductCode | String | Yes | The product solution to use. Set the value to | ID_OCR |
MerchantBizId | String | Yes | A unique business identifier that you define to help track and troubleshoot issues. It can be a combination of letters and digits up to 32 characters long. Ensure that this ID is unique. Note Alibaba Cloud servers do not enforce the uniqueness of this value. For effective tracking, we strongly recommend that you ensure each ID 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
| |
MerchantUserId | String | Yes | A custom user identifier, such as a mobile phone number or email address. We strongly recommend that you mask this value before submission, for example, by using a hashing algorithm. | 123456789 |
ReturnUrl | String | No | The URL to which the user is redirected after the verification process completes. Important This parameter is optional only when you embed the verification flow in an iframe. | https://www.alibabacloud.com |
DocType | String | Yes | The document type, identified by a unique 8-digit code. For a list of supported document types, see the Document types table below. | 01000000 |
SceneCode | String | No | A custom ID for the verification scenario. You can use this ID to search for related records in the ID Verification console. It can contain up to 10 characters, including letters, digits, and underscores (_). | 1234567890 |
IdSpoof | String | No | Specifies whether to enable document anti-spoofing detection. Valid values:
| Y |
IdThreshold | String | No | The custom OCR quality detection threshold mode:
| 0 |
ShowAlbumIcon | String | No | Specifies whether to display an icon for uploading a document from the photo album during the OCR process. Valid values:
| 1 |
ShowOcrResult | String | No | Specifies whether to display the OCR result page. Valid values:
| 1 |
ShowGuidePage | String | No | Specifies whether to display the guide page. Valid values:
| 1 |
CallbackUrl | String | No | The webhook address for verification result notifications. The callback request method is GET by default. The webhook address must start with
Warning
| https://www.aliyun.com?callbackToken=100000****&transactionId=shaxxxx&passed=Y&subCode=200 |
CallbackToken | String | No | A security token that you generate to prevent replay attacks and data tampering. If you set this parameter, the CallbackToken is included in the request sent to your callback URL. | 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. | |
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. | |
EditOcrResult | String | No | Specifies whether users can edit the information on the OCR result page. Valid values:
| 0 |
Document types
DocType | Document |
01000000 | Passport (Global) |
00000006 | Hong Kong Permanent Identity Card (2003 version) |
00000008 | Hong Kong Permanent 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 SAR Permanent Resident Identity Card |
000000012 | Mainland Travel Permit for Taiwan Residents |
00000001 | Second-generation resident ID card for the Chinese mainland |
Response parameters
Parameter | 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 response code. | 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
| hksb7ba1b28130d24e015d6******** | |
Result.TransactionUrl | String | The URL for the web-based verification flow. After the process completes, the user is redirected to the URL specified in the Important
| https://www.alibabacloud.com/index.html?clientcfg=**** | |
Result.Protocol | String | The standard encryption protocol for the verification. We recommend that you obtain this parameter and pass it to the client side SDK. The SDK uses this parameter to reduce network interactions and support dynamic network switching, which improves user experience. Note This parameter is required for H5 integrations that use an iframe. | 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. |