Register Faces

Enrols a user's face profile, the template every later authentication is matched against. Registration runs sanity, liveness and cross-image matching checks before the profile is created.

Endpoint

POST /v1/face_auth_register
Content-Type: application/json

{
  "user_id": "user_00000001",
  "faces": [
    { "id": "a4facba3-334b-41fb-97e3-4766cb70ae29" }
  ],
  "device_id": "device_00000001",
  "app_id": "app_00000001",
  "lat": "10.7769",
  "lng": "106.7009",
  "face_type": "selfie",
  "metadata": { "key2": "value2" }
}

Parameters:

Param	Type	Required	Default	Description
user_id	string	Yes	—	User ID of the customer.
faces	ImageData[]	Yes	—	Images of the user's selfie, or a document containing a selfie photo such as an ID card front. At least one is required.
device_id	string	No	—	The user's device ID, so face auth history shows which device performed the registration on the admin portal.
app_id	string	No	—	The app the customer used, so face auth history shows which app performed the registration.
lat	string	No	—	Latitude of the device used for this registration.
lng	string	No	—	Longitude of the device used for this registration.
face_type	string	No	selfie	Type of face input: selfie or id_card. Use id_card for a face extracted from a Citizen ID card, for example while reading its NFC chip.
metadata	json_object	No	—	Any key-value metadata to store with this customer. Nested objects are allowed.

ImageData

Param	Type	Required	Default	Description
id	string	No	—	ID of the image returned by Upload Image.
base64	string	No	—	Base64-encoded text of the image data.
label	string	No	—	Label of the image, as described in Usage Recommendations.
metadata	string_json	No	—	Key/value JSON string. Example: {"gesture":"left","type":1}

Supply either id or base64, never both. CAKE recommends id over base64.

INFO

faces is required — send at least one; a registration with no faces has nothing to enrol.

Returns: RegisterFacesResponse

Sample Request

curl -X POST \
  '<BASE_URL>/v1/face_auth_register' \
  -H 'Authorization: ATV <ACCESS_ID>:<SIGNATURE>' \
  -H 'X-TV-Timestamp: <TIMESTAMP>' \
  -H 'Content-Type: application/json' \
  -d '{
    "user_id": "user_00000001",
    "faces": [
      { "id": "a4facba3-334b-41fb-97e3-4766cb70ae29" },
      { "id": "c5a2a405-f152-4248-b746-3af76b241ef7" },
      { "id": "5d0345f7-da7c-44e8-bd6c-a8c08c806227" }
    ],
    "face_type": "selfie",
    "device_id": "device_00000001",
    "app_id": "app_00000001",
    "lat": "10.7769",
    "lng": "106.7009",
    "metadata": {
      "key1": { "key11": "value11", "key12": "value12" },
      "key2": "value2"
    }
  }'

Response

{
  "data": {
    "status": "success",
    "request_id": "cfc7b8d5-f2e2-437b-80e5-d600dfad26e2",
    "face_auth": {
      "user_id": "user_00000001",
      "status": "VERIFIED"
    }
  },
  "success": true,
  "code": 0,
  "message": "Success"
}

Field	Type	Description
data.status	string	success or failure.
data.request_id	string	Request ID; quote it to CAKE Support when checking logs.
data.face_auth.user_id	string	The user ID the profile was created for.
data.face_auth.status	string	Profile status, e.g. VERIFIED.

WARNING

A face template is biometric data. Register only with the customer's consent, and use Delete Face Authen to honour erasure requests.

Errors

Registration surfaces the quality and matching failures that rejected the enrolment:

Code	Message
2001003	Image sent to the server has no faces.
2001006	Faces detected from images sent to the server are not matched.
2001008	Face has been registered on the system.
2001009	Image sent to the server has multiple faces.
2001010	Access ID not found.
2001011	Verify selfie / id_card liveness failed.
2001012	Verify selfie / id_card sanity failed.
2001014	Register rate limit exceeded.
2001015	Register brute force limit exceeded.
2001025	Selfie image sent to the server has length not equal to configuration.
2001026	Images sent to server are duplicated.
401100	You are not authorized to perform the action.
4001000	Input parameter violates a constraint.
4001001	The X-TV-Timestamp header is expired, need a newer one.
4001002	Selfie or original image have more than 1 faces.
4041000	The image ID is not found in DB.
4041001	User not found.
4091000	The user_id has been registered.
4131000	The input image size exceeds the allowed limit (15MB).
4151000	The provided image format is not supported (JPG/PNG).
4291000	The number of requests exceeded your throughput limit.
5001000	Some unexpected error occurs while processing the request.

Code	Description
access_id_not_found	Access ID not found.
register_rate_limit_exceeded	Register rate limit exceeded.
register_brute_force_limit_exceeded	Register brute force limit exceeded.
access_denied_exception	You are not authorized to perform the action.
invalid_parameter_exception	Input parameter violates a constraint.
request_time_too_skewed	The X-TV-Timestamp header is expired, need a newer one.
incorrect_number_of_faces	Selfie or original image have more than 1 faces.
image_not_found_exception	The image ID is not found in DB.
user_already_registered	The user_id has been registered.
image_too_large_exception	The input image size exceeds the allowed limit (15MB).
invalid_image_format_exception	The provided image format is not supported (JPG/PNG).
rate_limit_exception	The number of requests exceeded your throughput limit.
duplicated_image	Images sent to server are duplicated.
selfie_image_invalid	Selfie image sent to the server has length not equal to configuration.
sanity_check_failed	Verify selfie / id_card sanity failed.
liveness_check_failed	Verify selfie / id_card liveness failed.
image_has_no_faces	Image sent to the server has no faces.
image_has_multiple_faces	Image sent to the server has multiple faces.
face_already_registered	Face has been registered on the system.
compare_faces_not_matched	Faces detected from images sent to the server are not matched.
internal_server_error	Some unexpected error occurs while processing the request.

face_already_registered and user_already_registered are different failures: the first means that face belongs to another profile, the second means this user_id already has one.

Next Steps

• Verify Face Authen — authenticate against the profile you just created
• Update Face Authen — replace the enrolled faces later