Overview
eKYC Platform
Face Authentication
Overview
Integration Use Case
API Docs
Vision Score
Behavioral Biometric (BehavioIQ)
SIM Verification
Mule Account Database
eKYC Core
Demo Apps
Download SDKs
Privacy Policy
FAQ

TrustVision API Documentation v1.0.0

Face Authentication API

Face Authentication lets a customer register their face once, then re-authenticate against that registration for subsequent logins or transactions. The typical lifecycle is: register a customer's face (face_auth_register), authenticate against it on future sessions (face_auth), check whether a customer is already registered (face_auth_user), and unregister or unlock the account when needed.

Request face authentication registration

1. Request

Method	Path	Content-Type	Auth Required
POST	`/v1/face_auth_register`	application/json	Yes

Request Body:

JSON

{
    "cus_user_id": string,
    "faces": [
        {
            "id": string,
            "base64": string,
            "label": string,
            "metadata": string_json,
        }
    ],
    "gesture_faces":[
        {
            "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
            ],
        },
        ... // other videos
    ],
    "gesture_videos": [
        {
            "gesture": string,
            "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
                    ],
                },
                ... // other videos
            ]
        },
        ... // other gesture videos
    ],
    "face_in_id_card": {
        "id": string,
        "base64": string,
        "label": string,
        "metadata": string_json,
    },
    "device_id": string,
    "app_id": string,
    "lat": float,
    "lng": float,
    "face_type": string,
    "selfie_type": string,
    "history_return_count": int,
    "history_return_status": string,
    "metadata": json_object,
    "face_priority": string
}

Where

Name	Type	Required	Description	Max Length
`cus_user_id`	string	Yes	user id of customer	256
`faces`	[]image	No	images of the selfie	50
`gesture_faces`	[]gesture_image	No	array of gestures contain images	50
`videos`	[]video	No	array of videos selfie	50
`gesture_videos`	[]gesture_video	No	array of videos gesture	50
`face_in_id_card`	image	No	image of the face in id_card
`device_id`	string	No	device id of user	256
`app_id`	string	No	app id of customer	128
`lat`	float	No	latitude of device
`lng`	float	No	longitude of device
`face_type`	string	No	type of face input (`selfie`, `id_card`)
`selfie_type`	string	No	specify the characteristic of authentication type eg. Light, Standard, Edge, Advanced, NFC	64
`history_return_count`	int	No	number of history registration records to return
`history_return_status`	string	No	status of history registration records to return (`success`, `failure` or `all`)
`metadata`	json_object	No	any key-value metadata to store with this customer
`face_priority`	string	No	type of face (`selfie` or `id_card`) to prioritize when perform face authen (override default setting)

Which each image's parameters contains:

Name	Type	Required	Description
`id`	string	No	ID of image is returned from API Upload
`base64`	string	No	base64 encoded text of image data
`label`	string	No	label of the image as described at Label table
`metadata`	string_json	No	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	Yes	specify a gesture value as below table. Example `left`, `right`, `up` or `down`
`images`	[]image	Yes	an array of images for each gesture

Which gesture parameter contains value:

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

Which each video's parameters contains:

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

Which FrameData's parameters contains:

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

Which each gesture_video's parameters contains:

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

Which `selfie_type` parameter is defined as below table values

`selfie_type`	Description
`id_card`	Portrait image in Chip NFC of CCCD

Note:

The parameter face_in_id_card or faces is required. you have to specify at least one
For parameter type image, if you use id (result id is returned from Upload Image API), omit parameter base64, label and metadata. If you use base64, label and metadata, omit parameter id.
For parameter type 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 parameter face_type is not specified, the default value is selfie.
If you want to register face from ID card (e.g. face extracted while reading NFC of Citizen ID Card), you have to either:
- Pass the face to faces param and specify face_type and selfie_type as id_card.
- Or pass the face to face_in_id_card (no need to specify face_type or selfie_type).
To register both face from ID card and selfie, please pass the selfie face to faces param and the face from ID card to face_in_id_card param.

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/face_auth_register \
-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 \
'
{
    "cus_user_id": "3b4bf7b6-088b-4931-9279-9259f5c34fe3",
    "faces": [
        {
            "id": "a4facba3-334b-41fb-97e3-4766cb70ae29"
        },
        {
            "id": "c5a2a405-f152-4248-b746-3af76b241ef7"
        },
        {
            "id": "5d0345f7-da7c-44e8-bd6c-a8c08c806227"
        }
    ],
    "gesture_faces": [
        {
            "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": "61801fcd-b109-49f7-b871-ae82c2a666cc",
        },
        {
            "id": "1f93d229-7f1c-44f9-a85b-1be4c2d4be41",
        }
    ],
    "face_type": "selfie",
    "metadata": {
        "key1": {
          "key11": "value11",
          "key12": "value12"
        },
        "key2": "value2"
    }
}
'

2. Response

The response will be a JSON with following format:

JSON

{
    "data": {
        "status": string, // "success" or "failure"
        "request_id": string, // return request id to the client and can use request-id to check logs.
        "user_metadata": json_object, // return user metadata
        "register_id": string, // id of this registration request
        "histories": [
            {
                "id": string, // id of this history
                "client_id": string, // client id
                "cus_user_id": string, // user id
                "face_auth_id": string, // id of selfie image containing user's face
                "id_card_face_id": string, // id of id card image containing user's face
                "live_face_id": string, // id of input image for this registration request
                "device_id": string, // device id input for this registration request
                "app_id": string, // app id input for this registration request
                "latitude": float, // latitude input for this registration request
                "longitude": float, // longitude input for this registration request
                "created_at": string, // time of this registration request
                "auth_action": string, // "register"
                "status": string, // "success" or "failure"
                "result": string, // detail result of this registration request
                "metadata": json_object, // metadata input for this registration request
                "face_type": string, // type of face input for this registration request ("selfie", "id_card")
            },
            ... // other history
        ]
    },
    "errors": [
        {
            "code": string,
            "message": string,
            "detail": {
                "field": string, // optional, which parameter is invalid.
                ... // any other information that can be useful for client
            },
        },
        ... // other errors
    ]
}

The expiry_date of selfie face will be returned in user_metadata field as expiry_date_face in RFC3339 format.

In case the request processing has been finished successfully, 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
`face_auth_user_deactivated`	the user is deactivated

In case of any other errors, the data field will be empty, and the server sends one of the following HTTP status codes with an 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.
`400`	`incorrect_number_of_faces`	Selfie or original image have more than 1 faces.
`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

Sample Response

JSON

{
    "data": {
        "status": "success",
        "request_id": "cfc7b8d5-f2e2-437b-80e5-d600dfad26e2",
        "user_metadata": {
            "key1": "value1",
            "key2": 2,
            "expiry_date_face": "2023-12-27T03:33:06.307977Z",
        },
        "register_id": "d4f99f9b-4862-437f-a9c9-608e050d06c6",
        "histories": [
            {
                "id": "f1ca6795-cbd4-4eec-821f-b4ac646db627",
                "client_id": "0ef0f7e9-7f2f-4767-84b8-f76da7701c46",
                "cus_user_id": "3b4bf7b6-088b-4931-9279-9259f5c34fe3",
                "face_auth_id": "",
                "id_card_face_id": "4f959f4a-f5de-4b50-8724-224e709d06c2",
                "live_face_id": "009161c9-9c89-4573-8119-8f513de4449c",
                "created_at": "2023-12-27T03:33:06.307977Z",
                "auth_action": "register",
                "status": "success",
                "result": "",
                "face_type": "selfie"
            },
            {
                "id": "8c23af95-aaa0-4448-bfba-68acce31236e",
                "client_id": "0ef0f7e9-7f2f-4767-84b8-f76da7701c46",
                "cus_user_id": "3b4bf7b6-088b-4931-9279-9259f5c34fe3",
                "face_auth_id": "",
                "id_card_face_id": "4f959f4a-f5de-4b50-8724-224e709d06c2",
                "live_face_id": "009161c9-9c89-4573-8119-8f513de4449c",
                "created_at": "2023-12-21T07:24:19.829484Z",
                "auth_action": "register",
                "status": "failure",
                "result": "image is not liveness",
                "face_type": "id_card"
            }
        ]
    }
}

Request face authentication

1. Request

Method	Path	Content-Type	Auth Required
POST	`/v1/face_auth`	application/json	Yes

Request Body:

JSON

{
    "cus_user_id": string,
    "client_transaction_id": string,
    "faces": [
        {
            "id": string,
            "base64": string,
            "label": string,
            "metadata": string_json,
        }
    ],
    "gesture_faces":[
        {
            "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
            ],
        },
        ...
    ],
    "gesture_videos": [
        {
            "gesture": string,
            "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
                    ],
                },
                ... // other videos
            ]
        },
        ... // other gesture videos
    ],
    "device_id": string,
    "app_id": string,
    "lat": float,
    "lng": float,
    "auth_type": string,
    "selfie_type": string,
    "history_return_count": int,
    "history_return_status": string,
    "metadata": json_object
}

Where

Name	Type	Required	Description	Max Length
`cus_user_id`	string	Yes	user id of customer	256
`faces`	[]image	Yes	images of the selfie	50
`gesture_faces`	[]gesture_image	No	array of gestures contain images	50
`videos`	[]video	No	array of videos selfie	50
`gesture_videos`	[]gesture_video	No	array of videos gesture	50
`device_id`	string	No	device id of user	256
`app_id`	string	No	app id of customer	128
`lat`	float	No	latitude of device
`lng`	float	No	longitude of device
`auth_type`	string	No	specify different authentication type (or different use-cases)	64
`client_transaction_id`	string	No	client transaction ID
`selfie_type`	string	No	specify the characteristic of authentication type eg. Light, Standard, Edge, Advanced	64
`history_return_count`	int	No	number of history authenticate records to return
`history_return_status`	string	No	status of history authenticate records to return (`success`, `failure` or `all`)
`metadata`	json_object	No	any key-value metadata to store with this login time

Which each image's parameters contains:

Name	Type	Required	Description
`id`	string	No	ID of image is returned from API Upload
`base64`	string	No	base64 encoded text of image data
`label`	string	No	label of the image as described at Label table
`metadata`	string_json	No	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	Yes	specify a gesture value as below table. Example `left`, `right`, `up` or `down`
`images`	[]image	Yes	an array of images for each gesture

Which gesture parameter contains value:

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

Which each video's parameters contains:

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

Which FrameData's parameters contains:

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

Which each gesture_video's parameters contains:

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

Define flow based on parameters

The `auth_type` parameter is defined for each use-case differently

auth_type	description
`reset_password`	Authenticate to reset password flow
`login`	Use face to replace text password
`payment`	Authenticate payment
`transfer`	Authenticate transfer
`transfer_type_A`	Authenticate transfer type A
`transfer_type_B`	Authenticate transfer type B
`transfer_type_C`	Authenticate transfer type C
`transfer_type_D`	Authenticate transfer type D
`...`	You can define any authentication type based on your business

The `selfie_type` parameter is defined as below table values

`selfie_type`	Description
`light`	Light Authen
`passive`	Standard Authen
`active`	Advanced Authen use active liveness (gestures)
`flash`	Advanced Authen uses full flash liveness
`flash_8`	Edge Authen uses flash liveness with 8 frames
`flash_16`	Edge Authen uses flash liveness with 16 frames
`flash_32`	Advanced Authen uses flash liveness with 32 frames
`flash_edge`	Edge Authen uses flash liveness with minimum time
`flash_advanced`	Advanced Authen uses full flash liveness

Note:

For parameter type image, if you use id (result id is returned from Upload Image API), omit parameter base64, label and metadata. If you use base64, label and metadata, omit parameter id.
For parameter type 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.

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/face_auth \
-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 \
'
{
    "cus_user_id": "3b4bf7b6-088b-4931-9279-9259f5c34fe3",
    "faces": [
        {
            "id": "a4facba3-334b-41fb-97e3-4766cb70ae29"
        },
        {
            "id": "c5a2a405-f152-4248-b746-3af76b241ef7"
        },
        {
            "id": "5d0345f7-da7c-44e8-bd6c-a8c08c806227"
        }
    ],
    "gesture_faces": [
        {
            "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": "61801fcd-b109-49f7-b871-ae82c2a666cc",
        },
        {
            "id": "1f93d229-7f1c-44f9-a85b-1be4c2d4be41",
        }
    ],
    "metadata": {
        "key1": {
          "key11": "value11",
          "key12": "value12"
        },
        "key2": "value2"
    }
}
'

2. Response

The response will be a JSON with following format:

JSON

{
    "data": {
        "status": string, // "success" or "failure"
        "auth_check": {
            "score": float, // how likely that face1 and face2 are matched (0-1)
            "result": string // "matched", "unmatched"
        },
        "request_id": string, // return request id to the client and can use request-id to check logs.
        "user_metadata": json_object, // return user metadata
        "validate_faces_result": {
            "sanity_verdict": string, // portrait_sanity check result, if field not exist or value is "", it means portrait_sanity check is not performed
            "is_live": bool, // liveness check result, if field not exist or value is null, it means liveness check is not performed
            "sanity_check: {...}, // full sanity check response
            "liveness_check: {...} // full liveness check response
        },
        "auth_id": string, // id of this authentication request
        "histories": [
            {
                "id": string, // id of this history
                "client_id": string, // client id
                "cus_user_id": string, // user id
                "face_auth_id": string, // id of selfie image containing user's face
                "id_card_face_id": string, // id of id card image containing user's face
                "live_face_id": string, // id of input image for this login request
                "device_id": string, // device id input for this login request
                "app_id": string, // app id input for this login request
                "latitude": float, // latitude input for this login request
                "longitude": float, // longitude input for this login request
                "created_at": string, // time of this login request
                "auth_action": string, // "login"
                "status": string, // "success" or "failure"
                "result": string, // detail result of this login request
                "metadata": json_object, // metadata input for this login request
                "face_type": string, // type of face used to compare against the input face to authenticate ("selfie", "id_card")
            },
            ... // other history
        ]
    },
    "errors": [
        {
            "code": string,
            "message": string,
            "detail": {
                "field": string, // optional, which parameter is invalid.
                ... // any other information that can be useful for client
            },
        },
        ... // other errors
    ]
}

The expiry_date of selfie face will be returned in user_metadata field as expiry_date_face in RFC3339 format.

fields	description
`auth_check`	have `result` (matched/unmatched) and `score`

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

error code	description
`image_too_blur`	the input image is too blur
`image_too_dark`	the input image is too dark
`image_too_bright`	the input image is too bright (glare)
`image_has_no_faces`	the input image has no faces
`image_non_liveness`	the input image is not liveness
`face_auth_user_deactivated`	the user is deactivated
`face_auth_user_unregistered`	the user is unregistered from face_auth service
`face_auth_user_locked`	the user is locked from face_auth service

In case of any other errors, the data field will be empty, and the server sends one of the following HTTP status codes with an 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.
`400`	`incorrect_number_of_faces`	Selfie or original image have more than 1 faces.
`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
`404`	`face_auth_user_not_found_exception`	The user of face_auth service not found.
`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

Sample Response

JSON

{
    "data": {
        "status": "success",
        "auth_check": {
            "score": 0.9999999862517992,
            "result": "matched"
        },
        "request_id": "cfc7b8d5-f2e2-437b-80e5-d600dfad26e2",
        "user_metadata": {
            "key1": "value1",
            "key2": 2,
            "expiry_date_face": "2023-12-27T03:33:06.307977Z",
        },
        "validate_faces_result": {
            "sanity_verdict": "good",
            "is_live": true,
            "sanity_check": {
                "portrait_sanity": {
                    "score": 1,
                    "verdict": "good"
                },
                "request_id": "9f89377f-4bb4-4ecb-884c-f46f1d7d6099",
                "status": "success"
            },
            "liveness_check": {
                "images": null,
                "is_live": true,
                "request_id": "baee3d03-8af4-421b-8968-a0f6172b4df8",
                "score": 1,
                "status": "success"
            }
        },
        "auth_id": "d4f99f9b-4862-437f-a9c9-608e050d06c6",
        "histories": [
            {
                "id": "f1ca6795-cbd4-4eec-821f-b4ac646db627",
                "client_id": "0ef0f7e9-7f2f-4767-84b8-f76da7701c46",
                "cus_user_id": "3b4bf7b6-088b-4931-9279-9259f5c34fe3",
                "face_auth_id": "887249dc-681c-4231-aff9-67734833aca7",
                "id_card_face_id": "4f959f4a-f5de-4b50-8724-224e709d06c2",
                "live_face_id": "009161c9-9c89-4573-8119-8f513de4449c",
                "created_at": "2023-12-27T03:33:06.307977Z",
                "auth_action": "login",
                "status": "success",
                "result": "",
                "face_type": "selfie"
            },
            {
                "id": "8c23af95-aaa0-4448-bfba-68acce31236e",
                "client_id": "0ef0f7e9-7f2f-4767-84b8-f76da7701c46",
                "cus_user_id": "3b4bf7b6-088b-4931-9279-9259f5c34fe3",
                "face_auth_id": "",
                "id_card_face_id": "4f959f4a-f5de-4b50-8724-224e709d06c2",
                "live_face_id": "009161c9-9c89-4573-8119-8f513de4449c",
                "created_at": "2023-12-21T07:24:19.829484Z",
                "auth_action": "login",
                "status": "failure",
                "result": "image is not liveness",
                "face_type": "id_card"
            }
        ]
    }
}

Request check user of face authentication

This API checks whether a cus_user_id has been registered to the face_authentication system.

1. Request

Method	Path	Content-Type	Auth Required
POST	`/v1/face_auth_user`	application/json	Yes

Request Body:

JSON

{
    "cus_user_id": string
}

Where

Name	Type	Required	Description
`cus_user_id`	string	Yes	user id of customer

Authentication mechanism is described in Authentication.

Sample Request

bash

curl -X POST \
https://tv-staging.trustingsocial.com/api/v1/face_auth_user \
-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 \
'
{
    "cus_user_id": "3b4bf7b6-088b-4931-9279-9259f5c34fe3"
}
'

2. Response

The response will be a JSON with following format:

JSON

{
    "data": {
        "status": string, // "success" or "failure"
        "verdict" : string, // "registered" or "not_registered"
        "face_types": [string], // list of face types that user has registered (if verdict is "registered")
        "histories": [ // list of registration history if verdict is "registered"
            {
                "id": string, // id of this history
                "client_id": string, // client id
                "cus_user_id": string, // user id
                "face_auth_id": string, // id of selfie image containing user's face
                "id_card_face_id": string, // id of id card image containing user's face
                "live_face_id": string, // id of input image for this login request
                "device_id": string, // device id input for this login request
                "app_id": string, // app id input for this login request
                "latitude": float, // latitude input for this login request
                "longitude": float, // longitude input for this login request
                "created_at": string, // time of this login request
                "auth_action": string, // "register"
                "status": string, // "success" or "failure"
                "result": string, // detail result of this login request
                "metadata": json_object, // metadata input for this login request
                "face_type": string, // type of face used to compare against the input face to authenticate ("selfie", "id_card")
            },
            ... // other history
        ],
        "metadata": {
            ... // key-value if exists
        },
    },
    "errors": [
        {
            "code": string,
            "message": string,
            "detail": {
                "field": string, // optional, which parameter is invalid.
                ... // any other information that can be useful for client
            },
        },
        ... // other errors
    ]
}

The expiry_date of selfie face will be returned in metadata field as expiry_date_face in RFC3339 format.

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 the following HTTP status codes with an 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.
`400`	`incorrect_number_of_faces`	Selfie or original image have more than 1 faces.
`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
`404`	`face_auth_user_not_found_exception`	The user of face_auth service not found.
`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

Sample Response

JSON

{
    "data": {
        "status": "success",
        "verdict": "registered",
        "face_types": ["selfie", "id_card"],
        "histories": [
            {
                "id": "f1ca6795-cbd4-4eec-821f-b4ac646db627",
                "client_id": "0ef0f7e9-7f2f-4767-84b8-f76da7701c46",
                "cus_user_id": "3b4bf7b6-088b-4931-9279-9259f5c34fe3",
                "face_auth_id": "887249dc-681c-4231-aff9-67734833aca7",
                "id_card_face_id": "4f959f4a-f5de-4b50-8724-224e709d06c2",
                "live_face_id": "009161c9-9c89-4573-8119-8f513de4449c",
                "created_at": "2023-12-27T03:33:06.307977Z",
                "auth_action": "register",
                "status": "success",
                "result": "",
                "face_type": "selfie"
            },
            {
                "id": "8c23af95-aaa0-4448-bfba-68acce31236e",
                "client_id": "0ef0f7e9-7f2f-4767-84b8-f76da7701c46",
                "cus_user_id": "3b4bf7b6-088b-4931-9279-9259f5c34fe3",
                "face_auth_id": "",
                "id_card_face_id": "4f959f4a-f5de-4b50-8724-224e709d06c2",
                "live_face_id": "009161c9-9c89-4573-8119-8f513de4449c",
                "created_at": "2023-12-21T07:24:19.829484Z",
                "auth_action": "register",
                "status": "failure",
                "result": "image is not liveness",
                "face_type": "id_card"
            }
        ],
        "metadata": {
          "key": "value",
          "expiry_date_face": "2023-12-27T03:33:06.307977Z",
        }
    }
}

Request face authentication unregistration

1. Request

Method	Path	Content-Type	Auth Required
POST	`/v1/face_auth_unregister`	application/json	Yes

Request Body:

JSON

{
    "cus_user_id": string,
    "device_id": string,
    "app_id": string,
    "lat": float,
    "lng": float,
}

Where

Name	Type	Required	Description	Max Length
`cus_user_id`	string	Yes	user id of customer	256
`device_id`	string	No	device id of user	256
`app_id`	string	No	app id of customer	128
`lat`	float	No	latitude of device
`lng`	float	No	longitude of device

Authentication mechanism is described in Authentication.

Sample Request

bash

curl -X POST \
https://tv-staging.trustingsocial.com/api/v1/face_auth_unregister \
-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 \
'
{
    "cus_user_id": "3b4bf7b6-088b-4931-9279-9259f5c34fe3",
}
'

2. Response

The response will be a JSON with following format:

JSON

{
    "data": {
        "status": string, // "success" or "failure"
        "unregister_id": string, // id of this unregistration request
        "face_auth_user": { // user information after unregistration
            "id": string,
            "client_id": string,
            "access_key_id": string,
            "face_auth_id": string,
            "id_card_face_id": string,
            "cus_user_id": string,
            "device_id": string,
            "app_id": string,
            "latitude": float,
            "longitude": float,
            "metadata": json_object,
            "is_deactivated": bool,
            "is_unregistered": bool,
            "created_at": string_time,
            "updated_at": string_time
        }
    },
    "errors": [
        {
            "code": string,
            "message": string,
            "detail": {
                "field": string, // optional, which parameter is invalid.
                ... // any other information that can be useful for client
            },
        },
        ... // other errors
    ]
}

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 the following HTTP status codes with an 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.
`400`	`incorrect_number_of_faces`	Selfie or original image have more than 1 faces.
`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
`404`	`face_auth_user_not_found_exception`	The user of face_auth service not found.
`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

Sample Response

JSON

{
    "data": {
        "status": "success",
        "unregister_id": "d4f99f9b-4862-437f-a9c9-608e050d06c6",
        "face_auth_user": {
            "id": "f1ca6795-cbd4-4eec-821f-b4ac646db627",
            "client_id": "0ef0f7e9-7f2f-4767-84b8-f76da7701c46",
            "access_key_id": "c7d97b7c-f73d-4d62-973e-6eb3e0557ddf",
            "cus_user_id": "3b4bf7b6-088b-4931-9279-9259f5c34fe3",
            "face_auth_id": "",
            "id_card_face_id": "4f959f4a-f5de-4b50-8724-224e709d06c2",
            "live_face_id": "009161c9-9c89-4573-8119-8f513de4449c",
            "device_id": "",
            "app_id": "",
            "latitude": 1.0,
            "longitude": 2.0,
            "metadata": {
              "key1": "value1",
              "key2": 2
            },
            "is_deactivated": false,
            "is_unregistered": true,
            "created_at": "2023-12-27T03:33:06.307977Z",
            "updated_at": "2023-12-28T03:33:06.307977Z",
        }
    }
}

Request face authentication unlock

1. Request

Method	Path	Content-Type	Auth Required
POST	`/v1/face_auth_unlock`	application/json	Yes

Request Body:

JSON

{
    "cus_user_id": string,
}

Where

Name	Type	Required	Description	Max Length
`cus_user_id`	string	Yes	user id of customer	256

Authentication mechanism is described in Authentication.

Sample Request

bash

curl -X POST \
https://tv-staging.trustingsocial.com/api/v1/face_auth_unlock \
-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 \
'
{
    "cus_user_id": "3b4bf7b6-088b-4931-9279-9259f5c34fe3",
}
'

2. Response

The response will be a JSON with following format:

JSON

{
    "data": {
        "status": string, // "success" or "failure"
        "unlock_id": string, // id of this unlock request
        "face_auth_user": { // user information after unlock
            "id": string,
            "client_id": string,
            "access_key_id": string,
            "face_auth_id": string,
            "id_card_face_id": string,
            "cus_user_id": string,
            "device_id": string,
            "app_id": string,
            "latitude": float,
            "longitude": float,
            "metadata": json_object,
            "is_deactivated": bool,
            "is_unregistered": bool,
            "created_at": string_time,
            "updated_at": string_time
        }
    },
    "errors": [
        {
            "code": string,
            "message": string,
            "detail": {
                "field": string, // optional, which parameter is invalid.
                ... // any other information that can be useful for client
            },
        },
        ... // other errors
    ]
}

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 the following HTTP status codes with an 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.
`400`	`incorrect_number_of_faces`	Selfie or original image have more than 1 faces.
`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
`404`	`face_auth_user_not_found_exception`	The user of face_auth service not found.
`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

Sample Response

JSON

{
    "data": {
        "status": "success",
        "unlock_id": "d4f99f9b-4862-437f-a9c9-608e050d06c6",
        "face_auth_user": {
            "id": "f1ca6795-cbd4-4eec-821f-b4ac646db627",
            "client_id": "0ef0f7e9-7f2f-4767-84b8-f76da7701c46",
            "access_key_id": "c7d97b7c-f73d-4d62-973e-6eb3e0557ddf",
            "cus_user_id": "3b4bf7b6-088b-4931-9279-9259f5c34fe3",
            "face_auth_id": "",
            "id_card_face_id": "4f959f4a-f5de-4b50-8724-224e709d06c2",
            "live_face_id": "009161c9-9c89-4573-8119-8f513de4449c",
            "device_id": "",
            "app_id": "",
            "latitude": 1.0,
            "longitude": 2.0,
            "metadata": {
              "key1": "value1",
              "key2": 2
            },
            "is_deactivated": false,
            "is_unregistered": true,
            "created_at": "2023-12-27T03:33:06.307977Z",
            "updated_at": "2023-12-28T03:33:06.307977Z",
        }
    }
}

.css-9x8bsw{-webkit-text-decoration:none;text-decoration:none;}.css-9x8bsw:hover{-webkit-text-decoration:underline;text-decoration:underline;}Face Authentication API

Face Authentication API