Add Item
POST /api/v1/zoloz/blacklist/additem
This API is used to add an item to a target blacklist.
Structure
Request parameters
Field name | Data type | Max length | Description |
bizId | String | 32 | Required. A unique ID maintained by client for tracing purpose. Note: ZOLOZ server does not perform uniqueness check on this field. For better tracing, it is strongly recommended to enable the merchant server to guarantee the uniqueness of the business ID. |
listId | String | 32 | (Optional) Specify the ID of the target blacklist, into which this item will be added. If the parameter value is left blank, ZOLOZ will add the item to the default blacklist. |
itemType | String | 8 | Required. Specify the type of item to be added. Valid values include:
|
base64ImageContent | String | 5MB | Required when itemType is FACE. Specify the face image to be added. The face image should be in JPEG format. Face image needs to be of good quality and face features should be visible. |
deviceId | String | 128 | Required when itemType is DEVICE. Specify the device ID to be added. The device ID must be captured by ZOLOZ SDK, otherwise, the search and match might fail. |
docType | String | 16 | Required when itemType is CERT. Specify the type of document to be added. To understand the list of supported values, please check supported doc types here. |
docNumber | String | 32 | Required when itemType is CERT. Specify the number of the document to be added. Please note that ZOLOZ match document with target document blacklist by combining both docType and docNumber. |
sourceTransactionId | String | 64 | (Optional) Specify the original source of the item. If the item to be added is obtained from a history ZOLOZ transaction, It is recommended that client to set history transaction ID for this parameter for tracing purposes |
description | String | 64 | description |
Response parameters
Field name | Data type | Description |
result | Contain the result code, result status, and a result message. | |
itemId | String | (Optional) only available if the item is added successfully. |
relatedItems | List<String> | (Optional) If the item is not added due to duplicates, a list of existing items will be returned. Each item is represented as a JSON String, which contains itemId and itemType. |
Result
Common result codes
For the full list of common result codes, see the Common error codes section in the Error handling topic.
API-specific result codes
The following table shows the possible result codes that are specific for this API.
resultCode | resultStatus | Description |
SUCCESS | S | The API call is successful. |
INVALID_ARGUMENT | F | Input parameters are invalid. For more information about which parameter is invalid, check the result message or the related log. |
BLACKLIST_LIST_NOT_FOUND | F | The target blacklist does not exist. |
BLACKLIST_IMAGE_DENIED | F | Only applicable when itemType is FACE. The error message occurs when the image is not accepted by ZOLOZ. To understand rejection details, you can check the result message. |
SYSTEM_ERROR | F | Other system errors. For more information about the error details, check the result message that is returned and the related log. |
Sample
Request sample
Here is an example of request, which is trying to add a selfie face to the default FACE list.
{
"bizId":"add-face-item-bizid",
"itemType":"FACE",
"base64ImageContent":"/9j/4Axxxxxxxx",
"sourceTransactionId":"G1647337311928"
}Response Sample
The following sample response will be returned when the face is already blacklisted.
{
"result":{
"resultCode":"BLACKLIST_IMAGE_DENIED",
"resultMessage":"Similar image(s) found in existing blacklist.",
"resultStatus":"F"
},
"relatedItems":[
"{\"itemId\":\"86451b883c80372a1ccc85dc2fdae2cd\",\"itemType\":\"FACE\"}"
]
}