Face · Standard API · eKYC Core

Verify portrait

POST/v1/verify_portrait_sanity_sync

Checks the sanity of a portrait image and returns a verdict — good, or the first quality issue found — with a confidence score.

Request

MethodPOST
Path/v1/verify_portrait_sanity_sync
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.

NameTypeRequiredDescription
imagestringRequiredportrait image. if use TS SDK, use last frontal image
selfie_typestringOptionalSpecify the characteristic of a disabled face or liveness mode eg. disabled eye, passive, active, flash
  • If you use base64, label and metadata, omit parameter id.
  • If you use id (result id is returned from Upload Image API), omit parameter base64, label and metadata.
JSON
{
    "image": {
        "id": string,
        "base64": string,
        "label": string,
        "metadata": string_json,
    },
    "selfie_type": string,
}

Which image's parameters contains:

keytyperequireddescription
idstringOptionalID of image is returned from API Upload
base64stringOptionalbase64 encoded text of image data
labelstringOptionallabel of the image as described at Label table
metadatastring_jsonOptionalkey-value string, key should be string, value should be string, int, float, bool. Example "{\"id\":\"123456789\",\"type\":1}"

The selfie_type parameter

selfie_type names the liveness mode the capture used, and is defined as one of the table values below.

selfie_typedescription
id_cardPortrait image in Chip NFC of CCCD
lightLight Authen
passiveStandard Authen
activeAdvanced Authen use active liveness (gestures)
flashAdvanced Authen uses full flash liveness
flash_8Edge Authen uses flash liveness with 8 frames
flash_16Edge Authen uses flash liveness with 16 frames
flash_32Advanced Authen uses flash liveness with 32 frames
flash_edgeEdge Authen uses flash liveness with minimum time
flash_advancedAdvanced Authen uses full flash liveness

Sample request

curl -X POST \
https://tv-staging.trustingsocial.com/api/v1/verify_portrait_sanity_sync \
-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": "7db00808-0416-45cf-a5cb-3b6dfbd7bb74"
    }
}
'

Response

data.portrait_sanity carries the verdict and a score between 0 and 1 for how much confidence there is in it. 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"
        "portrait_sanity": { // only return the first issue found if any
            "verdict": string, // "good" or some alerts, see below.
            "score": float, // range 0-1, how much confidence about the verdict
        },
        "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
    ]
}

Possible data.portrait_sanity.verdict is good or one of the following values corresponding to each check:

verdictsupported countries
image_too_blurvietnam, india, philippines
image_too_darkvietnam, india, philippines
image_too_brightvietnam, india, philippines
face_too_darkvietnam, india, philippines
face_too_brightvietnam, india, philippines
image_has_no_facesvietnam, india, philippines
image_has_multiple_facesvietnam, india, philippines
not_white_backgroundindia
rightvietnam, india, philippines
leftvietnam, india, philippines
not_qualifiedvietnam, india, philippines
open_eye,closed_eyevietnam, india, philippines
closed_eye,open_eyevietnam, india, philippines
open_eye,sunglassesvietnam, india, philippines
sunglasses,open_eyevietnam, india, philippines
closed_eye,closed_eyevietnam, india, philippines
closed_eye,sunglassesvietnam, india, philippines
sunglasses,closed_eyevietnam, india, philippines
face_too_smallvietnam, india, philippines
face_too_bigvietnam, india, philippines

A portrait that passes every check comes back like this:

JSON
{
  "data": {
    "image": {
      "id": "4368143d-9066-4f3d-ab22-4e0b6dd9b274"
    },
    "portrait_sanity": {
      "score": 1,
      "verdict": "good"
    },
    "status": "success"
  }
}

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 codeError codeDescription
401access_denied_exceptionYou are not authorized to perform the action.
400invalid_parameter_exceptionInput parameter violates a constraint.
400request_time_too_skewedThe X-TV-Timestamp header is expired, need a newer one.
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

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.