Add Item

2024-01-08 13:33

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: `FACE`: face blacklist. When itemType is `FACE`, add this item to blacklist via sourceTransactionId or base64ImageContent. `DEVICE`: device blacklist. When itemType is `DEVICE`, add this item to blacklist via sourceTransactionId or deviceId. `CERT`: document blacklist. When itemType is `CERT`, add this item to blacklist via sourceTransactionId or docType and docNumber.
base64ImageContent	String	5MB	Optional. Specify the face image to be added when itemType is `FACE`. 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	Optional. Specify the device ID to be added when itemType is `DEVICE`. The device ID must be captured by ZOLOZ SDK, otherwise, the search and match might fail.
docType	String	16	Optional. Specify the type of document to be added when itemType is `CERT`. To understand the list of supported values, please check supported doc types Document types supported and OCR results returned.
docNumber	String	32	Optional. Specify the number of the document to be added when itemType is `CERT`. 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	Optional. Description

Response parameters

Field name	Data type	Description
result	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.

copy
{
  "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.

copy
{
  "result":{
    "resultCode":"BLACKLIST_IMAGE_DENIED",
    "resultMessage":"Similar image(s) found in existing blacklist.",
    "resultStatus":"F"
  },
  "relatedItems":[
    "{\"itemId\":\"86451b883c80372a1ccc85dc2fdae2cd\",\"itemType\":\"FACE\"}"
  ]  
}