Facematch

Not yet checked on the product

This chapter was written from the product's source code and has not yet been checked by a person on a running Cogneris. If what you see on screen differs, the screen is right — please tell your Cogneris contact so the chapter can be corrected.

Compares the selfie of a process with the identity documents it must belong to, and publishes one verdict per document and one decision for the process. A missing selfie, an unreadable face or a failed comparison never fails the run: it sends the process to human review.

Palette	Nodes › Facematch
Outputs	One output. The phase never branches; it writes a decision (pass, review or notApplicable) that a later phase reads.
Content status	From source; not observed (workflow-fe f88c5c1, workflow-be 6703373, 2026-10-22)

When to use it

• Identity checks (KYC): the customer sends an ID and a selfie, and you need to know they are the same person.
• After a Classification or Zero Shot phase — Facematch needs the document types those phases assign.
• Before Manual Review: the face conference is shown to the reviewer, and a manual review never approves on its own when a Facematch ran.

The Identity verification workflow template includes this phase. A face comparison can also be a rule of a Cross-check (Face match); the dedicated phase adds a threshold, explicit targets and per-document detail.

What happens in a run

Inputs. The documents of the run, and the document type each one received from an earlier Classification or Zero Shot phase.

1. The selfie is found. The selfie is the document whose type equals Selfie document type (selfie when the field is empty). If no document has that type — the normal case, since templates rarely type a selfie — the service looks for a face on the run's images whose type could not be identified, up to 5 images. Exactly one image with a face becomes the selfie, and its type is set to the selfie type for the rest of the run.

2. The targets are chosen. With Documents that must match the selfie ticked, only documents of those types are compared; a ticked type the process did not supply is reported as document_not_present. With nothing ticked, the selfie is compared with every other document of the run.

3. Each target is compared, one call per document (each comparison is billed). The result for that document is:

   Result of the comparison	Verdict	Reason
   Same person: score at or above Match threshold, or — with no threshold — the face service's own verdict	match	—
   Different person	mismatch	different_person
   No face found in the document	inconclusive	no_face_in_document
   More than one face in the document	inconclusive	too_many_faces
   The face service answered with an error, or the call failed	inconclusive	facematch_error: …
   The document failed in an earlier phase	inconclusive (or notApplicable when skipping)	document_failed_upstream

4. Cases without a comparison produce a single verdict instead:

   Situation	Verdict	Reason
   No selfie found	inconclusive, or notApplicable when Skip when the selfie or the document is missing is on	selfie_not_present
   More than one image with a face	inconclusive	multiple_selfies
   No target document	inconclusive, or notApplicable when skipping	no_target_document / document_not_present
   The face-detection service did not answer for an image after the retries	inconclusive	selfie_probe_unavailable

5. The process decision is:

   • pass — at least one document matched and none is mismatch or inconclusive;
   • notApplicable — nothing was compared (every verdict is notApplicable); this is not a pass, it means the process was never face-checked;
   • review — anything else.

Outputs. A facematch block in the run's data: decision, selfie (its file name), threshold, a summary (total, match, mismatch, inconclusive, notApplicable) and one entry per check (document, document type, verdict, score, whether a face was found, whether there were too many faces, reason). Each compared document also gets its own result (results[…].facematch, with score and matched), which the review screen shows next to the document.

Retries and failures. When the face-detection service refuses temporarily while looking for the selfie, the phase is run again after 30 seconds, then after 2 minutes. The run fails only for a structural problem: no documents, no document types from an earlier phase, or a selfie that cannot be read from storage.

To route on the decision, add a Conditional that tests facematch.decision — for example = pass to demand a successful check, or ≠ review to also let notApplicable through.

Configuration

Field	What it does	Required	Format / values	Default	Validation messages
Description	Name shown on the node.	No	Text	Facematch	—
Selfie document type	The document type that is the selfie. Every other compared document is matched against it.	No	Text; compared ignoring case	selfie (shown as placeholder)	—
Documents that must match the selfie	One checkbox per template of your company. Only the ticked types are compared.	No	Template names; matched against the document type an earlier phase assigned	None ticked — compare with every other document	Could not load your templates, so targets cannot be picked. With none checked, every other document is compared.
Match threshold (0-1)	The minimum score for a match, for this workflow only.	No	Number from 0 to 1, step 0.01; values outside are brought back into range	Empty — the face service's own verdict	—
Skip when the selfie or the document is missing	Off: a missing selfie or target sends the process to review. On: it is recorded as notApplicable.	No	On / off	Off	—

Common problems

Message	Cause	What to do
Could not load your templates, so targets cannot be picked. With none checked, every other document is compared.	The template list did not load, so no target can be ticked.	Reload the editor.
No documents found for facematch. (run error)	The run reached the phase with no documents.	Check what the process was started with.
Facematch requires an upstream classification or zero-shot phase that assigns document types. (run error)	No Classification or Zero Shot ran before the phase.	Add one before Facematch.
facematch: could not read selfie '…': … (run error)	The selfie file could not be read from storage.	Start the process again; if it repeats, contact support.
Decision review with reason selfie_not_present	No document has the selfie type and no unidentified image with a face was found.	Check Selfie document type, or that the form asks for a selfie.
Decision review with reason multiple_selfies	More than one unidentified image has a face.	A reviewer decides.
Decision notApplicable	Skip when the selfie or the document is missing is on and nothing could be compared.	Turn it off for identity checks that must always run.

Related

• Cross-check — Face match rules.
• Classification, Zero Shot — assign the document types this phase needs.
• Manual Review — selfies wait in their own review queue.
• Conditional
• Organize human review

---

Last reviewed 2026-10-22 · Version 1.0.0 · Owner: product-documentation