Blacklist - Blacklist Scan API

2026-06-25 06:23

Important Notice:

All request and response parameters are strictly subject to the official API documentation.
The API response may contain fields not defined in the documentation. These fields are for internal debugging purposes only and are not guaranteed to be stable or compatible. Do not rely on these fields in production environments. ZOLOZ reserves the right to modify or remove these fields at any time without prior notice.

Overview

API URL: /api/v1a/zoloz/blacklist/scan
API Description: Used to scan whether a specified user hits the blacklist. It supports simultaneous scanning of three types: Face (FACE), Document (CERT), and Device (DEVICE). It also supports automatic data retrieval through the transactionId from eKYC history records.

Request Parameters

Field Name	Data Type	Max Length	Mandatory	Default Value	Description	Example Value
bizId	String	32	true	-	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.	"2017839040588699"
userId	String	64	false	null	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.	"user123456"
itemTypes	List<String>	-	false	["FACE","CERT","DEVICE"]	List of blacklist types to scan. One or more types can be specified. Allowed values: `FACE`: Face blacklist `CERT`: Document blacklist `DEVICE`: Device blacklist Note: If not provided or an empty array is passed, all types are scanned by default.	["FACE", "CERT"]
sourceTransactionId	String	64	false	null	Specifies the source of the data to be scanned. You can pass in the ZOLOZ eKYC historical record ID (i.e., `transactionId`) of the current calling merchant. Once passed, the system will automatically retrieve the face image, document information, and device ID from the product record through reverse lookup. `sourceTransactionId` and direct-pass parameters (`base64ImageContent`, `docType`/`docNumber`, `deviceId`) can be used either alternatively or together. See Data Source and Parameter Passing Rules for details.	"G1647337311928"
base64ImageContent	String	5MB	false	null	Specifies the face image to scan when `itemTypes` includes `FACE`. The image must meet the following requirements: Encoding: Base64-encoded string Format: JPEG Quality: Good quality with visible facial features Note: When `sourceTransactionId` is also provided and a face image is retrieved, the retrieved result takes precedence.	"/9j/4Axxxxxxxx"
deviceId	String	128	false	null	Specifies the device ID to scan when `itemTypes` includes `DEVICE`. Notes: The device ID must be collected through the ZOLOZ SDK; otherwise, the query may fail. When `sourceTransactionId` is also provided and a device ID is retrieved, the retrieved result takes precedence.	"device_abc123"
docType	String	16	false	null	Specifies the document type to scan when `itemTypes` includes `CERT`. Supported document types, see Document types supported and OCR results returned. Note: When `sourceTransactionId` is also provided and a `docType` is retrieved, the retrieved result takes precedence.	"NATIONAL_ID"
docNumber	String	32	false	null	Specifies the document number to scan when `itemTypes` includes `CERT`. Note: When `sourceTransactionId` is also provided and a `docNumber` is retrieved, the retrieved result takes precedence.	"330100xxxx1234"

Data Source and Parameter Passing Rules

Data Source Overview

Each scan type has two data sources: Retrieval (higher priority) and Direct Pass (lower priority). They can be used either alternatively or together.

Scan Type	Data via Retrieval (Higher Priority)	Data via Direct Pass (Lower Priority)
FACE	Pass `sourceTransactionId` to automatically retrieve face image	Pass `base64ImageContent`
CERT	Pass `sourceTransactionId` to automatically retrieve document info (`docType` + `docNumber`)	Pass `docType` + `docNumber`
DEVICE	Pass `sourceTransactionId` to automatically retrieve device ID	Pass `deviceId`

Parameter Passing Methods and Validation Rules

The processing logic and validation rules vary depending on the parameter passing method.

Passing Method	Parameter Requirements	Processing Logic	Validation Rules	Retrieval Business Requirements
Retrieval + Direct Pass	Pass both `sourceTransactionId` and direct-pass parameters.	The system prioritizes data retrieved via sourceTransactionId. If retrieval fails for any data type, it automatically falls back to the corresponding direct-pass parameter for that type.	Not validated	The merchant to which the business data belongs must be consistent with the merchant making the current API call.
Retrieval Only	Pass only `sourceTransactionId`, no direct-pass parameters.	The system relies solely on data retrieved via `sourceTransactionId`.	Strict validation of business data status; both conditions must be met, otherwise `INVALID_ARGUMENT` is returned: Data has not been deleted due to privacy policy. Business status is `Success`, `Failure`, or `Pending`.
Direct Pass Only	Pass only direct-pass parameters, no `sourceTransactionId`.	The system uses the direct-pass parameters directly for scanning.	Not validated	None

Response Parameters

Field Name	Data Type	Description	Example Value
result	Result	Required. The result of the API request, including the operation status, result code, and message.	{ "resultCode": "SUCCESS", "resultMessage": "Success", "resultStatus": "S" }
transactionId	String	Optional. The unique transaction ID generated for this scan, which can be used for subsequent case queries. Returned only when the API call is successful.	"G1647337312000"
isScan	String	Optional. Indicates whether a scan was performed. Returned only when the API call is successful. `Y`: Scan performed, at least one type was scanned. `N`: No scan performed, the merchant has no blacklist data.	"Y"
blacklistResult	String	Optional. Blacklist scan result. Returned only when `isScan` is `Y`. `Success`: No blacklist hit `Failure`: Blacklist hit	"Failure"
blacklistDetails	Map<String, List<ScanItemResult>>	Optional. Hit details, grouped by scan type. The structure is defined in the BlacklistDetails section below. Returned only when `blacklistResult` is `Failure`. Note: When any scan type hits, all requested scan types will appear as keys in the result. Hit types: return the details list. Missed or skipped types: return an empty array.	See response examples below
scannedItemTypes	List<String>	Optional. The list of types that were actually scanned. Returned only when `isScan` is `Y`.	["FACE", "CERT"]

BlacklistDetails Structure

Field Name	Data Type	Description	Example Value
listId	String	Required. The ID of the hit blacklist.	"default_list"
relatedTransactionId	String	Optional. The source `transactionId` when the blacklist entry was created.	"G1647337311928"
itemId	String	Required. The ID of the hit blacklist entry.	"86451b883c80372a1ccc85dc2fdae2cd"
similarityScore	Double	Optional. Face similarity score. The higher the score, the more similar the faces. Returned only when the scan type is `FACE` and a hit occurs.	95.6

Result

API-Common Result Codes

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

API-Specific Result Codes

The following table lists result codes specific to the Blacklist Scan API.

resultCode	resultStatus	Description
SUCCESS	S	The API call is successful.
INVALID_ARGUMENT	F	Invalid request parameters. Please refer to the returned `resultMessage` for specific issues. Common causes include: General Parameter Errors: `bizId` is empty or not of type String `itemTypes` is not of type Array or contains unsupported blacklist types All scan types lack required parameters Retrieval Parameter Errors: Business data corresponding to `sourceTransactionId` has been deleted due to privacy policy (validated only when `sourceTransactionId` is used and no direct-pass parameters are provided) Business status corresponding to `sourceTransactionId` is invalid. Only `Success`, `Failure`, and `Pending` are allowed (validated only when `sourceTransactionId` is used and no direct-pass parameters are provided) Merchant of the business data corresponding to `sourceTransactionId` does not match the current caller
BLACKLIST_LIST_NOT_FOUND	F	The target blacklist does not exist.
BLACKLIST_IMAGE_DENIED	F	Applicable only when `itemTypes` includes `FACE`. This error is returned when the uploaded image has an invalid format, does not meet quality requirements, or exceeds the size limit. For details, please check the returned `resultMessage`.
SYSTEM_ERROR	F	Internal system error. For details, please check the returned `resultMessage`.

Sample

Request Sample

Sample 1: Retrieval Only (sourceTransactionId) – Scan All Types

This example automatically retrieves face, document, and device information through the eKYC transactionId and scans all blacklist types.

copy
{
    "bizId": "2017839040588699", 
    "sourceTransactionId": "G1647337311928"
}

Sample 2: Direct Pass Only – Scan Specified Types

This example directly passes face image and document information and scans only FACE and CERT blacklist types.

copy
{
    "bizId": "2017839040588699", 
    "userId": "user123456", 
    "itemTypes": [
        "FACE", 
        "CERT"
    ], 
    "base64ImageContent": "/9j/4Axxxxxxxx", 
    "docType": "NATIONAL_ID", 
    "docNumber": "330100xxxx1234"
}

Sample 3: Hybrid Mode (Retrieval + Direct Pass)

This example demonstrates the Retrieval + Direct Pass mode. It retrieves face and document information via sourceTransactionId, while also passing deviceId as a fallback for the device scan. The scan will prioritize the retrieved data and only use the direct-pass deviceId if the retrieval fails.

copy
{
    "bizId": "2017839040588699", 
    "sourceTransactionId": "G1647337311928", 
    "itemTypes": [
        "FACE", 
        "CERT", 
        "DEVICE"
    ], 
    "deviceId": "device_abc123"
}

Response Sample

Sample 1: Blacklist Hit

FACE type hit, CERT and DEVICE types not hit.

copy
{
    "result": {
        "resultCode": "SUCCESS", 
        "resultMessage": "Success", 
        "resultStatus": "S"
    }, 
    "transactionId": "G1647337312000", 
    "isScan": "Y", 
    "blacklistResult": "Failure", 
    "scannedItemTypes": [
        "FACE", 
        "CERT", 
        "DEVICE"
    ], 
    "blacklistDetails": {
        "FACE": [
            {
                "listId": "default_list", 
                "relatedTransactionId": "G1647337311928", 
                "itemId": "86451b883c80372a1ccc85dc2fdae2cd", 
                "similarityScore": 95.6
            }
        ], 
        "CERT": [ ], 
        "DEVICE": [ ]
    }
}

Sample 2: No Blacklist Hit

copy
{
    "result": {
        "resultCode": "SUCCESS", 
        "resultMessage": "Success", 
        "resultStatus": "S"
    }, 
    "transactionId": "G1647337312001", 
    "isScan": "Y", 
    "blacklistResult": "Success", 
    "scannedItemTypes": [
        "FACE", 
        "CERT"
    ]
}

Sample 3: No Scan Performed (Merchant Has No Blacklist Data)

copy
{
    "result": {
        "resultCode": "SUCCESS", 
        "resultMessage": "Success", 
        "resultStatus": "S"
    }, 
    "transactionId": "G1647337312002", 
    "isScan": "N"
}

Sample 4: Retrieval Failed Due to Privacy Policy Deletion

When data is retrieved solely through sourceTransactionId but the history record has been deleted due to privacy policy, the system returns an INVALID_ARGUMENT error.

copy
{
    "result": {
        "resultCode": "INVALID_ARGUMENT", 
        "resultMessage": "The case has been deleted for privacy reasons", 
        "resultStatus": "F"
    }
}

Sample 5: Missing bizId

copy
{
    "result": {
        "resultCode": "INVALID_ARGUMENT", 
        "resultMessage": "bizId is mandatory", 
        "resultStatus": "F"
    }
}