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: docType specifies the document type, while autoDocTypes and autoDocCategory are used for automatic document classification. These three parameters are mutually exclusive; only one can be passed at a time.

"00000001003"

autoDocTypes

List<String>

200

null

Optional. Specify the list of document types. The parameters docType, autoDocTypes, and autoDocCategory are mutually exclusive and only one of them is supported for input at a time.

  • When autoDocTypes is provided, ZOLOZ will automatically classify the document uploaded. The passport auto-classification feature is supported, but it is only available in the Native SDK.
  • If the uploaded document could not be classified or it is not included in autoDocTypes list, the checkresult API will return NO_REQUIRED_ID.

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 docType, autoDocTypes, and autoDocCategory are mutually exclusive; only one can be passed at a time.

  • If you pass autoDocCategory, ZOLOZ will automatically classify the uploaded documents. The supported document categories are as follows:
    • PASSPORT: Passport
    • DRIVING_LICENSE: Driving License
    • ID_CARD: ID Card
    • RESIDENCE_PERMIT: Residence Permit
    • VISA: Visa
    • ALL: All documents
  • If ZOLOZ cannot classify the uploaded document or the classified document type is not in autoDocCategory, it will return NO_REQUIRED_ID.

Note: Please be cautious that if autoDocCategory is in use, the docType classified could be a new type supported by ZOLOZIt also means certType and docCategory in checkresult response could fall into a new type as we continue to expand the doc coverage globally. For example, when autoDocCategory in request is ALL, based on the doc submitted by user, after auto classification, the certType could be a new doc type (e.g. 00000001001 and NEW_CATEGORY). (For illustration only)

Please take necessary compatible actions for integration. For example, do not strongly validate the returned certType and docCategory.

"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 frontPageImage and backPageImage must not exceed 5MB. If the images are too large, it is recommended to compress them before uploading to avoid system errors.

"/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 frontPageImage and backPageImage must not exceed 5MB. If the images are too large, it is recommended to compress them before uploading to avoid system errors.

"/9j/4AA..[omitted]..PxA="

operationMode

String

32

STANDARD

Optional. Specifies the operation mode where the identity proofing process runs. The following values are supported:

  • CLOSED: All the algorithms and risk control rules are not applied. You can use this operation mode in the test phase so that the algorithms and risk controls rules do not affect the test process.
  • STANDARD: A standard recommended level is applied.
  • LOOSE: A relatively looser level is applied. You can use this operation mode in low-risk scenarios.
  • STRICT: A relatively stricter level is applied. You can use this operation mode in high-risk scenarios.

"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 sceneCode field to different values according to your business purpose; for example, login, riskVerify, payment, changePassword. Setting this value will not have business impacts.

"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.
An array of supported information check components needs to be specified if consistency check is expected. To understand the valid values for this field, please refer to consistency check data structure.

[

{

"type": "commonConsistencyCheck"

},

{

"details": [

"NAME",

"SEX"

],

"type": "mrzVisualConsistencyCheck"

},

{

"valueRange": [

"CHN",

"PHL"

],

"type": "passportCountryCheck"

}

]

allowExpiredDocument

String

-

Different document types have different default values:

  • Y: This is the default value for all documents except Passport (docType=00000001003).
  • N: This is the default value for Passport (docType=00000001003).

Optional. Specifies whether expired documents are allowed. The following values are supported:

  • Y: Allow expired documents.
  • N: Pause ID Recognition process when an expired document is detected.

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: Crop an additional face image from the doc image
  • N: Default value. Do not crop

"Y"

enableOCR

String

-

N

Optional. Whether to enable the OCR function. The values are as follows:

  • Y: Enabled
  • N: Not enabled

"Y"

spoofMode

tring

10

CLOSED

Optional. This parameter refers to document anti-spoofing levels, defined as follows:

  • CLOSED: All algorithms are not applied. You can use this anti-spoofing detection mode in the test phase so that the algorithms do not affect the testing process.
  • STANDARD: A standard recommended level is applied.
  • LOOSE: Reserved value, not currently supported for use.
  • STRICT: Reserved value, not currently supported for use.

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

  • front page: ID_NUMBER
  • back page: ID_NUMBER_BACK first 12 digit

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.

  • When type is set as mrzVisualConsistencyCheck, details field is required and should not be null.
  • Only allow to input OCR fields supported by the ID document.

MyVisa / Malaysia / 00600000011 /

  • NAME
  • SEX

Passport (both MRZ and VIZ) / CHN, HKG, TWN, MAC, PHL, SGP, MYS / 00000001006 /

  • ID_NUMBER
  • COUNTRY_CODE
  • EXPIRY_DATE
  • DATE_OF_BIRTH

Travel Permit for Hong Kong and Macau / China / 00860000011

  • ID_NUMBER
  • DATE_OF_EXPIRY

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 COUNTRY_CODE in the OCR result is consistent with the country detected by the system.

valueRange

List<String>

Each value should be the same as

the default country code.

The COUNTRY_CODE in the OCR result should be within the valueRange.

When the type is set to passportCountryCheck, the valueRange field must be provided. For the supported valueRange of each document, please refer to

Document types supported and OCR results returned

For below docTypes, valueRange should be a list of its default country or region code

  • China Passport / 00860000888 / COUNTRY_CODE / CHN
  • China Taiwan Passport / 08860000002 / COUNTRY_CODE / TWN
  • China Macao Passport / 08530000002 / COUNTRY_CODE / CHN
  • Philippines Old Passport / 00630000031 / COUNTRY_CODE / PHL
  • Philippines New Passport /00630000032 / COUNTRY_CODE / PHL

Each value should comply with ISO_3166-1_alpha-3

For below docTypes, valueRange should be a list, and each item should comply with ISO_3166-1_alpha-3

  • Internaltional Passport / 00000001003 / COUNTRY_CODE
  • Passport (with MRZ and VIZ) / 00000001006 / COUNTRY_CODE

Request Sample

copy
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

CommonResult

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

copy
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;