Face · Standard API · eKYC Core
Verify faces suspicious
Retrieves the fraudsters matching the faces in an image from a defined collection, each with a similarity score and metadata, plus a summary blacklist verdict.
Request
Clients can provide image data to the TrustVision API by specifying the ID the image by using upload API, or by sending the image data as base64-encoded text.
| Name | Type | Required | Description |
|---|---|---|---|
image | ImageData | Required | image to index face. Should use image has the face |
- If you use
base64,labelandmetadata, omit parameterid. - If you use
id(resultidis returned from Upload Image API), omit parameterbase64,labelandmetadata. - Priority order is
id, (base64,label)
{
"image": {
"id": string,
"base64": string,
"label": string,
"metadata": string_json,
},
}
Sample request
curl -X POST \
https://tv-staging.trustingsocial.com/api/v1/verify_faces_suspicious \
-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": {
"id": "a4facba3-334b-41fb-97e3-4766cb70ae29"
}
}
'
Response
data.faces holds one array of matched faces per face found in the input image, and data.face_blacklist_check summarises the match. In case the request processing has been finished, the HTTP status code will be 200, and the data.status is either "success" or "failure" depending on whether the request has been successfully processed or not.
{
"data": {
"request_id": string,
"status": string, // "success" or "failure"
"faces": [ support search multiple faces. Each array is result of each face
[
{
"id": string, // id of the face in image
"image_id": string, // id of original image
"score": float, // score similar between 2 faces
"metadata": // list of meta data information of this face
{
"field": string, // application_id, national_id, ...
"value": primitive_type, // when index key=value then the value should a primitive type as string, int, float, boolean
},
... // other fields
},
... // other face matched of first face in image
],
[
... // list face matches of another face in image
],
],
"face_blacklist_check": { // summary matching result
"type": string, // type of image
"matched": bool, // true, false
"num_matched_faces": int // number of matched faces,
"is_hit_blacklist": bool // true if hit blacklist
"is_hit_suspicious": bool // true if hit suspicious
}
},
"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 face that hit the suspicious list comes back like this:
{
"data": {
"status": "success",
"image": {
"id": "2a5b80da-d093-4987-9711-9c7eb1b42a4d",
"faces": [
{
"id": "37d45f39-80f0-4361-8ce0-129cea184994",
"bounding_box": {
"top": 615,
"left": 231,
"bottom": 1006,
"right": 550,
"angle": 0
}
}
]
},
"faces": [
[
{
"id": "0a195b20-d5a8-472a-ac02-3c5465689a1a",
"image_id": "2a5b80da-d093-4987-9711-9c7eb1b42a4d",
"score": 1,
"metadata": [
{
"field": "date_of_birth",
"value": "1984/01/06"
},
{
"field": "full_name",
"value": "name1"
},
{
"field": "image_id",
"value": "2a5b80da-d093-4987-9711-9c7eb1b42a4d"
},
{
"field": "is_blacklisted",
"value": false
},
{
"field": "nid_number",
"value": "000506544743"
},
{
"field": "nid_type",
"value": "vn.cccd_new"
}
]
}
]
],
"face_blacklist_check": {
"type": "id_cards_blacklist",
"matched": true,
"num_matched_faces": 1
"is_hit_suspicious": true
}
}
}
Failure codes
If the data.status is "failure", the "errors" field will tell you why it failed.
In case of any other errors, the data field will be empty, and the server sends one of following HTTP status code with error code:
| HTTP code | Error code | Description |
|---|---|---|
401 | access_denied_exception | You are not authorized to perform the action. |
400 | invalid_parameter_exception | Input parameter violates a constraint. |
400 | request_time_too_skewed | The X-TV-Timestamp header is expired, need a newer one. |
404 | image_not_found_exception | The image ID is not found in DB. |
404 | request_not_found_exception | The request ID is not found when polling result by id |
408 | request_timeout_exception | Request takes too long to process |
429 | rate_limit_exception | The number of requests exceeded your throughput limit. |
500 | internal_server_error | Some unexpected error occurs while processing the request |
The codes above are the ones documented for this endpoint. Response errors on the Overview lists the codes for the eKYC Core surface as a whole — the two lists do not match on every endpoint.