asyncrecognize
Overview
- API URL: POST
/api/v1/zoloz/idrecognition/asyncrecognize
- API Description: The ZOLOZ ID Recognition asyncrecognize API initializes an asynchronous document recognition request. When you need to frequently call the recognize API, it is recommended to use the asyncrecognize API to avoid response timeouts due to network fluctuations. After the API call completes, you can asynchronously obtain the document verification results using the asynccheckresult API.
Request
Fields Specification
Field name | Data type | Max length | Default Value | Description | Example |
bizId | String | 32B | - | Required. A unique ID maintained by client for tracing purpose. | "trans-test-1234" |
docType | String | 32B | null | Optional. Specify the document types.
Note: | "00000001003" |
autoDocTypes | List<String> | 200 | null | Optional. Specify the list of document types. The parameters
Supported document types, see Document types supported and OCR results returned. | [ "08520000001", "08520000002" ] |
autoDocCategory | List<String> | - | null | Optional. Optional. Specifies list of document types. The parameters
Note: Please be cautious that if Please take necessary compatible actions for integration. For example, do not strongly validate the returned | "ID_CARD" |
frontPageImage | String | 5MB | - | Required. The front image of the document supports Base64 encoded JPG, JPEG, PNG, and BMP formats. Note: The total size of | "/9j/4AA..[omitted]..PxA=" |
backPageImage | String | 5MB | - | Optional. Required. The back image of the document supports Base64 encoded JPG, JPEG, PNG, and BMP formats. Note: The total size of | "/9j/4AA..[omitted]..PxA=" |
operationMode | String | 32 | STANDARD | Optional. Specifies the operation mode where the identity proofing process runs. The following values are supported:
| "STANDARD" |
sceneCode | String | 64 | null | Optional. Specifies the business scene for data analysis purpose. If you want to distinguish the data performance of different scenes, it is recommended to set the | "changePassword" |
userId | String | 64 | null | Optional. Merchant user ID, or other identifiers that can be used to identify a specific user. For example, mobile phone number, email address and so on. It is strongly recommended to pre-desensitize the value of the userId field; for example, by hashing the value. | "trans-abc-1234" |
productConfig | ProductConfig | - | null | Optional. Specifies finer controls for the IDR product. For more information, see productConfig. | { "consistencyCheck": [ { "type": "commonConsistencyCheck" }, { "details": [ "NAME", "SEX" ], "type": "mrzVisualConsistencyCheck" } ] } |
ProductConfig
Field name | Data type | Max length | Default Value | Description | Example |
pageInfoCheck | Array | - | null | Optional. Specifies page information check in the DOC spoofing check. For detailed inspection items, refer to the DOC spoofing check component. Note: Page information check is only applicable to Hong Kong, China identity cards and Malaysia Mykad. | [ {"name":"id"}, {"name":"symbol"}, {"name":"name"} ] |
consistencyCheck | List<ConsistencyCheckItem> | - | null | Optional. Specifies whether to perform consistency check. Consistency check is only applicable to specific fields of certain documents. | [ { "type": "commonConsistencyCheck" }, { "details": [ "NAME", "SEX" ], "type": "mrzVisualConsistencyCheck" }, { "valueRange": [ "CHN", "PHL" ], "type": "passportCountryCheck" } ] |
allowExpiredDocument | String | - | Different document types have different default values:
| Optional. Specifies whether expired documents are allowed. The following values are supported:
Note: Invalid values will fall back to the default option and pause the ID Recognition process when an expired document is detected. | "N" |
cropFaceImageFromDoc | String | 1 | N | Optional. Specifies whether to crop the face area of the captured doc image. Valid values include:
| "Y" |
enableOCR | String | - | N | Optional. Whether to enable the OCR function. The values are as follows:
| "Y" |
spoofMode | tring | 10 | CLOSED | Optional. This parameter refers to document anti-spoofing levels, defined as follows:
Note: You need to purchase the Spoof product before you can use this feature. | "STANDARD" |
ConsistencyCheckItem data structure
commonConsistencyCheck
Field name | Data type | Value range | Description | Supported ID / Country or Region / docType / OCR field to check |
type | String | commonConsistencyCheck | Consistency check of OCR field within DOC spoofing check | Mykad / Malaysia / 00600000001 / ID_NUMBER
|
mrzVisualConsistencyCheck
Field name | Data type | Value range | Description | Supported ID / Country or Region / docType / OCR field to check |
type | String | mrzVisualConsistencyCheck | Consistency check of OCR field which has both MRZ (machine readable zone) and VIZ (visual inspection zone)within DOC spoofing check | - |
details | List<String> | Refer to supported ocr fileds of each docType | Specify ocr field in details for consistency check.
| MyVisa / Malaysia / 00600000011 /
|
Passport (both MRZ and VIZ) / CHN, HKG, TWN, MAC, PHL, SGP, MYS / 00000001006 /
| ||||
Travel Permit for Hong Kong and Macau / China / 00860000011
|
passportCountryCheck
Field name | Data type | Value range | Description | Supported ID / Country or Region / docType / OCR field to check / default country code |
type | String | passportCountryCheck | Checks that the | |
valueRange | List<String> | Each value should be the same as the default country code. | The When the | For below docTypes,
|
Each value should comply with ISO_3166-1_alpha-3 | For below docTypes,
|
Request Sample
POST /api/v1/zoloz/idrecognition/asyncrecognize HTTP/1.1
Content-Type: application/json; charset=UTF-8
Client-Id: 5X67656YXXXXXX
Request-Time: 2024-01-04T12:08:56+05:30
Signature: algorithm=RSA256, signature=xxxxxxxxxxxx
{
"bizId": "trans-test-1234",
"autoDocTypes":["08520000001","08520000002"],
"frontPageImage": "/9j/4AA..[omitted]..PxA=",
"backPageImage": "/9j/4AA..[omitted]..PxA=",
"productConfig": {
"consistencyCheck": [
{
"type": "commonConsistencyCheck"
},
{
"details": [
"NAME",
"SEX"
],
"type": "mrzVisualConsistencyCheck"
},
{
"valueRange": [
"CHN",
"PHL"
],
"type": "passportCountryCheck"
}
],
"pageInfoCheck": [
{
"name": "id"
},
{
"name": "symbol"
},
{
"name": "name"
}
],
"allowExpiredDocument": "Y",
"cropFaceImageFromDoc": "Y",
"enableOCR": "Y",
"spoofMode": "STANDARD"
},
"operationMode": "STANDARD",
"sceneCode": "changePassword",
"userId": "userid_1234"
}
Response
Fields Specification
Field name | Data type | Description | Example |
result | Required. Common result, please refer to Appendix. | { "resultCode": "PROCESSING", "resultStatus": "S", "resultMessage": "It is still under processing" } | |
transactionId | String | Required. Transaction id | "G000000005FID2020030400000000000157****" |
Response Sample
HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8
Response-Time: 2024-01-19T21:56:15-0800
Signature: algorithm=RSA256, signature=xxxxxxxxxxxxxxxxxx
{
"transactionId": "G000000005FID2020030400000000000157****",
"result": {
"resultCode":"PROCESSING",
"resultStatus":"S",
"resultMessage":"It is still under processing"
}
}
Appendix
CommonResult Model
Description: A unified data structure that indicates the status of API invocation.
Fields Specification:
Field name | Data type | Mandatory | Value Range | Description | Sample Value |
resultCode | string | true | result code | "SUCCESS" | |
resultStatus | string | true | "S": successful "F": failed | result status | "S" |
resultMessage | string | true | result description | "success" |
The value range of "resultCode"at business level:
resultCode | Description |
SUCCESS | success |
SYSTEM_ERROR | other internal errors; |
INVALID_ARGUMENT | input parameters are illegal; |