> ## 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
> ReconciliationLink records a single AI-produced assertion that two distinct entity records represent the same real-world object (source โ target)
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
```json theme={null}
{
"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" }
}
}
}
}
```
Source: `apps/api/src/database/entities/ReconciliationLink.ts` ยท domain: financial-graph ยท tier: Supporting