Users Blacklist

This API allows the generation of a users faces shared blacklist on which to perform 1:N face recognition searches.

note

Blacklist functionality is designed to share a list of faces to detect and block among a set of clients.

In case of finding matches for a provided face, only the client who has initially registered that face will receive in the response the user identifier assigned in the enrollment, the rest of the clients with access to that list will only receive the similarity score.

Only the client who has registered a face (associated with a user ID) will be able to perform the deletion.

Supported operations are:

• Enroll: new user face registration.
• Search: 1:N search of faces within the collection.
• Unenroll: user deregistration.

Enroll

User enrollment request:

curl --location '{IDENTITY_API_BASE_URL}/users/blacklist/{USER_ID}' \
--header 'x-api-key: {API_KEY}' \
--header 'Content-Type: application/json' \
--data '{
    "face": "{FACE_IMAGE}"
}'

Request parameters:

Field	Required	Description
USER_ID	Yes	ID for the UserID to be created. This ID needs to be unique within the collection.
FACE_IMAGE	Yes	Base64 encoded image of the user's face. Supported formats are JPEG and PNG. The maximum supported size is 5MB.

Sample successful response:

200 OK

Unsuccessful sample responses:

Scenario: Duplicated user ID.

400 Bad Request

Content-Type: application/json

{
    "status": 400,
    "title": "Bad Request",
    "detail": "Invalid request.",
    "type": "https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400",
    "errors": [
        "provided userId already exists"
    ]
}

Scenario: Invalid face image.

400 Bad Request

Content-Type: application/json

{
    "status": 400,
    "title": "Bad Request",
    "detail": "Invalid request.",
    "type": "https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400",
    "errors": [
        "no face detected in the provided image"
    ]
}

Search

User search request:

curl --location '{IDENTITY_API_BASE_URL}/users/blacklist/search' \
--header 'x-api-key: {API_KEY}' \
--header 'Content-Type: application/json' \
--data '{
    "face": "{FACE_IMAGE}",
    "threshold": {THRESHOLD},
}'

Request parameters:

Field	Required	Description
FACE_IMAGE	Yes	Base64 encoded image of the user's face. Supported formats are JPEG and PNG. The maximum supported size is 5MB.
THRESHOLD	No	Optional value specifying the minimum confidence in the face match to return. For example, don't return any matches where confidence in matches is less than 75,5%. The default value is 80%. Ejemplo de valor esperado para 75,5%: 75.5

Sample successful response:

200 OK

Content-Type: application/json

{
    "matches": [
        {
            "userId": "f7eab18f-e5d3-4dac-9d4d-cfb969ef848e",
            "similarity": 99.99953
        }
    ]
}

Unsuccessful sample responses:

Scenario: user not found.

404 Not Found

Content-Type: application/json

{
    "status": 404,
    "title": "Not Found",
    "detail": "Server cannot find the requested resource.",
    "type": "https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/404"
}

Unenroll

User deregistration request:

curl --location --request DELETE '{IDENTITY_API_BASE_URL}/users/blacklist/{USER_ID}' \
--header 'x-api-key: {API_KEY}'

Request parameters:

Field	Required	Description
USER_ID	Yes	ID for the UserID to be deleted.

Sample successful response:

200 OK