Handling ambiguous identity matches
When Anchord finds multiple plausible matches and can't pick one with
confidence, it returns needs_review
instead of guessing. This is the key safety mechanism that prevents
agents from writing to the wrong record.
When this happens
- Resolve: Two or more candidates score within a close confidence margin, or a fuzzy match falls below the auto-link threshold
- Guard: The entity has unresolved conflicts, missing links, or confidence below the threshold (default 0.70)
- Common trigger: Similar company names like "Acme Corp" and "Acme Inc" across different source systems
Endpoints involved
| Endpoint | Signal |
|---|---|
| POST /api/v1/resolve/company | status: "needs_review" |
| POST /api/v1/resolve/person | status: "needs_review" |
| POST /api/v1/guard/write | allowed: false with blocks array |
What the response looks like
{
"status": "needs_review",
"safe_to_write": false,
"candidates": [
{ "entity_id": "ent_111", "confidence": 0.92 },
{ "entity_id": "ent_222", "confidence": 0.90 }
],
"conflicts": ["AMBIGUOUS_CANDIDATES"],
"attempt_id": "att_xyz789"
}
Key fields: attempt_id (links to the Review Queue),
candidates (competing matches with scores),
safe_to_write: false (explicit signal to stop).
What the agent should do
Stop — do not write
Do not pick a candidate programmatically. The point is that the system couldn't, so the agent shouldn't either.
Escalate to a human
Store the attempt_id and link the user to the
Review Queue, where they can confirm,
dismiss, defer, or create a new entity.
Retry after resolution
Once the human resolves the ambiguity, the same resolve call returns
resolved with a stable AnchorID. Proceed to guard and write.