Face Authentication

Common objects & errors

The Face Authentication endpoints are built from a small set of shared request and response objects, and they fail the same way at the transport layer — all of it defined once, here, and referred to by name from each endpoint page.

Request objects

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.

image

One image. Register a face takes an array of them in faces and a single one in face_in_id_card; Authenticate takes an array in faces; gesture_image nests an array in images.

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.

gesture_image

One gesture together with the images captured for it. Register a face and Authenticate both take an array of them in gesture_faces.

video

One video. Register a face and Authenticate both take an array of them in videos; gesture_video nests an array in videos.

If you use id (result id is returned from Upload File API), omit parameter frames, metadata. If you use frames, metadata, omit parameter id.

FrameData

One frame of a video, for the case where frames are sent inline rather than by upload id.

gesture_video

One gesture together with the videos captured for it. Register a face and Authenticate both take an array of them in gesture_videos.

Enums

Gesture values

The values the gesture parameter accepts, on both gesture_image and gesture_video.

Response objects

history

One record of a past registration or authentication. Register a face, Authenticate and Check registration all return an array of them in data.histories.

face_auth_user

The user record as it stands after the call. Unregister returns it in data.face_auth_user as the user information after unregistration, and Unlock returns it as the user information after unlock.

Error envelope

Every response carries an errors array alongside data. When data.status is "failure" it tells you why the request failed; when the call failed before processing, data is empty and errors carries the transport error.

{
    "errors": [
        {
            "code": string,
            "message": string,
            "detail": {
                "field": string, // optional, which parameter is invalid.
                ... // any other information that can be useful for client
            },
        },
        ... // other errors
    ]
}

Each entry contains:

Shared transport errors

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. These are the same on every Face Authentication call.

A code that arrives with HTTP 200 and data.status: "failure" belongs to the endpoint that returned it, and is documented under Failure codes on that endpoint's own page.