WorkspaceIdentityExtraction

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" }
      }
    }
  }
}

_{Source: /Users/maximechampoux/platform/apps/api/src/database/entities/WorkspaceIdentityExtraction.ts · domain: ingestion · tier: Infrastructure}

Main objects

Supporting objects

Platform objects

Activity objects

Infrastructure objects

API operations

Data model

Attributes

Relationships

System-computed

Example

​API operations

​Data model

​Attributes

​Relationships

​System-computed

​Example

API operations

Data model

Attributes

Relationships

System-computed

Example