FR-APIaaS - Face Recognition API as a Service

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://your-domain.com/api/v1/collections/COLLECTION_ID/faces \
  -H "X-API-Key: YOUR_API_KEY" \
  -F "image=@photo.jpg" \
  -F "external_id=user_alice_001" \
  -F 'metadata={"name":"Alice Smith","department":"Engineering"}'

{
  "success": true,
  "data": {
    "face_id": "face_01j9abc...",
    "external_id": "user_alice_001",
    "collection_id": "col_01j8...",
    "quality_score": 0.94,
    "liveness_score": 0.98,
    "metadata": {"name": "Alice Smith", "department": "Engineering"},
    "created_at": "2024-01-15T10: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 and liveness thresholds

Before storing a face, the API automatically evaluates image quality (blur, occlusion, extreme pose) and runs a liveness check. Enrollments that fail quality are rejected with FACE_QUALITY_TOO_LOW. Failed liveness checks return LIVENESS_CHECK_FAILED.

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.

POST /api/v1/collections/{collection_id}/faces/batch
X-API-Key: fr_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxx
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

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

Get a specific face

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

Update face metadata

PUT /api/v1/collections/{collection_id}/faces/{face_id}
X-API-Key: fr_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxx
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.

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

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).

Face Enrollment