Call the Initialize API to initiate certificate OCR - ID Verification

This topic describes how to call the Initialize API operation to initiate a request for certificate Optical Character Recognition (OCR).

Initiate an authentication request

API operation name: Initialize
Request method: HTTPS POST
Description: Before you start each certificate OCR process, call this API operation to obtain a transactionId . The transactionId links all API operations in the authentication request.
This API operation has a dedicated QPS limit. For more information, see QPS limits for ID Verification server-side API operations.
Service endpoint:
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 operation directly in OpenAPI Explorer to debug it, and generate an SDK code sample .

Request parameters

Name	Type	Required	Description	Example
ProductCode	String	Yes	The product plan to use. Set the value to ID_OCR.	ID_OCR
SceneCode	String	No	A custom authentication scenario ID. Use this ID to query related records in the console. The ID can contain up to 10 letters, digits, and underscores (_).	1234567890
MerchantBizId	String	Yes	A custom unique business ID for troubleshooting. The ID can contain up to 32 letters and digits. Ensure it is unique. Note Alibaba Cloud servers do not check the uniqueness of this value. For better tracking, ensure that the value is unique.	e0c34a77f5ac40a5aa5e6ed20c35****
MetaInfo	String	Yes	The MetaInfo environment parameter. Obtain this parameter using the client SDK. For more information, see Android SDK integration. Note Do not modify the return value. Pass it through directly.	{"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 custom user ID or another identifier for a specific user, such as a mobile phone number or an email address. Strongly recommend desensitizing this value in advance, such as by hashing it.	123456789
IdSpoof	String	No	Specifies whether to enable certificate anti-spoofing detection: Y: Enable N: Disable (default)	Y
DocType	String	Yes	The certificate type. An 8-digit number serves as the unique identifier. For details, see the following table.	01000000
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
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 fields: 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. 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
DocPageConfig	String	No	A JSON string array: OCR_ID_BACK: Collect the back page. Note Currently, only Chinese mainland ID cards are supported.	OCR_ID_BACK
ShowGuidePage	String	No	Specifies whether to display the guide page: 1 (Default): Display 0: Do not display	1
DocScanMode	String	No	OCR certificate scanning mode: shoot (Default): Take a photo scan: Scan auto: Automatic switchover between taking a photo and scanning	shoot

Certificate types

DocType	Corresponding certificate
01000000	Global passport
00000001	Second-generation resident ID card of the Chinese mainland
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

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.	Success
	Message	String	The detailed description of the response code.	success
	Result.TransactionId	String	The unique identifier for the entire verification flow. This field 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.	hksb7ba1b28130d24e015d6********
	Result.Protocol	String	The standard encryption protocol for authentication. We recommend that you obtain this parameter and pass it to the client SDK. The client SDK uses this parameter to reduce network interactions and support dynamic network switching, improving user experience.	hksb7ba1b28130d24e015d*********

Return code

HTTP status code	Code	Description
200	Success	Request successful.
400	MissingParameter	Parameter cannot be empty.
400	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.