Face · eKYC Core

Delete faces

POST/v1/delete_faces

Deletes the given image ids out of a face collection's index and returns the id of the request.

Request

MethodPOST
Path/v1/delete_faces
Content-Typeapplication/json
Auth requiredYes — HMAC signing
NameTypeRequiredDescription
image_ids[]stringRequiredimage IDs in DB. Should use indexed image. Omit when you send file_names
collectionstringOptionalindex faces to this collection
file_names[]stringOptionalfile names the images were indexed with, 1 to 100. Only with file-name tracking; see The file_names parameter
  • If not set collection, default collection will be used.
JSON
{
    "image_ids": []string,
    "collection": string,
    "file_names": []string,
}

The file_names parameter

file_names deletes faces by the file_name they were indexed with in Index faces, instead of by image ID. It is read only when TrustVision has enabled file-name tracking for your client or access key (setting require_file_name); otherwise image_ids stays required.

  • Send 1 to 100 names, none of them empty. Names are matched exactly as they were indexed.
  • Send file_names or image_ids, never both. Deleting by image_ids works as before.
  • Names are looked up in collection only (the default collection if it is not set).
  • The response lists in data.unknown_file_names the names that are not live in the collection: never indexed, indexed without a face, already deleted, or indexed in another collection. Every other name was found, and its faces are deleted. If no name is found, the call fails with 400 no image found for file_names.
  • Once its faces are deleted, a file name is free again and can be indexed with a new image.
JSON
{
    "file_names": ["IMG_20261101_0000123.jpg", "IMG_20261101_0000124.jpg"],
    "collection": "my_collection"
}

Sample request

curl -X POST \
'<BASE_URL>/v1/delete_faces' \
-H 'Authorization: TV <YOUR ACCESS KEY>:<CREATED SIGNATURE>' \
-H 'X-TV-Timestamp: 2019-04-21T18:00:15+07:00' \
-H 'Content-Type: application/json' \
-d \
'
{
    "image_ids": [
      "a4facba3-334b-41fb-97e3-4766cb70ae29",
      "7db00808-0416-45cf-a5cb-3b6dfbd7bb74"
    ]
}
'

Response

In case of success, the HTTP status code will be 200, and the data will be an object containing following fields:

fieldtypedescription
statusstring"success"
request_idstringID of the request (UUID)
unknown_file_names[]stringonly when deleting by file_names: the names not found in the collection, [] if all were found
JSON
{
    "data": {
        "status": string,
        "request_id": string,
        "unknown_file_names": []string, // only when deleting by file_names
    },
    "errors": [
        {
            "code": string,
            "message": string,
            "detail": {
                "field": string, // optional, which parameter is invalid.
                ... // any other information that can be useful for client
            },
        },
        ... // other errors
    ]
}

A successful delete comes back like this:

JSON
{
    "data": {
        "status": "success",
        "request_id": "d4493ff5-e41f-4d10-a291-6a9727050b4c"
    }
}

A delete by file_names in which one name was not found:

JSON
{
    "data": {
        "status": "success",
        "request_id": "d4493ff5-e41f-4d10-a291-6a9727050b4c",
        "unknown_file_names": ["IMG_20261101_0000124.jpg"]
    }
}

Failure codes

In case of error, the data will be empty, and the server sends one of the following HTTP status codes with an error code:

HTTP codeError codeDescription
400invalid_parameter_exceptionInput parameter violates a constraint.
400request_time_too_skewedThe X-TV-Timestamp header is expired, need a newer one.
401access_denied_exceptionYou are not authorized to perform the action.
404image_not_found_exceptionThe image ID is not found in DB.
408request_timeout_exceptionRequest takes too long to process.
429rate_limit_exceptionThe number of requests exceeded your throughput limit.
500internal_server_errorSome unexpected error occurs while processing the request.

When deleting by file_names, these 400 invalid_parameter_exception errors can occur. The message is exact:

messagedetailCause
no image found for file_names{"field": "file_names"}No name of the call is live in the collection. Nothing is deleted.
image_ids and file_names cannot be used together{"field": "file_names"}Both image_ids and file_names are set.
file_names cannot contain an empty name{"field": "file_names"}file_names holds "".
number faces delete must be less than 100noneMore than 100 names. 100 is accepted.
parameter is required{"field": "image_ids"}Neither image_ids nor file_names is set, or file-name tracking is off.

The codes above are the ones documented for this endpoint. Response errors lists the codes for the eKYC Core surface as a whole — the two lists do not match on every endpoint.