Enrolment image capture

The face you submit to biofrq.enroll becomes the reference every future identify and verify call is compared against. Every quality issue in that one image follows you for the lifetime of the subject — bad reference, persistent misses.

This page is the standard operating procedure for capturing enrolment images. Probe images (the ones you submit at identify / verify time) follow the same rules, but the bar is highest at enrol.

The one rule that beats everything else

Inspect quality before you enrol. Call biofrq.detect with returnQuality: true first, read the response, and only call biofrq.enroll if the metrics pass the gates below. The detect call costs a fraction of an enrol and saves you from poisoning your gallery with a reference you can't trust.

# 1. Pre-flight: detect + quality
curl -X POST https://api.biofrq.com/v1/face/execute \
  -H "X-Api-Key: bfq_live_…" \
  -H "Content-Type: application/json" \
  -d '{
    "action": "biofrq.detect",
    "params": {
      "images": [{ "kind": "image", "bytes": "<base64>", "contentType": "image/jpeg" }],
      "returnQuality": true
    }
  }'

# 2. Only if quality passes -> biofrq.enroll

The quality block lives at data.results[0].value.faces[0].quality.

Quality fields

Recommended gates

These are recommendations, not hard limits the service imposes — you choose the policy that matches your operating environment.

Framing the face

The face needs to dominate the crop you send. A small face inside a wide frame wastes resolution; a face cropped tight to the chin loses the forehead and ears the embedding relies on.

Target: face fills 60–80% of the shorter dimension, centred, with margin on all sides.

Good: face fills the height of the crop, eyes near the mid-line, even ambient light.

What to avoid:

• Face too small in frame — sourced from a wide shot or full-body capture. facePixelWidth will likely fall below 112 and the embedding will be unstable. Re-crop closer or capture at a shorter distance.
• Face crop too tight — forehead, ears, or chin clipped. The detector aligns on those landmarks; missing any of them degrades the embedding quality.
• Off-centre — face crammed against one edge. Centre the face before cropping.

Pose tolerance

The embedding is sensitive to head pose. Frontal works best. Acceptable for enrol when poseSupported is true: |yaw| ≤ 20°, |pitch| ≤ 20°, |roll| ≤ 20°.

Left: frontal (yaw ≈ 0°) — primary reference. Centre: slight angle (yaw ≈ 15°) — fine as an additional reference. Right: profile (yaw ≈ 90°) — do not enrol.

If poseSupported: false is returned, the current model build did not estimate angles for this face. Fall back to a visual check — the subject should be looking close to the camera, not in profile.

Lighting

Aim for a setup the operator can replicate every day. Inconsistent lighting across captures of the same person degrades the embedding average over time.

Capture distance and lens

Multiple references per identity

Identify scores the probe against every reference attached to a subject and reports the highest. The more reference embeddings a subject has, covering more poses / lighting / expressions, the more chances any single probe has to score above your match threshold.

Multiple references for one externalId. Identify returns the max score across all of them — so a probe only needs to match one reference well to surface.

Add a new reference by calling biofrq.enroll again with the same externalId and mode: "addReference". The service attaches the new reference to the existing subject; identify takes the maximum across all of them.

{
  "action": "biofrq.enroll",
  "params": {
    "externalId": "emp-4421",
    "groupName": "employees",
    "mode": "addReference",
    "images": [ { "kind": "image", "bytes": "...base64..." } ]
  }
}

Default mode is "create", which rejects a repeat externalId with CONFLICT — that's the right behaviour for first enrolment, not for adding references. forceEnroll: true is a different flag: it only bypasses the duplicate-face dedup gate (the check that prevents enrolling the same person twice under different externalIds); it does not change the create-vs-add behaviour. Use both flags together only when you're adding a reference to an existing person whose new image happens to sit very close to another subject's embedding.

When to add a reference:

• The subject's appearance changes meaningfully — new haircut, glasses, weight change, beard.
• You captured a higher-quality image than the original.
• Identify on a known-correct probe scores below your match threshold — the existing reference no longer represents the person well.

Common pitfalls

Checklist before enrolling

□  Subject is looking close to the camera (not profile)
□  Eyes, nose, mouth, chin, forehead all visible
□  No sunglasses, no face mask, no hand covering the face
□  Even lighting on both sides of the face
□  Face fills 60-80% of the shorter dimension of the frame
□  detect returned faceBoxConfidence >= 0.85
□  detect returned overallScore >= 0.80
□  detect returned facePixelWidth >= 112
□  No motion blur (sharpnessScore >= 0.40)
□  Exposure looks right (brightnessScore >= 0.35)
□  pose within ±20° (when poseSupported is true)

If every box is checked, submit biofrq.enroll. If any box fails, re-capture; don't lower the bar.

What's next

• biofrq.detect — the pre-flight call.
• biofrq.enroll — the action itself.
• biofrq.identify — how the references you just enrolled are used.