Blacklist - Get Item API

2026-05-28 01:47

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.

POST /api/v1/zoloz/blacklist/getitem

This API is used to get the details of an existing blacklist item.

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.
itemType	String	8	Required. Specify the type of the item to be retrieved. Valid values include: FACE DEVICE CERT
itemId	String	64	Required. The ID of the item to be retrieved.

Response parameters

Field name	Data type	Description
result	Result	Contains the result code, result status, and a result message.
itemId	String	Available if the item is retrieved successfully.
itemType	String	Available if the item is retrieved successfully.
itemStatus	String	Available if the item is retrieved successfully. Valid values include: ACTIVE DELETED
listId	String	Available if the item is retrieved successfully. ID of the list in which this item belongs to.
base64ImageContent	String	Available if the item is retrieved successfully, and itemType is FACE.
deviceId	String	Available if the item is retrieved successfully, and itemType is DEVICE.
docType	String	Available if the item is retrieved successfully, and itemType is CERT.
docNumber	String	Available if the item is retrieved successfully, and itemType is CERT.
sourceTransactionId	String	Available if the item is retrieved successfully.
gmtCreated	Date	Available if the item is retrieved successfully. The date and time when this item was first created.
gmtModified	Date	Available if the item is retrieved successfully. The date and time when this item was last modified.

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_ITEM_NOT_FOUND	F	The requested item does not exist.
SYSTEM_ERROR	F	Other internal 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 request to retrieve the details of a FACE item.

copy
{
  "bizId": "some-random-biz-id",
  "itemId": "86451b883c80372",
  "itemType": "FACE"
}

Response Sample

Here is an example when item is found.

copy
{
  "result":{
    "resultCode":"SUCCESS",
    "resultMessage":"Success",
    "resultStatus":"S"
  },
  "itemId":"86451b883c80372",
  "itemStatus":"ACTIVE",
  "itemType":"FACE",
  "listId":"1",
  "base64ImageContent":"/9j/4AAxxxxxxx",
  "sourceTransactionId":"1646971102303",
  "gmtCreated":1646971104006,
  "gmtModified":1646971104006
}

Here is another example when the item is not found.

copy
{
  "result":{
    "resultCode":"BLACKLIST_ITEM_NOT_FOUND",
    "resultMessage":"item 86451b883c80372 of type FACE is not found.",
    "resultStatus":"F"
  }
}