Index Faces

Indexes the face in an image and adds it to a collection, building the searchable set that Search Faces queries for duplicates and blocklist hits.

Endpoint

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

{
  "image": {
    "id": "a4facba3-334b-41fb-97e3-4766cb70ae29",
    "base64": "",
    "label": "portrait",
    "metadata": "{}"
  },
  "enable_update_metadata": false,
  "collection": "default",
  "type": 0
}

Parameters:

Param	Type	Required	Default	Description
image	ImageData	Yes	—	Image containing the face to index. When using the TS SDK, pass the last frontal frame.
enable_update_metadata	bool	No	false	Allows image.metadata to be updated on an already-indexed image.
collection	string	No	default collection	Collection to index the face into. Case-sensitive.
type	int	No	—	Type of collection.

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: {"id":"<ID>","type":1}

Sample Request

curl -X POST \
  '<BASE_URL>/v1/index_faces_sync' \
  -H 'Authorization: ATV <ACCESS_ID>:<SIGNATURE>' \
  -H 'X-TV-Timestamp: <TIMESTAMP>' \
  -H 'Content-Type: application/json' \
  -d '{
    "image": {
      "id": "a4facba3-334b-41fb-97e3-4766cb70ae29"
    }
  }'

Response

{
  "success": true,
  "code": 0,
  "message": "success",
  "data": {
    "status": "success",
    "image": {
      "id": "a4facba3-334b-41fb-97e3-4766cb70ae29",
      "transformed_image_id": ""
    },
    "request_id": "dfdef016-e89b-4da4-ae17-5844f909c947"
  },
  "errors": []
}

Field	Type	Description
data.status	string	success or failure.
data.image.id	string	ID of the indexed image.
data.image.transformed_image_id	string	ID of the transformed image, present only when the image was transformed.
data.request_id	string	Request ID; quote it to CAKE Support when checking logs.

WARNING

Indexing enrols a biometric template that persists until you delete it. Index only after the customer has consented and the onboarding has been approved, and use Delete Faces to honour erasure requests.

Errors

Code	Message
2001010	Access ID not found.
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.
5001000	Some unexpected error occurs while processing the request.

Code	Description
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.
image_not_found_exception	The image ID is not found in DB.
request_not_found_exception	The request ID is not found when polling result by id.
request_timeout_exception	Request takes too long to process.
rate_limit_exception	The number of requests exceeded your throughput limit.
internal_server_error	Some unexpected error occurs while processing the request.

Next Steps

• Search Faces — query the collection you just added to
• Delete Faces — remove an indexed face