initialize

2024-11-01 09:54

POST /api/v1/zoloz/idrecognition/initialize

The ZOLOZ initialize API is used to initialize the ID recognition process in ZOLOZ. A unique transaction ID is generated for the ID recognition process and used in all the subsequent interactions with the ZOLOZ server. This API is not idempotent.

Structure

Request parameters

Field name	Data type	Max length	Default Value	Description
bizId	String	32	-	Required. A unique business ID for tracing purpose. For example，the sequence ID from the merchant's business-related database. Note: The ZOLOZ server does not perform uniqueness check on the value of this field. For better tracking, it is strongly recommended to enable the merchant server to guarantee the uniqueness of the business ID.
metaInfo	String	512	-	Required. The meta information about the SDK and the user's device. The value of this field is returned from the ZOLOZ SDK in the JSON string format, for example: `"{\"apdidToken\":\"69b74bfe-bf7f-4d3b-ac59-907ee09e7955\",\"appName\":\"com.zoloz.atomic.client\",\"appVersion\":\"1.0.9\",\"bioMetaInfo\":\"3.46.0:2916352,0\",\"deviceModel\":\"MI 6\",\"deviceType\":\"android\",\"osVersion\":\"9\",\"zimVer\":\"1.0.0\"}"`. Note: Do not modify the returned value as it only needs to be passed through directly.
userId	String	64	-	Required. 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.
docType	String	16	-	Optional. Type of the document, for example, if the document to be uploaded is a passport, set the value of this attribute to 00000001003. The value of this field must not be null or an empty string. For the document types that are supported, see Document types supported and OCR results returned. Note: Please provide either `docType` or `autoDocTypes`.
autoDocTypes	List<String>	200	-	Optional. Specify list of document types. Please provide either `docType` or `autoDocTypes`. When `autoDocTypes` is provided, ZOLOZ will automatically classify the document uploaded. Notes： passport currently is not supported for auto classified. Singapore Citizen card(00650000001) and PR card(00650000002) will be both classified as Singapore Citizen card. If the uploaded document could not be classified or it is not included in `autoDocTypes` list, the checkresult API will return `NO_REQUIRED_ID`. The value of items in `autoDocTypes` must be a valid docType. Supported document types, see Document types supported and OCR results returned.
pages	String	32	All pages supported by the document type	Optional. The document pages that you want to do id recognition. Use comma to separate. For the document page range, see Document types supported and OCR results returned. Note: When `autoDocTypes` is provided, `pages` should be null; if `pages` is not null, `INVALID_ARGUMENT` will be returned.
serviceLevel	String	32	IDRECOGNITION0002	Optional. Three levels are supported: IDRECOGNITION0002 (default): basic anti-spoofing, which only captures a normal photo of the document. IDRECOGNITION0003: flashlight anti-spoofing. If this value is set, the ZOLOZ SDK automatically scans the identity document. The ZOLOZ server performs advanced spoofing checks. This level shall only be used in native SDK, as web SDK has technical limitations in operating the flashlight. If it is used in web SDK, the behaviour is unpredictable. IDRECOGNITION0005: multi-angle anti-spoofing. This level shall only be used in web SDK, the behaviour is unpredictable when used in native SDK. As of now, this level only supports HK identity cards, other document types may be supported in future when needed.
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.
h5ModeConfig	Object		-	Optional. Specifies the configuration settings for H5 ID Recognition flow. For more information，see h5ModeConfig.
productConfig	ProductConfig	-	-	Optional. Specifies finer controls for the IDR product. For more information, see productConfig.

Response parameters

Field name	Data type	Description
result	Result	Required. The API request result, which contains information about the result of the API request, such as status and error codes.
transactionId	String	Optional. A unique transaction ID that is generated by the ZOLOZ server for the ID recognition process. This ID will be used as an input parameter for the ID recognition checkresult API request. Note: when an error occurs during the process, for example, invalid argument, no transaction ID is returned.
clientCfg	String	Optional. The client configuration information, including parameters about SDK connection and behavior. The value of this field is specified only when the result.resultStatus field is `"S"`.

productConfig

The following table shows the fields that can be specified in the productConfig data model.

Field name	Data type	Max length	Default Value	Description
pageInfoCheck	Array	-	null	Optional. Specify 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.
consistencyCheck	List<ConsistencyCheckItem>	-	null	Optional. Specify whether to perform consistency checks. Consistency checks are only applicable for selected 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.
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.
cropFaceImageFromDoc	String	1	N	Optional. Specify whether to crop the face area of the captured doc image. Valid values include: `Y`: Crop an additional face image from the original captured doc image. `N`: Do not crop.
enableOCR	String	-	N	Optional. Whether to enable the OCR function. The values are as follows: ● `Y`: Enabled ● `N`: Not enabled Note: You need to purchase the OCR product before you can use this feature.
spoofMode	String	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.

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
details	List<String>	refer to supported ocr fileds of each docType		Passport (both MRZ and VIZ) / CHN, HKG, TWN, MAC, PHL, SGP, MYS / 00000001006 / ID_NUMBER COUNTRY_CODE EXPIRY_DATE DATE_OF_BIRTH

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>	should be the same as the default country code.	when type is passportCountryCheck, `valueRange` should not be empty. Refer to allowed value of supported docType.	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
valueRange	List<String>	each item 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 viz / 00000001006 / COUNTRY_CODE

Result

Result process logic

For different request results, different actions are to be performed. See the following for details:

If the value of the result.resultStatus is S , the ZOLOZ initialize API is invoked successfully and a unique transaction ID is returned.
If the value of the result.resultStatus is F , the invocation of the ZOLOZ initialize API fails. Check the error code and message for more information about the possible reasons. Error codes

Common error codes

For the full list of common error codes, see the Common error codes section in the Error handling topic.

API-specific error codes

The following table shows the possible error codes that are specific for the ID Recognition initialize API.

resultCode	resultStatus	Description
SUCCESS	S	The API call is successful.
HIGH_RISK	F	High risks are detected. The user account is strategically cooled down by the risk engine.
ACCOUNT_SERVICE_SUSPEND	F	The user account is blacklisted by the risk engine.
DEVICE_NOT_SUPPORT	F	The device type is not supported.
OS_NOT_SUPPORT	F	The operating system of the device is not supported.
SDKVERSION_NOT_SUPPORT	F	The version of the ZOLOZ SDK is not supported.
INVALID_ARGUMENT	F	Input parameters are invalid. For more information about which parameter is invalid, check the result message or the related log.
SYSTEM_ERROR	F	Other internal errors. For more information about the error details, check the result message that is returned and the related log.

Sample

Request sample

For different integration modes, the request structures are a little different. When the ID recognition process is initiated in the H5 mode, additionally, an object called h5ModeConfig must be specified. Refer to the following two request samples for the detailed information.

Native Request Sample

The following sample shows what a request looks like if the identity proofing process is initiated in the App SDK mode.

copy
{
    "bizId": "2017839040588699",
    "userId": "123456abcd",
    "autoDocTypes":["08520000001","08520000002"],
    "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"
  },
    "metaInfo": "{
           \"deviceType\": \"deviceType\",
           \"appVersion\": \"1.0\",
           \"osVersion\": \"7.1.1\",
           \"appName\": \"com.company.wallet\",
           \"bioMetaInfo\": \"3.37.0:262144,0\",
           \"apdidToken\": \"mock-apdidToken\",
           \"deviceModel\": \"MI 6\",
           \"zimVer\": \"2.0.0\"
      }",
  "serviceLevel": "IDRECOGNITION0002",
  "operationMode": "CLOSED" 
}

H5 RealId Request Sample

The following sample shows what a request looks like if the ID recognition process is initiated in the H5 mode.

copy
{
    "bizId": "2017839040588699",
    "userId": "123456abcd",
    "autoDocTypes":["08520000001","08520000002"],
    "metaInfo": "MOB_H5",
    "h5ModeConfig":{
      "completeCallbackUrl":"https://sg-production-cdn.zoloz.com/page/zoloz-doc-fe/index.html",
      "interruptCallbackUrl":"http://xxx.html"
   },
    "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"
  },
   "serviceLevel": "IDRECOGNITION0002",
   "operationMode": "CLOSED"
}

Response Sample

The following sample shows what a response that the ZOLOZ server returns looks like.

copy
{
   "result": {
        "resultStatus": "S",
        "resultCode": "SUCCESS",
        "resultMessage": "Success"
    },
  "transactionId":"G000000005FID20200304000000000001570702", 
  "clientCfg": "……"   
}

More information

h5ModeConfig

The following table shows the fields that can be specified in the h5ModeConfig Object.

Field name	Data type	Max length	Description
state	String	128	Optional. An identifier that is used to recover the customer's context. You can set this field to any String value. The value is then passed as a parameter when the ZOLOZ SDK calls back to the merchant's application. If the value is not set, the value of the transactionId field is used.
completeCallbackUrl	String	128	Required. Specifies the callback URL where the browser is redicted when the whole identity proofing process is completed.
interruptCallbackUrl	String	128	Required. Specifies the callback URL where the browser is redirected when the process is interrupted.
isIframe	String	1	Optional. If the Web Page need to be open in Iframe, this param should be set as Y. Supported Value: Y / N
uiCfg	String	256	Optional. Custom UI configurations in the JSON string format. Only support `titlebarbgcolor`, `titlebartextcolor`, and `buttoncolor` and `captureMode` for now. For example:`"{\"titlebarbgcolor\":\"#ffffff\",\"titlebartextcolor\":\"#000000\",\"buttoncolor\":\"#3696fd\", \"captureMode\":\"landscape\"}"` If set `captureMode` param to "landscape", the sdk will be switched to landscape capture mode.