Update Face Authen

Replaces the images enrolled in an existing face profile. Use it when a user's appearance has changed enough to hurt match rates, or to re-enrol after a poor initial capture.

Endpoint

POST /v1/update_face_auth
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. At least one is required.
device_id	string	No	—	The user's device ID, shown in face auth history on the admin portal.
app_id	string	No	—	The app the customer used, shown in face auth history.
lat	string	No	—	Latitude of the device used for this update.
lng	string	No	—	Longitude of the device used for this update.
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.
metadata	json_object	No	—	Any key-value metadata to store with this customer.

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.

Returns: UpdateFaceAuthResponse

Sample Request

curl -X POST \
  '<BASE_URL>/v1/update_face_auth' \
  -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" }
    ],
    "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"
    }
  },
  "errors": [],
  "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 belongs to.
data.face_auth.status	string	Profile status after the update.

WARNING

Updating replaces the biometric template every future authentication is matched against. Gate this endpoint behind a strong authentication of its own — an attacker who can call it for another user's user_id can enrol their own face and take over the account.

Errors

Update runs the same quality and matching gate as registration:

Code	Message
2001003	Image sent to the server has no faces.
2001006	Faces detected from images sent to the server are not matched.
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.
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.
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.
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.

Unlike registration, update has no user_already_registered or face_already_registered failure — the profile is expected to exist.

Next Steps

• Get Face Authen — confirm the profile status afterwards
• Delete Face Authen — remove the profile instead of replacing it