> ## 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.
# Custom Column
> A Custom Column is a per-workspace, per-root virtual column a user adds to a records table (e.g
A Custom Column is a per-workspace, per-root virtual column a user adds to a records table (e.g. a 'Risk level' column on companies). It holds the column definition only โ name, type, position, and the AI/formula/format config โ while the computed cell values live in custom\_column\_values. Custom columns are workspace-scoped and namespaced by records root; they are NOT Hasura columns and NOT governed DATA\_VIEW\_ROOTS, so they sit behind the records table as an overlay rather than as a queryable entity of their own.
| Naming | Value |
| ------------------------------- | --------------------------------- |
| Object | Custom Column |
| Resource type (JSON:API `type`) | `custom_column` |
| Collection / records root | โ (not a records root) |
| REST base | `/v1/custom-columns` |
| Entity class | `CustomColumn` |
**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/custom-columns` | ๐ก Planned |
| Retrieve | `GET /v1/custom-columns/{id}` | ๐ก Planned |
| Create | `POST /v1/custom-columns` | ๐ก Planned |
| Update | `PATCH /v1/custom-columns/{id}` | ๐ก Planned |
| Delete | `DELETE /v1/custom-columns/{id}` | ๐ก Planned |
## Data model
### Attributes
| Field | Type | Required | Constraints | Allowed values | Description |
| ------------------ | ----------------------------- | -------- | -------------------------------------------------------------- | ------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- |
| custom\_column\_id | string, UUID, ๐ system | โ
Yes | unique; gen\_random\_uuid() | โ | Public identifier of the column definition. Internal pk is never exposed. |
| root | string | โ
Yes | max 50 chars; part of partial-unique key | A records root (companies, invoices, transactions, โฆ) | The data-view root this column is attached to. Scopes the column to one records table. |
| name | string | โ
Yes | max 255 chars | โ | Human-readable column header shown in the records table. |
| field\_key | string | โ
Yes | max 100 chars; part of partial-unique key; slugified from name | โ | Stable machine key for the column, slugified from name at creation. Unique per (workspace, root). |
| type | string (CustomColumnTypeEnum) | โ
Yes | native enum custom\_column\_type\_enum; default 'text' | text, number, amount, single\_select, multi\_select, ai | Column data type. 'ai' (and rules\_config-bearing columns) are auto-computed; others may be manually entered. |
| position | number (int) | โช No | default 0 | โ | Display order of the column within the records table. |
| icon | string | โช No | max 100 chars; nullable | โ | Optional icon identifier rendered in the column header. |
| rules\_config | jsonb | โช No | nullable | โ | AI compute rules. When set, the column is auto-computed by the enrichment pipeline (Anthropic Haiku) for every record. |
| formula\_config | jsonb | โช No | nullable | โ | Formula configuration for computed (non-AI) columns. |
| format\_config | jsonb | โช No | nullable | โ | Display/format configuration (e.g. select options, number format). |
| created\_at | ISO 8601, ๐ system | โ | onCreate hook | โ | Creation timestamp. |
| updated\_at | ISO 8601, ๐ system | โ | onCreate + onUpdate hooks | โ | Last-update timestamp. |
| deleted\_at | ISO 8601, ๐ system | โ | nullable; soft delete | โ | Soft-delete tombstone; null when active. |
### Relationships
| Name | Type | Required | Description |
| --------- | ------------------------------- | -------- | ----------------------------------------------------------------------------------------------- |
| workspace | to-one (workspace) | โ
Yes | Owning workspace โ the per-workspace scope of the column. |
| values | to-many (custom\_column\_value) | โช No | Computed/entered cell values for this column, one per record (cascade-deleted with the column). |
### System-computed
* custom\_column\_id generated by gen\_random\_uuid()
* field\_key slugified from name at creation (slugifyFieldKey)
* Partial unique index on (workspace\_pk, root, field\_key) WHERE deleted\_at IS NULL โ managed in a raw-SQL migration, not @Index (MikroORM cannot express partial indexes)
* type defaults to 'text'; position defaults to 0
* created\_at via onCreate; updated\_at via onCreate + onUpdate hooks
* Soft-delete via deleted\_at
* On create: autoProvisionPresets(workspace, root) may seed preset AI columns; fire-and-forget recompute over existing records
* On rules\_config / formula\_config / format\_config change: enqueueRecompute โ recompute all records for the column
* AI columns (type='ai' or rules\_config present) compute via EnrichmentTask (CUSTOM\_COLUMN) โ Cloud Task โ Anthropic Haiku, with anti-prompt-injection guards
## Example
```json theme={null}
{
"data": {
"type": "custom_column",
"id": "7c1f9a02-4d3b-4e21-9a77-2f0c11aa33bc",
"attributes": {
"custom_column_id": "7c1f9a02-4d3b-4e21-9a77-2f0c11aa33bc",
"root": "companies",
"name": "Risk level",
"field_key": "risk_level",
"type": "single_select",
"position": 3,
"icon": "shield-alert",
"rules_config": "{\"prompt\":\"Classify the company risk as low, medium, or high based on its industry and country.\"}",
"formula_config": null,
"format_config": "{\"options\":[\"low\",\"medium\",\"high\"]}",
"created_at": "2026-05-20T09:14:00.000Z",
"updated_at": "2026-05-28T11:02:00.000Z",
"deleted_at": null
}
},
"relationships": {
"workspace": {
"data": {
"type": "workspace",
"id": "a1b2c3d4-0000-4000-8000-000000000001"
}
}
}
}
```
Source: `apps/api/src/database/entities/CustomColumn.ts` ยท domain: records / data-views ยท tier: Infrastructure