Parameter

Data type

Max length

Default Value

Description

Example

bizId

String

32

-

Required. A unique business ID for tracing purposes. For example, the sequence ID from the merchant's business-related database.

Note: The ZOLOZ server does not perform uniqueness checks 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.

"1658894076638"

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.

"e9830710-0d70"

riskDetection

RiskDetection

-

null

Optional. Risk detection. For more details, please see RiskDetection.

Note: When data is being stored, in order to improve efficiency, this field can be skipped so that data is stored first without risk detection. Once data has been stored, risks can be detected using the risk query interface instead.

{

"riskTypes":[ "IDFAKE", "DUPLICATE",

"BATCH_REGISTER",

"DEEPFAKE"

],

"timeWindow":{ "startTime":1651882535687, "endTime":1658902665000 }

}

checkAllianceRisk

String

–

N

Optional. Specifies whether to check the affiliate risk. The default value is N.

• Y: Check affiliate merchants at the same time
• N: Only the current merchant is checked.

“N”

imageInfo

ImageInfo

–

-

Required. Specifies the image information to be passed in. For more details, see ImageInfo.

• Currently, only faceImage fields are supported. docImage fields are not supported by the system at the moment.
• The image size should not exceed 5MB.

{ "docImage":"eA3AW/6dxn6QAAAABJRU5ErkJggg==...", "faceImage":"p+AY/b2OF/F1CxAAAAAElFTkSuQmCC..."

}

basicInfo

BasicInfo

–

null

Optional. Basic information about the user. For more details, see BasicInfo.

Note:The values of the incoming basicInfo field should be as detailed as possible. In the risk detection phase, the incoming basic information will be compared.

{

"idType":"00000001003", "idNumber":"46082119870811896X", "certName":"Tom", "dateOfBirth":"19870811"

}

referenceId

String

64

null

Optional. Specifies the reference ID value returned by other businesses.

Supports passing in the transactionId of RealID or Face Capture. When this field is provided, and if the customer does not provide faceImage, the system will obtain the corresponding face image from the transaction identified by transactionId; if the customer provides faceImage, the system will give priority to the face image in faceImage. The fields in the basicInfo object follow the same logic, giving priority to the data provided by the customer.

"8365364ceddd411da027cdb15fea92ed"

scene

String

32

kyc

• Optional：

• kyc, Indicates the authentication scenario
• verification，Indicates an identity verification scenario

• Non-mandatory field

Note: The risk type being queried needs to align with the scenario; each risk type will be queried within the data corresponding to its respective scenario.

"kyc"

Field

Data type

Max length

Default Value

Description

Example

riskTypes

List<String>

-

[]

Optional. Specifies the type of risk to be queried. The following four major risk types are supported, and the system will automatically query the sub-risks they contain.

• IDFAKE: Impersonated identity
• DUPLICATE: Duplicate authentication
• BATCH_REGISTER: Batch register
• DEEPFAKE：Deepfake face

[

"IDFAKE",

"DUPLICATE",

“BATCH_REGISTER” ,

"DEEPFAKE"

]

timeWindow

TimeWindow

-

The last 180 days

Optional. The risk query time window can support up to 180 days of data, with the default being the most recent 180 days. For more details, see TimeWindow.

Note: The system limits the data volume for a single scan to 500,000 records. If the data volume within the query time window exceeds 500,000 records, the system will dynamically adjust the time window you set.

{ "startTime":1651882535687, "endTime":1658902665000 }

riskThreshold

Integer

-

1

Optional. Specifies the threshold for risk query. When the number of historical associated risk transactions exceeds the specified threshold, it will be intercepted. The same itemId will only be counted once.
Support passing any integer greater than or equal to 1, with a default threshold value of 1.

1

Field

Data type

Max length

Default Value

Description

Example

startTime

Long

-

null

Optional. Risk query start time, using a 13-digit timestamp.

1651882535687

endTime

Long

-

null

Optional. Risk query end time, using a 13-digit timestamp.

1658902665000

Field

Data type

Max length

Default Value

Description

Example

docImage

String

-

null

Optional. The ID image to be passed in (this field is not supported at the moment).

"eA3AW/6dxn6QAAAABJRU5ErkJggg==..."

faceImage

String

-

null

Optional. The face image to be passed in.

"p+AY/b2OF/F1CxAAAAAElFTkSuQmCC..."

Field

Data type

Max length

Default Value

Description

Example

idType

String

32

null

Optional. Specifies the document type. For supported document types, see Document types supported and OCR results returned.

"00000001003"

certName

String

32

null

Optional. Name.

"Tom"

idNumber

String

32

null

Optional. ID number.

"46082119870811896X"

dateOfBirth

String

-

null

Optional. The date of birth in yyyyMMdd format.

"19870811"

Parameters

Data type

Description

Example

result

Result

Required. The API request result, which contains information about the result of the API request, such as status and error codes.

{

"resultStatus":"S", "resultCode":"SUCCESS", "resultMessage":"Success" }

transactionId

String

Optional. A unique business ID generated by the IDN.

Note: The system will only return the transactionId after the transaction enters the processing stage. If an error occurs before the transaction begins processing, the system will not return a transactionId. This includes, but is not limited to, the following situations:

• Invalid request parameters, such as incorrect input format or missing required parameters.
• The request fails to reach the server successfully, such as due to network issues or gateway failures.
• The request is denied due to system rate limiting.

"G00000000817636816"

itemId

String

The record ID of the item.

Note: Please save the record ID as it is required for subsequent record inquiries, risk inquiries as well as record deletion.

"AIN20220727890204890950"

hasRisk

Boolean

Specifies whether risk exists.

• true: Risk exists
• false: No risk exists.

true

riskDetails

List<RiskDetail>

Risk details. For more information, see RiskDetail.

[ { "type":"IDFAKE", "subType":"SameFaceDifferentIdNumber", "riskData":[ "AIN20220727890199220364" ] }

allianceRiskDetails

List<RiskDetail>

Alliance risk details. For more information, see RiskDetail.

[ { "type":"IDFAKE", "subType":"SameFaceDifferentIdNumber", "riskData":[ "AIN20220727890976220364" ] }

Field

Data type

Description

Example

type

String

Risk type.

"IDFAKE"

subType

String

Sub-risk type.

"SameFaceDifferentIdNumber"

riskData

List<String>

Risk data with an itemId array.

["AIN20220727890199220364"]

riskDataDetails

List<RiskDataDetail>

Risk data details are available in RiskDataDetail.

[

{

"itemId": "AIN20220727890199220364",

"faceSimilarScore": "90.0"

}

]

Field

Data type

Description

Example

itemId

String

Optional. Risk itemId.

"AIN20220727890199220364"

faceSimilarScore

String

Optional. Face similarity score: the higher the score, the greater the similarity.

"90.0"