API Reference

Face Enrollment

Face enrollment registers a person into a collection so they can later be verified or identified. Each enrolled face is linked to an external_id (your own user or record identifier) and optional JSON metadata.

Enroll a face

Submit a multipart/form-data request with the image file, an external ID, and optional metadata. The API automatically handles face detection and quality checks before storing the face.

curl -X POST https://api.livexface.com/api/v1/collections/COLLECTION_ID/faces \
  -H "X-API-Key: YOUR_API_KEY" \
  -F "[email protected]" \
  -F "external_id=user_alice_001" \
  -F 'metadata={"name":"Alice Smith","department":"Engineering"}'

JSON

{
  "success": true,
  "data": {
    "id": "dc3e7a57-22d5-4271-b707-213e49c8fe54",
    "collectionId": "9f1c2b7e-3d84-4a16-8c55-0b7e2a1d6f30",
    "externalId": "user_alice_001",
    "metadata": {"name": "Alice Smith", "department": "Engineering"},
    "imageUrl": "faces/9f1c2b7e-.../dc3e7a57-....jpg",
    "createdAt": "2026-09-20T10:05:00Z"
  }
}

Request parameters

Parameter	Type	Required	Description
image	file	Yes	JPEG/PNG image. Min 100×100px, max 10MB.
external_id	string	Yes	Your identifier for this person (e.g. user UUID).
metadata	JSON string	No	Arbitrary key-value data returned with matches.
check_liveness	boolean	No	Run liveness check before enrolling (default: true).

Quality checks

Before storing a face the API evaluates image quality — blur, occlusion, extreme pose — and rejects anything below the threshold with FACE_QUALITY_TOO_LOW.

Liveness is checked only if the collection asks for it. With Require liveness at enrolment switched on, a face that does not pass is refused with SPOOF_DETECTED and nothing is stored. With it off — the default — a photo of a real person enrols like any other. See Liveness at enrolment for what the check does and does not stop.

Batch enrollment

For bulk imports, use the batch endpoint to enroll multiple faces in a single request. Each item in the batch is processed independently. Partial failures do not roll back successful enrollments.

Shell

POST /api/v1/collections/{collection_id}/faces/batch
X-API-Key: lxf_a1b2c3d4_e5f6g7h8i9j0k1l2m3n4o5p6
Content-Type: multipart/form-data

images[]=@alice.jpg
images[]=@bob.jpg
external_ids[]=user_alice_001
external_ids[]=user_bob_002

List faces in a collection

Shell

GET /api/v1/collections/{collection_id}/faces?page=1&page_size=50
X-API-Key: lxf_a1b2c3d4_e5f6g7h8i9j0k1l2m3n4o5p6

Get a specific face

Shell

GET /api/v1/collections/{collection_id}/faces/{face_id}
X-API-Key: lxf_a1b2c3d4_e5f6g7h8i9j0k1l2m3n4o5p6

Update face metadata

Shell

PATCH /api/v1/collections/{collection_id}/faces/{face_id}
X-API-Key: lxf_a1b2c3d4_e5f6g7h8i9j0k1l2m3n4o5p6
Content-Type: application/json

{
  "metadata": {"name": "Alice Johnson", "department": "Product"}
}

Delete a face

Removes the face from the collection. The change takes effect immediately. The face will no longer appear in searches.

Shell

DELETE /api/v1/collections/{collection_id}/faces/{face_id}
X-API-Key: lxf_a1b2c3d4_e5f6g7h8i9j0k1l2m3n4o5p6

Auto-enroll

When a 1:N identification produces a high-confidence match, the query image is automatically saved as a secondary reference for that face. This progressively improves recognition accuracy over time as users' appearance naturally changes (lighting, haircut, accessories).

In a collection that requires liveness, the query image has to pass the same check before it is kept. Otherwise a spoof that matched once would become a permanent reference, and every later spoof would match it better.