Face · Standard API · eKYC Core

Face OTP

POST/v1/face_otp

Compares a newly taken selfie against the original image and returns a matched, unmatched or unsure verdict with a similarity score, alongside a liveness verdict for the selfie.

Request

MethodPOST
Path/v1/face_otp
Content-Typeapplication/json
Auth requiredYes — HMAC signing

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.

JSON
{
    "selfie": [{
        "id": string,
        "base64": string,
    }],
    "original": {
        "id": string,
        "base64": string
    }
}

Each image in selfie, and the original image, is given by:

keytyperequireddescription
idstringOptionalID of them image in DB
base64stringOptionalBase64 encoded text of image1 data
  • If you use base64, label and metadata (label and metadata of the image as described at Upload Image API), omit parameter id.
  • If you use id (result id is returned from Upload Image API), omit parameter base64, label and metadata.
  • Upto 3 selfie images can be provided all of them will be used for liveness verification, but only the first selfie image will be used for comparing faces
  • Atleast one selfie image should be provided
  • The original and the selfie image should not contain more than 1 face

Sample request

curl -X POST \
https://tv-staging.trustingsocial.com/api/v1/face_otp \
-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 \
'
{
    "selfie": [
        {
            "id": "7db00808-0416-45cf-a5cb-3b6dfbd7bb74"
        }
    ],
    "original": {
        "id": "a4facba3-334b-41fb-97e3-4766cb70ae29"
    }
}
'

Response

data.compare_faces carries the comparison verdict and data.is_live the liveness verdict for the selfie. 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.

JSON
{
    "data": {
        "status": string, // "success" or "failure"
        "is_live": bool, // the face is live or not
        "compare_faces": {
            "score": float, // how likely that face1 and face2 are matched (0-1)
            "result": string // "matched", "unmatched", "unsure"
        },
        "request_id": string // return request id to the client and can use request-id to check logs.
    },
    "errors": [
        {
            "code": string,
            "message": string,
            "detail": {
                "field": string, // optional, which parameter is invalid.
                ... // any other information that can be useful for client
            },
        },
        ... // other errors
    ]
}
fieldsdescription
is_livethe boolean to tell the selfie is live or not
compare_faceshave result (matched/unmatched) and score

A matched, live selfie comes back like this:

JSON
{
  "data": {
    "compare_faces": {
      "face1_id": "349ac5cd-2bd1-4bff-8c10-1cdacdd4c66d",
      "face2_id": "57263098-9c07-4220-888f-f8c4b73d4c1d",
      "result": "matched",
      "score": 0.9256071887745998
    },
    "is_live": true,
    "status": "success"
  },
  "errors": null
}

Failure codes

If the data.status is "failure", the "errors" field will tell you why it failed.

Error codeDescription
image_has_no_facethe input image has no faces
image_has_no_facesthe input image has no faces. (same with the above)
image_has_multiple_facesthe input image has multiple faces
image_too_blurthe input image is too blur
image_too_darkthe input image is too dark
image_too_brightthe input image is too bright (glare)
bad_quality_card_imagethe input image is bad quality
not_qualifiedthe input image is bad quality
not_white_backgroundthe image was not taken with a white background
face_too_darkthe face is too dark
face_too_brightthe face is too bright
face_too_smallthe face is too small
face_too_bigthe face is too big
rightthe face is turned right
leftthe face is turned left
open_eye,closed_eyethe face has eye(s) closed
closed_eye,open_eyethe face has eye(s) closed
open_eye,sunglassesthe face has sunglasses
sunglasses,open_eyethe face has sunglasses
closed_eye,closed_eyethe face has eye(s) closed
closed_eye,sunglassesthe face has sunglasses
sunglasses,closed_eyethe face has sunglasses
sunglasses,sunglassesthe face has sunglasses

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 codeError codeDescription
401access_denied_exceptionYou are not authorized to perform the action.
400invalid_parameter_exceptionInput parameter violates a constraint.
400incorrect_number_of_facesSelfie or original image have more than 1 faces.
404image_not_found_exceptionThe image ID is not found in DB.
404request_not_found_exceptionThe request ID is not found in Memory Cache and 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

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.