Skip to main content
POST
Upload faces for duplicate detection enrollment
Mass-enrolls up to 50 face images into the reserved biometric duplicate-detection watchlist in one call. Each image is processed asynchronously: a Trust Validation is created for it, the face is enrolled against the engine, and — only if enrollment succeeds — the image is stored and the Trust Validation is marked Verified. This lets you pre-seed the duplicate-detection watchlist in bulk (for example, when migrating an existing customer base) instead of enrolling one face per live verification. Processing is asynchronous. This endpoint queues the batch and returns immediately (202). Poll GET /api/v3/duplicate-detection/uploads/{uploadId} for progress and per-image results.

Authentication

Same as all other v3 endpoints:
  • Bearer token (Sanctum) in the Authorization header
  • HMAC signature headers (X-HMAC-SIGNATURE, X-TIMESTAMP, X-USER-ID)
See Introduction to the API for how to create an API token.

Request

Content-Type: multipart/form-data Example form fields: images[0], images[1], images[2], …

Example cURL

Responses

202 Accepted — batch queued

422 Validation error (bad file count / type / size)

The errors object follows the standard Laravel validation error shape. Keys are images or images.0, images.1, etc.

422 Company storage not configured

422 Biometrics Registration not enabled

503 Queue unavailable

Transient — safe to retry.

Behavioral notes

  • Billing: This endpoint is free. No plan credit is consumed per image, unlike the single-image Biometrics Detection endpoint.
  • Screening: Images are enrolled only. They are not screened against other watchlists at upload time — no duplicate or blacklist match results are returned here.
  • Per-image failures: If enrollment fails (poor quality, no face detected, etc.), no Trust Validation or image is kept for that image. The failure is reported via the polling endpoint with a human-readable reason.
  • Successful enrollments: Each enrolled face gets a real Trust Validation that appears in your normal Trust Validations list and can later be matched against by other verifications that screen the duplicate-detection watchlist.

Error responses

Authorizations

Authorization
string
header
required

Use Bearer {your_api_token} in the Authorization header, or HMAC signature headers (X-HMAC-SIGNATURE, X-TIMESTAMP, X-USER-ID). Same authentication as other v3 endpoints.

Headers

Authorization
string
required
Example:

"Bearer {your_api_token}"

Body

multipart/form-data
images
file[]
required

1–50 image files. Accepted formats: jpg, jpeg, png. Max 10 MB each. Use form fields images[0], images[1], etc.

Required array length: 1 - 50 elements

Response

Face upload accepted and queued for duplicate detection enrollment

success
boolean
message
string
data
object