Face Authentication

Check registration

POST/v1/face_auth_user

Reports whether a customer is already registered for face authentication, and returns their registration history.

Request

MethodPOST
Path/v1/face_auth_user
Content-Typeapplication/json
Auth requiredYes — HMAC signing
NameTypeRequiredDescription
cus_user_idstringRequiredUser id of customer
JSON
{
    "cus_user_id": string
}

Sample request

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

Response

data.verdict carries the answer — "registered" or "not_registered". When processing finishes, the HTTP status code is 200 and data.status is either "success" or "failure" depending on whether the request was processed successfully, so a 200 says the lookup ran, not that the customer is registered. Each entry in histories is a history record, and the errors array follows the shared error envelope.

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.

A customer registered with both a selfie and an ID card face, with one successful and one failed registration attempt in their history:

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

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

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