Enrol a face

Add a face to a collection so it can be searched for or recognised later.

POST /v1/face-embeddings/sync1 operation per face enrolled

Request

multipart/form-data, with your key as a bearer token.

Field	Type	Default	Description
imagerequired	file	—	An image containing one face.
unique_name	string	—	Your own identifier for this person. Use it to reconcile with your records.
full_name	string	—	Display name.
collection	string	default	Named collection to file this face under.
metadata	string	—	Free-form string stored alongside the face.
check_duplicate	boolean	true	Refuse the enrolment if this person is already in the collection.
duplicate_threshold	number	0.98	Match score above which a face counts as already enrolled.

Example

curl -X POST https://api.quantilence.com/v1/face-embeddings/sync \
  -H "Authorization: Bearer $QUANTILENCE_API_KEY" \
  -F "image=@photo.jpg" \
  -F "unique_name=alex-morgan" \
  -F "full_name=Alex Morgan" \
  -F "collection=default" \
  -F "metadata=" \
  -F "check_duplicate=true" \
  -F "duplicate_threshold=0.98"

Response

200 OK with this shape. Values below are illustrative; the keys and types are not.

{
  "success": true,
  "status": "enrolled",
  "face_id": 4127,
  "user_id": "8f14e45f-ceea-467a-9f2b-1c7d9c0a5e21",
  "collection": "staff",
  "image_filename": "alex.jpg",
  "crop_b64": "/9j/4AAQSkZJRg…",
  "embedding_dims": 512,
  "det_score": 0.938,
  "message": null,
  "duplicate": null
}

Field	Type	Description
success	boolean	Whether the request was handled.
status	string	`enrolled`, `duplicate_found`, `no_face` or `error`. Check this, not `success`.
face_id	integer \| null	The enrolled face's id.
user_id	string	The account it was filed under.
collection	string	Collection it went into.
image_filename	string	The filename you sent.
crop_b64	string \| null	Aligned crop of the enrolled face.
embedding_dims	integer \| null	Embedding size.
det_score	float \| null	Detector confidence.
message	string \| null	Human-readable detail.
duplicate	object \| null	The existing face, when one matched.

Worth knowing

Read `status`, not `success`. A duplicate or a face-less image returns 200 with `success: true` and a status that says what happened.
Enrolling the same person twice is refused by default — set `check_duplicate` to false only if you mean it.