Documentation Index
Fetch the complete documentation index at: https://docs.wellapp.ai/llms.txt
Use this file to discover all available pages before exploring further.
ReconciliationLink records a single AI-produced assertion that two distinct entity records represent the same real-world object (source → target). Each link carries the reconciliation action (e.g. merge), a confidence score, structured reasoning, and an optional field_contributions breakdown describing how individual field signals contributed to the match. The link is workspace-scoped, soft-deletable, and optionally tied to a human-review Task when the confidence is below auto-accept thresholds. It is written exclusively by the reconciliation pipeline (reconciliation-persister.ts) and is read-only from the user API layer.
| Naming | Value |
|---|
| Object | ReconciliationLink |
Resource type (JSON:API type) | reconciliation_link |
| Collection / records root | — (not a records root) |
| REST base | /v1/reconciliation-links |
| Entity class | ReconciliationLink |
Internal object. Not currently exposed on the public REST API. The operations below describe the intended contract.
API operations
| Operation | Method & path | Status |
|---|
| List | GET /v1/reconciliation-links | 🟡 Planned |
| Retrieve | GET /v1/reconciliation-links/{id} | 🟡 Planned |
| Create | POST /v1/reconciliation-links | 🟡 Planned |
| Update | PATCH /v1/reconciliation-links/{id} | 🟡 Planned |
| Delete | DELETE /v1/reconciliation-links/{id} | 🟡 Planned |
Data model
Attributes
| Field | Type | Required | Constraints | Allowed values | Description |
|---|
| reconciliation_link_id | string (UUID) | ✅ Yes | unique | — | Public identifier for this reconciliation link, generated by gen_random_uuid(). Exposed on all API responses; used as the canonical external reference. |
| source_type | string | ✅ Yes | varchar(100) | — | Entity type string for the source record (e.g. company, people). Together with source_id identifies the left-hand side of the match assertion. |
| source_id | string | ✅ Yes | varchar(255) | — | Public UUID of the source entity record. Used with source_type to resolve the entity without a FK constraint, supporting heterogeneous entity graphs. |
| target_type | string | ✅ Yes | varchar(100) | — | Entity type string for the target record — the candidate that the reconciliation pipeline identified as matching the source. |
| target_id | string | ✅ Yes | varchar(255) | — | Public UUID of the target entity record. Used with target_type to resolve the candidate entity. |
| relationship | string | ✅ Yes | varchar(100) | — | Semantic label for the nature of the match (e.g. duplicate, same_company, alias). Determined by the reconciliation agent’s strategy. |
| action | string | ✅ Yes | varchar(50) | — | Operational action the pipeline intends to take when the link is applied (e.g. merge, link). Used as an index dimension for the workspace-scoped tenant lookup index. |
| confidence | number (numeric) | ✅ Yes | numeric(5,4) | — | Reconciliation confidence score in the range [0, 1] expressed to 4 decimal places. Determines whether the link is auto-applied or routed to human review. |
| reasoning | string (text) | ✅ Yes | text | — | Human-readable explanation generated by the reconciliation agent summarising why the source and target were matched. |
| field_contributions | object[] (JSONB) | null | ⚪ No | jsonb, nullable | — | Ordered list of FieldContribution objects, each describing one field signal that contributed to the confidence score. Schema: { source_field, candidate_field, claimed_match_type, verified_match_type, signal, weight }. |
| status | 🔒 system — enum (link_status_enum) | ✅ Yes | native enum link_status_enum; default active | active | pending_review | rejected | Lifecycle state of the reconciliation link. Defaults to active on creation. Transitions to pending_review when confidence falls below the auto-apply threshold; set to rejected by the human reviewer or system. |
| created_at | 🔒 system — Date | ✅ Yes | timestamptz, not null, default now() | — | Timestamp set by onCreate hook when the link is first persisted. Never updated. |
| updated_at | 🔒 system — Date | ⚪ No | timestamptz, set by ORM hooks | — | Timestamp refreshed by onCreate and onUpdate MikroORM hooks on every write. Reflects the last mutation made by the pipeline. |
| deleted_at | 🔒 system — Date | null | ⚪ No | timestamptz, nullable | — | Soft-delete timestamp. Null when active. Set by the reconciliation pipeline when a link is superseded or retracted. All workspace-scoped queries filter deleted_at IS NULL. |
Relationships
| Name | Type | Required | Description |
|---|
| workspace | to-one (ManyToOne) | ✅ Yes | Tenant boundary. Every reconciliation link belongs to exactly one Workspace. Cascade delete: the link is hard-deleted when the workspace is deleted. Indexed via idx_reconciliation_links_workspace on workspace_pk. |
| review_task | to-one (ManyToOne, nullable) | ⚪ No | Optional reference to a Task created for human review of this link. Set when confidence is below the auto-accept threshold. FK delete rule: set null — the link persists if the review task is deleted. |
System-computed
- reconciliation_link_id — generated via gen_random_uuid() database default on INSERT; never supplied by the caller
- created_at — set by MikroORM onCreate hook (new Date()); never updated
- updated_at — set by MikroORM onCreate and onUpdate hooks; refreshed on every flush
- deleted_at — managed by the reconciliation pipeline; set to a timestamp on soft-delete; queries must always filter deleted_at IS NULL
- status — defaults to LinkStatusEnum.ACTIVE (‘active’) at ORM layer; transitioned by the reconciliation persister and review workflow, never by user PATCH
- pk — auto-increment serial primary key; internal join key only, never exposed in API responses
- field_contributions — populated by the reconciliation scorer at write time; null when the scoring pass did not produce per-field breakdown data
Example
{
"data": {
"type": "reconciliation_link",
"id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"attributes": {
"reconciliation_link_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"source_type": "company",
"source_id": "7f3e2a1b-0c4d-5e6f-a7b8-c9d0e1f23456",
"target_type": "company",
"target_id": "2b4d6f80-a1c3-e5f7-9012-b3c4d5e67890",
"relationship": "duplicate",
"action": "merge",
"confidence": 0.9312,
"reasoning": "Both records share the same SIREN number, registered address, and principal email domain. High-confidence deduplication candidate.",
"field_contributions": [
{
"source_field": "tax_id_value",
"candidate_field": "tax_id_value",
"claimed_match_type": "exact",
"verified_match_type": "exact",
"signal": "siren_match",
"weight": 0.5
},
{
"source_field": "domain",
"candidate_field": "domain",
"claimed_match_type": "exact",
"verified_match_type": "exact",
"signal": "domain_match",
"weight": 0.3
}
],
"status": "active",
"created_at": "2026-03-19T12:00:00.000Z",
"updated_at": "2026-03-19T12:00:00.000Z",
"deleted_at": null
},
"relationships": {
"workspace": {
"data": { "type": "workspace", "id": "ws-uuid-0001" }
},
"review_task": {
"data": { "type": "task", "id": "task-uuid-0042" }
}
}
}
}
apps/api/src/database/entities/ReconciliationLink.ts · domain: financial-graph · tier: Supporting
