risk query

2025-05-07 07:14

Overview

API URL：/api/v1/zoloz/idnetwork/risk/query
API Description: Provides the capability to query the risks associated with a record.

Structure

Request parameters

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.	"1658905294198"
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"
itemId	String	64	null	Optional. The record ID to be queried; this is the ID of the data record returned by the IDN when it is passed in. Note: If the value of the itemId field is passed in, the detailed data will be automatically extracted from the database, and the content passed in the imageInfo and basicInfo fields will no longer be used.	"AIN20220707717226249562"
checkAllianceRisk	String	–	N	Optional. Specifies whether to check the affiliate risk. `Y`: Check affiliate merchants at the same time. `N`: Only the current merchant is checked.	“N”
riskDetection	RiskDetection	–	-	Required. The risk to be queried. For details, see RiskDetection.	{ "riskTypes":[ "IDFAKE", "DUPLICATE", "DEEPFAKE", "BATCH_REGISTER" ], "timeWindow":{ "startTime":1651882535687, "endTime":1658902665000 } }
imageInfo	imageInfo	–	null	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.	{ "idType":"00000001003", "idNumber":"46082119870811896X", "certName":"Tom", "dateOfBirth":"19870811" }
scene	String	32	kyc	Optional： kyc，Indicates the authentication scenario. verification，Representing a 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"

RiskDetection

Field	Data type	Max length	Default Value	Description	Example
riskTypes	List<String>	-	-	Required. 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

TimeWindow

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

ImageInfo

Note:

Currently, only faceImage fields are supported. docImage fields are not supported by the system at the moment.
Image size should not exceed 5MB.
The picture format should be base64.

Field	Data type	Max length	Default Value	Description	Example
docImage	String	-	null	Optional. The ID image to be passed in (this field is not support at the moment).	"eA3AW/6dxn6QAAAABJRU5ErkJggg==..."
faceImage	String	-	null	Optional. The face image to be passed in.	"p+AY/b2OF/F1CxAAAAAElFTkSuQmCC..."

BasicInfo

Field	Data type	Max length	Default Value	Description	Example
idType	String	32	null	Optional. Specifies the document type. For more information, 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"

Response parameters

Parameters	Data type	Description	Example
result	Result	API request result with result status, result code and result message.	{ "resultStatus":"S", "resultCode":"SUCCESS", "resultMessage":"Success" }
transactionId	String	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"
hasRisk	Boolean	Specifies whether risk exists. `true`: Risk exists. `false`: No risk exists.	true
riskDetails	List<RiskDetail>	Risk details present in the current merchant. 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" ] }

RiskDetail

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" } ]

RiskDataDetail

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"

Samples

Request sample

copy
POST /api/v1/zoloz/idnetwork/risk/query HTTP/1.1
Content-Type: application/json; charset=UTF-8
Client-Id: 5X67656YXXXXXX
Request-Time: 2023-05-05T15:08:56+05:30
Signature: algorithm=RSA256, signature=xxxxxxxxxxxx

# Use itemId to query risks 
{
  "bizId":"1658905294198",
  "itemId":"AIN20220707717226249562",
  "riskDetection":{
    "riskTypes":[
      "IDfake",
      "DUPLICATE",
      "BATCH_REGISTER",
      "DEEPFAKE"
        ],
      "riskThreshold":1
        }
}

# Use local data to query risks
{
  "bizId":"1658904703520",
  "riskDetection":{
    "riskTypes":[
      "IDfake",
      "DUPLICATE",
      "BATCH_REGISTER",
      "DEEPFAKE"
        ],
      "riskThreshold":1
  },
  "imageInfo":{
    "docImage":"eA3AW/6dxn6QAAAABJRU5ErkJggg==...",
    "faceImage":"p+AY/b2OF/F1CxAAAAAElFTkSuQmCC..."
  },
  "basicInfo":{
    "idType":"00000001003",
    "idNumber":"46082119870811896X",
    "certName":"Tom",
    "dateOfBirth":"19870811"
  }
}

Response sample

copy
HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8
Response-Time: 2023-05-05T15:08:56+05:30
Signature: algorithm=RSA256, signature=xxxxxxxxxxxxxxxxxx

{
  "result":{
    "resultStatus":"S",
    "resultCode":"SUCCESS",
    "resultMessage":"Success"
  },
  "transactionId":"G00000000xxxxxxx",
  "hasRisk":true,
  "riskDetails":[
    {
      "type":"IDFAKE",
      "subType":"SameFaceDifferentIdNumber",
      "riskData":[
        "AIN20220727890199220364"
      ],
      "riskDataDetails":[
   {
      "itemId": "AIN20220727890199220364", 
      "faceSimilarScore": "90.0"
   }
      ]
    },
    {
      "type":"IDFAKE",
      "subType":"SameIdDifferentFace",
      "riskData":[
        "AIN20220727890199220387",
        "AIN20220727890222174163"
      ]
    },
    {
      "type":"BATCH_REGISTER",
      "subType":"SameFaceBackgroundDifferentFace",
      "riskData":[
        "AIN20220727890862716253",
        "AIN20220727899872658271"
       ]
    }
  ],
  "allianceRiskDetails":[
    {
      "type":"IDFAKE",
      "subType":"SameFaceDifferentIdNumber",
      "riskData":[
        "AIN20220727890976220364"
      ]
    },
    {
      "type":"IDFAKE",
      "subType":"SameIdDifferentFace",
      "riskData":[
        "AIN20220727890199220387",
        "AIN20220727890222174163"
      ]
    },
    {
      "type":"BATCH_REGISTER",
      "subType":"SameFaceBackgroundDifferentFace",
      "riskData":[
        "AIN20220727890862716253",
        "AIN20220727899872658271"
       ]
    }
  ]
}