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.
WorkspaceIdentityExtraction is an evidence ledger that the self-invoice consensus mechanism uses to identify the workspace owner’s own business identity from processed invoices. Each row captures one (field, value) pair extracted from a single invoice that was determined to originate from or be addressed to the workspace owner, classified by the signal that triggered that determination. The service WorkspaceSelfIdentityService reads these rows to check whether N≥2 independent invoices agree on a given identity field value before committing it to WorkspaceAccountingSettings. The table is workspace-scoped and soft-deleted; both foreign keys cascade on hard delete of the parent workspace or source invoice.
| Naming | Value |
|---|
| Object | WorkspaceIdentityExtraction |
Resource type (JSON:API type) | workspace_identity_extraction |
| Collection / records root | — (not a records root) |
| REST base | /v1/workspace-identity-extractions |
| Entity class | WorkspaceIdentityExtraction |
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/workspace-identity-extractions | 🟡 Planned |
| Retrieve | GET /v1/workspace-identity-extractions/{id} | 🟡 Planned |
| Create | POST /v1/workspace-identity-extractions | 🟡 Planned |
| Update | PATCH /v1/workspace-identity-extractions/{id} | 🟡 Planned |
| Delete | DELETE /v1/workspace-identity-extractions/{id} | 🟡 Planned |
Data model
Attributes
| Field | Type | Required | Constraints | Allowed values | Description |
|---|
| workspace_identity_extraction_id | string (UUID) | ✅ Yes | unique | — | Public-facing stable identifier for the extraction row, generated by gen_random_uuid() at insert time. Exposed as the JSON:API id. |
| field_name | string (enum: WorkspaceIdentityField) | ✅ Yes | varchar(40), NOT NULL | ”tax_id_value” | “registered_value” | “registered_name” | “trade_name” | “country” | Which workspace accounting field this extraction represents. Mirrors the writable subset of WorkspaceAccountingSettings. |
| value | string | ✅ Yes | varchar(255), NOT NULL | — | The extracted value for the field named by field_name (e.g., the actual VAT number, legal name, or ISO country code). |
| tax_id_type | string | ⚪ No | varchar(20), nullable | — | Only populated when field_name is ‘tax_id_value’. Carries the type of tax identifier extracted (e.g., ‘VAT’, ‘SIREN’). |
| signal | string (enum: WorkspaceIdentitySignal) | ✅ Yes | varchar(40), NOT NULL | ”mailbox_sent” | “receiver_exact” | “receiver_partial” | Classifies why the extraction pipeline concluded that this invoice’s issuer or receiver is the workspace owner. Drives confidence weighting in the consensus rule. |
| created_at | 🔒 system — timestamptz | ✅ Yes | NOT NULL, default now() | — | Timestamp set by the @Property onCreate hook when the row is first inserted. Not updated thereafter (no updated_at on this entity). |
| deleted_at | 🔒 system — timestamptz | ⚪ No | nullable | — | Soft-delete timestamp. When set, the row is excluded from the partial indexes idx_wie_workspace_field and uq_wie_workspace_field_invoice, and from all active consensus queries. |
Relationships
| Name | Type | Required | Description |
|---|
| workspace | to-one (ManyToOne) | ✅ Yes | The workspace whose owner identity this row is gathering evidence for. ON DELETE CASCADE — all extraction rows are removed when the workspace is deleted. |
| source_invoice | to-one (ManyToOne → Invoice) | ✅ Yes | The invoice from which this (field, value) pair was extracted. ON DELETE CASCADE — extraction rows are removed when the source invoice is deleted. Combined with workspace_pk and field_name forms the partial-unique constraint uq_wie_workspace_field_invoice. |
System-computed
- workspace_identity_extraction_id — generated by gen_random_uuid() at row creation via defaultRaw; client never supplies this value
- created_at — set by @Property onCreate hook; no updated_at on this entity (it is append-only evidence; rows are never mutated after insert)
- deleted_at — soft-delete; set by the pipeline when an evidence row is invalidated, not by user action
- pk — internal auto-increment serial primary key; never exposed via the API
- Partial UNIQUE constraint uq_wie_workspace_field_invoice (workspace_pk, field_name, source_invoice_pk) WHERE deleted_at IS NULL — enforced by the migration, not expressible in ORM decorators; prevents double-insert race during concurrent registerOne calls for the same invoice
- Partial index idx_wie_workspace_field (workspace_pk, field_name) WHERE deleted_at IS NULL — hot-path index for the consensus query in WorkspaceSelfIdentityService.checkConsensusAndAct
- Rows are created exclusively by WorkspaceSelfIdentityService (extraction pipeline); no user-facing PATCH endpoint exists for this entity
- tax_id_type is conditionally populated: only the extraction service sets it, and only when field_name === ‘tax_id_value’
Example
{
"data": {
"type": "workspace_identity_extraction",
"id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"attributes": {
"field_name": "tax_id_value",
"value": "FR12345678901",
"tax_id_type": "VAT",
"signal": "mailbox_sent",
"created_at": "2026-04-22T09:15:00.000Z",
"deleted_at": null
},
"relationships": {
"workspace": {
"data": { "type": "workspace", "id": "b2c3d4e5-f6a7-8901-bcde-f12345678901" }
},
"source_invoice": {
"data": { "type": "invoice", "id": "c3d4e5f6-a7b8-9012-cdef-012345678902" }
}
}
}
}
/Users/maximechampoux/platform/apps/api/src/database/entities/WorkspaceIdentityExtraction.ts · domain: ingestion · tier: Infrastructure
