1:N Identification answers: "Who is this person in my collection?" Submit a face photo, and the API searches your enrolled collection to return the top-K most similar matches above a confidence threshold.

Use identification for access control gates, attendance systems, watchlist screening, or any scenario where you need to find a person from a large database.

Identify a face

curl -X POST https://your-domain.com/api/v1/collections/COLLECTION_ID/identify \
  -H "X-API-Key: YOUR_API_KEY" \
  -F "image=@query.jpg" \
  -F "top_k=5" \
  -F "threshold=0.55"

{
  "success": true,
  "data": {
    "matches": [
      {
        "face_id": "face_01j9abc...",
        "external_id": "user_alice_001",
        "similarity": 0.97,
        "rank": 1,
        "metadata": {"name": "Alice Smith", "department": "Engineering"}
      },
      {
        "face_id": "face_01j9def...",
        "external_id": "user_alice_001",
        "similarity": 0.94,
        "rank": 2,
        "metadata": {"name": "Alice Smith", "department": "Engineering"}
      }
    ],
    "query_time_ms": 42,
    "searched": 12450
  }
}

If no faces meet the threshold, matches is an empty array. The API does not return a 404. A query time of ~42ms is typical for a collection of 10,000+ faces.

Request parameters

Deduplication by external ID

A person can have multiple face references in a collection (original enrollment plus any auto-enrolled secondary references). By default, results are deduplicated by external_id. Only the best-scoring match per person is returned. Set deduplicate=false to receive all individual matches.

image=@query.jpg
top_k=5
deduplicate=false   # returns individual embeddings, not deduplicated by person

Auto-enroll on match

When identification returns a high-confidence match, the query image is automatically saved as a secondary reference for that person. This improves accuracy over time as appearances change (lighting, haircut, glasses).

Auto-enroll can be disabled per-request:

image=@query.jpg
top_k=3
auto_enroll=false

Performance at scale

Search performance scales well for large collections. Contact support if you need to optimize for very large collections (>1M faces).