About TrustVision
FAQ
API Call Flow
Standard API
Customized API

Android SDK
Flutter SDK
React Native SDK
iOS SDK
Web SDK
API Client Libraries
Integration Case Studies
Demo App
Privacy Policy

TrustVision API Documentation v1.0.0

Customized API

List of APIs

Mix Compare faces between 2 images

1. Request

Client should call this API:

method	URL	content-type
POST	`/v1/mix_compare_faces_sync`	`application/json`

Body:

{
    "image1": {
        "id": string,
        "base64": string,
        "label": string,
        "metadata": json,
    },
    "image2": {
        "id": string,
        "base64": string,
        "label": string,
        "metadata": json,
    }
}

Where:

key	type	required	description
`image1`	ImageData	yes	image of the identity card's front side
`image2`	ImageData	yes	image of the selfie

Which each image's parameters contains:

key	type	required	description
`id`	string	no	ID of them image in DB
`base64`	string	no	Base64 encoded text of image data
`label`	string	no	label of the image
`metadata`	dictionary	no	any key-value metadata to save with the image, both key and value should be string

Note:

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.

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.

Authentication mechanism is described in Authentication.

Sample Request

bash

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

2. Response

The response will be a JSON with following format:

{
    "data": {
        "status": string, // "success" or "failure"
        "transaction_id": string, // optional
        "image1": {
            "id": string,
            "transformed_image_id": string // optional, just in case the image is transformed
            "faces": [
                {
                    "id": string, // id of the face in image1
                    "bounding_box": {
                        "top": int, // the top edge of the box
                        "right": int, // the right edge of the box
                        "bottom": int, // the bottom edge of the box
                        "left": int, // the left edge of the box
                        "angle": int // the angle at which the box is rotated
                    }
                },
                ... // other faces in image1
            ],
        },
        "image2": {
            "id": string,
            "transformed_image_id": string // optional, just in case the image is transformed
            "faces": [
                {
                    "id": string, // id of the face in image2
                    "bounding_box": {
                        "top": int, // the top edge of the box
                        "right": int, // the right edge of the box
                        "bottom": int, // the bottom edge of the box
                        "left": int, // the left edge of the box
                        "angle": int // the angle at which the box is rotated
                    }
                },
                ... // other faces in image2
            ],
        },
        "compare_faces": [
            {
                "face1_id": string, // id of the face in image1
                "face2_id": string, // id of the face in image2
                "score": float, // how likely that face1 and face2 are matched (0-1)
                "result": string // "matched", "unmatched", "unsure"
            },
            ... // other pair of faces in image1 and image2
        ],
        "portrait_sanity": { // only return the first issue found if any
            "verdict": string, // good, image_too_blur, image_too_dark, image_too_bright, not_white_background, not_qualified, image_has_multiple_faces, image_has_no_faces, right, left, "open_eye,closed_eye", "closed_eye,open_eye", "open_eye,sunglasses", "sunglasses,open_eye", "closed_eye,closed_eye", "closed_eye,sunglasses", "sunglasses,closed_eye", "sunglasses,sunglasses"
            "score": float, // range 0-1, how much confidence about the verdict
        },
        "card_sanity": { // only return the first issue found if any
            "verdict": string, // good, image_too_blur, image_too_dark, image_too_bright, image_has_hole, image_has_cut, image_has_hole_and_cut
            "score": float, // range 0-1, how much confidence about the verdict
        },
        "liveness_check": {
            "is_live": bool, // the face is live or not
            "score": float // how likely that the face is live (0-1)
        },
    },
    "errors": [
        {
            "code": string,
            "message": string,
            "detail": {
                "field": string, // optional, which parameter is invalid.
                ... // any other information that can be useful for client
            },
        },
        ... // other errors
    ]
}

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.

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

error code	description
`image_has_no_faces`	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.
`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`	`request_not_found_exception`	The request ID is not found in Memory Cache and DB.
`429`	`rate_limit_exception`	The number of requests exceeded your throughput limit.
`500`	`internal_server_error`	Some unexpected error occurs while processing the request

Sample Response

JSON

{
    "data": {
        "status": "success",
        "compare_faces": [
            {
                "face1_id": "abdba678-b680-4b62-bc4b-d9b8fb37e8e4",
                "face2_id": "d43bf504-f1a3-4799-9bda-e5709ae7aa69",
                "result": "matched",
                "score": 0.7381135644418032
            },
            {
                "face1_id": "ae7a6cd2-4f5b-45b3-955f-844b1bc6d95a",
                "face2_id": "d43bf504-f1a3-4799-9bda-e5709ae7aa69",
                "result": "unmatched",
                "score": 0.5098310116475188
            }
        ],
        "image1": {
            "faces": [
                {
                    "bounding_box": {
                        "angle": 0,
                        "bottom": 446,
                        "left": 357,
                        "right": 550,
                        "top": 172
                    },
                    "id": "abdba678-b680-4b62-bc4b-d9b8fb37e8e4"
                },
                {
                    "bounding_box": {
                        "angle": 0,
                        "bottom": 530,
                        "left": 57,
                        "right": 254,
                        "top": 263
                    },
                    "id": "ae7a6cd2-4f5b-45b3-955f-844b1bc6d95a"
                }
            ],
            "id": "f3f6f8b5-2ac0-4734-a4b5-836c6c300b0b",
            "transformed_image_id": ""
        },
        "image2": {
            "faces": [
                {
                    "bounding_box": {
                        "angle": 0,
                        "bottom": 369,
                        "left": 504,
                        "right": 559,
                        "top": 296
                    },
                    "id": "d43bf504-f1a3-4799-9bda-e5709ae7aa69"
                }
            ],
            "id": "639058a6-0631-4bfd-a718-bc72c2695daf",
            "transformed_image_id": ""
        },
        "portrait_sanity": {
            "score": 1,
            "verdict": "good"
        },
        "card_sanity": {
            "score": 1,
            "verdict": "good"
        },
        "liveness_check": {
            "is_live": true,
            "score": 0.9999999862517992
        }
    }
}

Read ID card info with sanity

The read id card api or ocr (optical character recognition) takes image_id as the input. Main function of this service is to extract text from supported legal documents. It also detects the location of the id card inside the uploaded image.