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

> A Custom Column Value is one computed-or-entered cell: the value of a Custom Column for a single record

A Custom Column Value is one computed-or-entered cell: the value of a Custom Column for a single record. It is joined to its target record by the record's public UUID (record\_id) rather than a typed foreign key, which is what lets the same custom-column mechanism work across every records root. AI-computed values are written by the enrichment worker as structured JSON.

| Naming                          | Value                             |
| ------------------------------- | --------------------------------- |
| Object                          | Custom Column Value               |
| Resource type (JSON:API `type`) | `custom_column_value`             |
| Collection / records root       | — <sub>(not a records root)</sub> |
| REST base                       | `/v1/custom-column-values`        |
| Entity class                    | `CustomColumnValue`               |

<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/custom-column-values`         | 🟡 Planned |
| Retrieve  | `GET /v1/custom-column-values/{id}`    | 🟡 Planned |
| Create    | `POST /v1/custom-column-values`        | 🟡 Planned |
| Update    | `PATCH /v1/custom-column-values/{id}`  | 🟡 Planned |
| Delete    | `DELETE /v1/custom-column-values/{id}` | 🟡 Planned |

## Data model

### Attributes

| Field       | Type                    | Required | Constraints                                | Allowed values | Description                                                                                                                          |
| ----------- | ----------------------- | -------- | ------------------------------------------ | -------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
| value\_id   | string, UUID, 🔒 system | ✅ Yes    | unique; gen\_random\_uuid()                | —              | Public identifier of the value row.                                                                                                  |
| record\_id  | string (UUID)           | ✅ Yes    | max 255 chars; indexed with custom\_column | —              | Public UUID of the target record (e.g. a company\_id). NOT a typed FK — a root-agnostic join key, so one mechanism serves all roots. |
| root        | string                  | ✅ Yes    | max 50 chars; denormalized                 | A records root | The records root of the target record (denormalized from the column for fast filtering).                                             |
| value       | jsonb                   | ⚪ No     | nullable                                   | —              | The cell value. AI stores structured output: \{ value: "high" } for text/select, \{ value: 42, currency: "EUR" } for amount.         |
| created\_at | ISO 8601, 🔒 system     | —        | onCreate hook                              | —              | Creation timestamp.                                                                                                                  |
| updated\_at | ISO 8601, 🔒 system     | —        | onCreate + onUpdate hooks; nullable        | —              | Last-update timestamp (recompute overwrites it).                                                                                     |

### Relationships

| Name           | Type                    | Required | Description                                                                                                |
| -------------- | ----------------------- | -------- | ---------------------------------------------------------------------------------------------------------- |
| custom\_column | to-one (custom\_column) | ✅ Yes    | The column definition this value belongs to. deleteRule: cascade — deleting the column deletes its values. |

### System-computed

* value\_id generated by gen\_random\_uuid()
* created\_at via onCreate; updated\_at via onCreate + onUpdate hooks
* NO deleted\_at — values are not soft-deleted; they cascade-delete with their custom\_column (deleteRule: cascade)
* Indexed on (custom\_column, record\_id)
* record\_id is the target record's PUBLIC UUID (root-agnostic join key) — no FK to the underlying entity table
* value shape is written by the enrichment worker: { value } or { value, currency } for amount columns

## Example

```json theme={null}
{
  "data": {
    "type": "custom_column_value",
    "id": "e4d5c6b7-1111-4111-8111-aaaabbbbcccc",
    "attributes": {
      "value_id": "e4d5c6b7-1111-4111-8111-aaaabbbbcccc",
      "root": "companies",
      "record_id": "3fa1c2d4-87ae-4b10-a9f3-ec5d1234abcd",
      "value": {
        "value": "high"
      },
      "created_at": "2026-05-20T09:15:30.000Z",
      "updated_at": "2026-05-28T11:03:00.000Z"
    }
  },
  "relationships": {
    "custom_column": {
      "data": {
        "type": "custom_column",
        "id": "7c1f9a02-4d3b-4e21-9a77-2f0c11aa33bc"
      }
    }
  }
}
```

<sub>Source: `apps/api/src/database/entities/CustomColumnValue.ts` · domain: records / data-views · tier: Infrastructure</sub>