Face Authentication

Register a face

POST/v1/face_auth_register

Registers a customer's face — from a selfie, the face on their ID card, or both — so later sessions can authenticate against it.

Request

MethodPOST

Path/v1/face_auth_register

Content-Typeapplication/json

Auth requiredYes — HMAC signing

Clients can provide image data to the TrustVision API by specifying the ID of the image from the upload API, or by sending the image data as base64-encoded text.

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

Either 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.

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
}

The `selfie_type` parameter

Set selfie_type when the face you are registering is not an ordinary selfie — passing an ID-card face through faces needs it, alongside face_type.

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

Sample request

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"
    }
}
'

data.status carries the verdict, not the HTTP status: when processing finishes the status code is 200 and data.status is then either "success" or "failure", depending on whether the request has been successfully processed or not. Each entry in histories is a history record, and errors follows the shared error envelope.

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.

A registration that went through, returning two history records:

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"
            }
        ]
    }
}

Failure codes

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 an HTTP status code with an error code instead.

Transport, auth and rate-limit errors are the same on every call — see Common objects & errors.

PreviousAuthentication NextAuthenticate

.css-9x8bsw{-webkit-text-decoration:none;text-decoration:none;}.css-9x8bsw:hover{-webkit-text-decoration:underline;text-decoration:underline;}Request

The selfie_type parameter

Sample request

Response

Failure codes

Request

The `selfie_type` parameter