initialize

    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

    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

    Required. 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

    pages

    String

    32

    Required. 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

    h5ModeConfig

    Object


    Optional. Specifies the configuration settings for H5 ID Recognition flow. For more information,see h5ModeConfig


    #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". 


    #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",
        "docType": "08520000001",
        "pages": "1",
        "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\"
          }"
    }


    #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",
        "docType": "08520000001",
        "pages": "1",
        "metaInfo": "MOB_H5",
        "h5ModeConfig":{
          "completeCallbackUrl":"https://sg-production-cdn.zoloz.com/page/zoloz-doc-fe/index.html",
          "interruptCallbackUrl":"http://xxx.html"
        }
    }

    #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. 

    locale

    String

    16

    Optional. Language of the web page, only support: en/ zh-CN/ zh-HK now

    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