Users

This API allows the generation of a faces collection on which to perform 1:N face recognition searches:

• Users faces inventory.
• Faces blacklist.
• Faces whitelist.

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/{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 or tokenized image of the user's face. For open images, 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/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 or tokenized image of the user's face. For open images, 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/{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