> ## 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

> WorkspaceIdentityExtraction is an evidence ledger that the self-invoice consensus mechanism uses to identify the workspace owner's own business identity from pr

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       | — <sub>(not a records root)</sub>    |
| REST base                       | `/v1/workspace-identity-extractions` |
| Entity class                    | `WorkspaceIdentityExtraction`        |

<Note>
  **Internal object.** Not currently exposed on the public REST API. The operations below describe the intended contract.
</Note>

## 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

```json theme={null}
{
  "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" }
      }
    }
  }
}
```

<sub>Source: `/Users/maximechampoux/platform/apps/api/src/database/entities/WorkspaceIdentityExtraction.ts` · domain: ingestion · tier: Infrastructure</sub>