Vision Score via eKYC Core · Vision Score

Vision Score

POST/v1/vision_score

Scores a customer's trustworthiness and risk profile from their selfie images, returning an overall vision score and a score for each image.

Authentication

Vision Score is called through the eKYC Core API, so it uses that API's HMAC request signing — there is no separate Vision Score credential. See Authentication mechanism for how to construct the signature.

Request

MethodPOST

Path/v1/vision_score

Content-Typeapplication/json

Auth requiredYes — HMAC signing

Vision Score generates a comprehensive score from facial data, enabling businesses to quickly validate identity, confirm liveness, and enhance fraud prevention during the onboarding process.

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
`images`	`[]image`	Required	array of frontal image object contains properties as described at ImageData. Active liveness: 2-4 images, Passive: 1-3 images.
`gesture_images`	`[]gesture_image`	Optional	array of gestures contain images. Active liveness: 3 images, Passive: no gesture image.
`videos`	`[]video`	Optional	array of video recording when liveness on SDK. Default 1
`metadata`	dictionary	Optional	the collected data during liveness checking process
`selfie_type`	string	Optional	Specify the characteristic of a disabled face or liveness mode eg. disabled eye, passive, active, flash

For image, 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.
For video, if you use id (result id is returned from Upload File API), omit parameter frames, metadata. If you use frames, metadata, omit parameter id.
If you use gesture_images, the images parameter should have at least 2 images and gesture in gesture_images should have at least left or right.

Every entry in images, and every entry in a gesture's own images, is an ImageData object:

JSON

{
    "images": [
        {
            "id": string,
            "base64": string,
            "label": string,
            "metadata": string_json,
        },
        {
            "id": string,
            "base64": string,
            "label": string,
            "metadata": string_json,
        }
    ],
    "gesture_images":[
        {
            "gesture": string,
            "images": [
                {
                        "id": string,
                        "base64": string,
                        "label": string,
                        "metadata": string_json,
                    },
                    {
                        "id": string,
                        "base64": string,
                        "label": string,
                        "metadata": string_json,
                    }
            ],
        }
    ],
    "videos": [
        {
            "id": string,
            "metadata": string_json,
            "frames": [
                {
                    "base64": string,
                    "label": string,
                    "index": int,
                    "metadata": string_json,
                },
                {
                    "base64": string,
                    "label": string,
                    "index": int,
                    "metadata": string_json,
                },
                // other frames
            ],
        },
        {
            "id": string,
            "metadata": string_json,
            "frames": [
                {
                    "base64": string,
                    "label": string,
                    "index": int,
                    "metadata": string_json,
                },
                {
                    "base64": string,
                    "label": string,
                    "index": int,
                    "metadata": string_json,
                },
                // other frames
            ],
        }
    ],
    "metadata": dictionary
}

Which each video's parameters contains:

Name	Type	Required	Description
`id`	string	Optional	ID of video is returned from API Upload
`metadata`	string_json	Optional	key-value string, key should be string, value should be string, int, float, bool. Example `"{\"id\":\"123456789\",\"type\":1}"`
`frames`	`[]FrameData`	Optional	list of video frames to be uploaded

Which FrameData's parameters contains:

Name	Type	Required	Description
`base64`	string	Optional	base64 encoded text of image data
`label`	string	Optional	label of the image as described at Label table
`index`	int	Optional	the index of this frame in the video
`metadata`	string_json	Optional	key-value string, key should be string, value should be string, int, float, bool. Example `"{\"id\":\"123456789\",\"type\":1}"`

Which each gesture_image's parameters contains:

Name	Type	Required	Description
`gesture`	string	Required	specify a gesture value as below table. Example `left`, `right`, `up` or `down`
`images`	`[]image`	Required	an array of images for each gesture

Which gesture parameter contains value:

`gesture`	Description
`left`	the face turns left
`right`	the face turns left
`up`	the face up
`down`	the face down

The `selfie_type` parameter

selfie_type names the liveness mode, and for the flash modes how many frames the capture carries.

`selfie_type`	Description
`passive`	Passive mode
`active`	Active mode
`flash`	Flash mode with 32 frames
`flash_8`	Flash mode with 8 frames
`flash_16`	Flash mode with 16 framess
`flash_32`	Flash mode with 32 frames

Sample request

curl -X POST \
https://tv-staging.trustingsocial.com/api/v1/vision_score \
-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 \
'
{
    "images": [
        {
            "id": "a4facba3-334b-41fb-97e3-4766cb70ae29"
        },
        {
            "id": "c5a2a405-f152-4248-b746-3af76b241ef7"
        },
        {
            "id": "5d0345f7-da7c-44e8-bd6c-a8c08c806227"
        }
    ],
    "gesture_images": [
        {
            "gesture": "left",
            "images": [
                {
                    "id": "d849a3ce-d209-4605-99a7-3d369234fd5e"
                }
            ]
        },
        {
            "gesture": "up",
            "images": [
                {
                    "id": "551fc06a-14fd-44dc-8838-abe895007c36"
                }
            ]
        },
        {
            "gesture": "right",
            "images": [
                {
                    "id": "536d2457-bfc0-4249-85f2-8c4053bdec58"
                }
            ]
        }
    ],
    "videos": [
        {
            "id": "433331b5-e1d4-433f-84e6-2260ec6bee92"
        },
        {
            "id": "3b4bf7b6-088b-4931-9279-9259f5c34fe3"
        }
    ]
}
'

Response

data.persona_attributes.vision_score carries the score, a float on a 0-100 range, and each entry in data.images carries a score on the same range — up to 3 images. A 200 only means the request finished processing; data.status is what says whether it succeeded, and it is either "success" or "failure".

The response will be a JSON with following format, in the shared response envelope:

JavaScript

{
    "data": {
        "status": string, "success" or "failure"
        "persona_attributes": {
            "vision_score": float // range (0-100)
        },
        "images": [
            {
                "id": string, // ID of the image
                "score": float // range (0-100)
            },
            ... // up to 3 images
        ],
        "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
    ]
}

A successful scoring comes back like this:

JSON

{
    "data": {
        "details": null,
        "images": [
            {
                "id": "0e33129a-c9ec-4e22-bf53-78d496bb1f37",
                "score": 95
            }
        ],
        "request_id": "93029850-924c-465a-baa6-27d843cbb1ba",
        "status": "success",
        "persona_attributes": {
          "vision_score": 95
        }
    }
}

Failure codes

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

Error code	Description
`image_has_no_face`	the input image has no faces

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.
`413`	`image_too_large_exception`	The input image size exceeds the allowed limit (15MB).
`415`	`invalid_image_format_exception`	The provided image format is not supported (JPG/PNG)
`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.
`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 lists the codes for the eKYC Core surface as a whole — the two lists do not match on every endpoint.

NextVision Score