Identification (1:N)

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://api.livexface.com/api/v1/collections/COLLECTION_ID/identify \
  -H "X-API-Key: YOUR_API_KEY" \
  -F "[email protected]" \
  -F "top_k=5" \
  -F "threshold=0.45"

{
  "success": true,
  "data": {
    "matches": [
      {
        "faceId": "dc3e7a57-22d5-4271-b707-213e49c8fe54",
        "externalId": "user_alice_001",
        "confidence": 0.97,
        "metadata": {"name": "Alice Smith", "department": "Engineering"}
      },
      {
        "faceId": "4b9e1f02-7c5a-4d83-9e61-2a7f8c3b5d40",
        "externalId": "user_bob_002",
        "confidence": 0.51,
        "metadata": {"name": "Bob Tan", "department": "Facilities"}
      }
    ],
    "queryTimeMs": 42,
    "detectedFaces": [
      { "bbox": { "x": 87, "y": 48, "width": 91, "height": 131 }, "detScore": 0.89 }
    ],
    "imageSize": { "width": 256, "height": 256 }
  }
}

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

One entry per face

An enrolled face accumulates more than one embedding over time: the photo you enrolled, plus any the service added later. The search scores every embedding but returns each face once, at its best-scoring one, so a face cannot crowd out the rest of your results with near-duplicates of itself.

Two separate people still both appear. If your collection holds the same person under two different externalId values, you will see two matches — the deduplication is per face, not per person.

Faces improve themselves

When a search matches a face at 0.70 confidence or better, the query image is kept as an extra reference for that face. Appearances drift — lighting, a haircut, new glasses — and a reference from today matches better than one from two years ago.

This runs in the background and never delays your response. It is bounded on purpose: at most 10 extra references per face, and at most one every 5 minutes, so a turnstile photographing the same person all morning adds one reference, not two hundred.

Performance at scale

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