For the complete documentation index, see llms.txt. This page is also available as Markdown.

Custom Columns

List custom columns

get

Returns every custom column on the tenant — across all modules and statuses (including soft-deleted) — paginated.

Query

  • search (optional) — substring match on name, case-insensitive.

  • skip / take (optional) — standard offset pagination; defaults to skip = 0, take = 20.

Authorizations
x-api-keystringRequired
Query parameters
searchstring · max: 200Optional

Substring match on name, case-insensitive.

skipnumberOptional
takenumberOptional
Header parameters
x-tenant-idstring · uuidOptional

Tenant id (uuid v4)

Responses
200Success
application/json
get/api/v1/public/custom-columns

Create custom column

post

Creates a new custom column on a given module.

Notes

  • column_type is immutable after creation.

  • status on create must be active or inactive. Use the delete endpoint to soft-delete.

  • The per-module field limit is enforced; creation fails with 409 if reached.

config field — what to pass for each column_type

The config object is polymorphic: its required shape is determined by the sibling column_type value. The server validates the combination — sending a config that doesn't match the column type is rejected with 400.

text

{ "min_chars": 0, "max_chars": 500 }

Both min_chars and max_chars are optional (nullable). Bounds are inclusive. null or omitted = no limit on that side. Constraints: min_chars >= 0, max_chars >= 1.

number

{ "number_type": "integer" }

Required. Allowed values: "integer", "decimal". Controls the input widget and validation on stored values.

date_time

{ "time_type": "date_time" }

Required. Allowed values: "date_time" (date + time), "date_only", "time_only".

people

Required. Allowed values: "user", "department", "position". Determines the kind of entity ids that people_options (and stored values) must reference. Immutable in practice — changing it invalidates existing options.

boolean

Both labels required and non-empty. Shown in the UI for the two states.

choice

Required. Allowed values: "single" (one choice per row) or "multi" (many). Use the choice_options array (see below) to define the options themselves.

Companion arrays

choice_options — required for choice columns on create; ignored for other column types. Must contain at least one entry of the form:

position is the display order (integer, >= 0). On update, use the nested management object instead:

people_options — only valid for people columns. On create, pass an array of entity uuids matching config.assignee_type (user / department / position ids). Empty or omitted = all active entities of that type are allowed:

On update, use the management object:

Note: remove takes people-option row ids (as returned by the get-by-id endpoint), not entity ids.

Concrete create-body examples

Authorizations
x-api-keystringRequired
Header parameters
x-tenant-idstring · uuidOptional

Tenant id (uuid v4)

Body
modulestring · enumRequiredPossible values:
column_typestring · enumRequired

Immutable after create.

Possible values:
namestring · min: 1Required
statusstring · enumRequired

Initial status. DELETED is not allowed on create.

Possible values:
is_requiredbooleanOptionalDefault: false
configone ofRequired

Type-specific config. Shape and required fields depend on column_type.

or
or
or
or
or
people_optionsstring · uuid[]Optional

List of allowed entity IDs (user.id / department.id / position.id depending on config.assignee_type). Only valid when column_type = PEOPLE. Empty/omitted = all active entities of the chosen assignee_type are allowed. Ignored for other types.

Responses
201Success
application/json
idstring · uuidRequired
namestringRequired
column_typestring · enumRequiredPossible values:
is_requiredbooleanRequired
statusstring · enumRequiredPossible values:
configone ofRequired

Type-specific config. Shape depends on column_type.

or
or
or
or
or
deleted_atstring · date-time · nullableOptional

Set when status = DELETED. Anchors the 30-day permanent deletion countdown.

post/api/v1/public/custom-columns

Get custom column by id

get

Returns the full custom column record, including choice_options (for choice columns) and people_options resolved to display entities (for people columns).

Soft-deleted columns are returned (the response includes deleted_at and status = deleted).

Authorizations
x-api-keystringRequired
Path parameters
idstringRequired
Header parameters
x-tenant-idstring · uuidOptional

Tenant id (uuid v4)

Responses
200Success
application/json
idstring · uuidRequired
modulestring · enumRequiredPossible values:
namestringRequired
keystringRequired

Stable slug used in API & integrations. Immutable after create.

column_typestring · enumRequiredPossible values:
statusstring · enumRequiredPossible values:
is_requiredbooleanRequired
configone ofRequired

Type-specific config. Shape depends on column_type.

or
or
or
or
or
deleted_atstring · date-time · nullableOptional

Set when status = DELETED. Anchors the 30-day permanent deletion countdown.

get/api/v1/public/custom-columns/{id}

Update custom column

put

Updates a custom column. Any field not provided is left unchanged.

Notes

  • column_type must match the persisted column type. Sending a different value is rejected with 400.

  • Status transitions: activeinactive freely. deleted soft-deletes the column.

  • Deleted columns cannot be edited — restore first.

config field — what to pass for each column_type

The config object is polymorphic: its required shape is determined by the sibling column_type value. The server validates the combination — sending a config that doesn't match the column type is rejected with 400.

text

{ "min_chars": 0, "max_chars": 500 }

Both min_chars and max_chars are optional (nullable). Bounds are inclusive. null or omitted = no limit on that side. Constraints: min_chars >= 0, max_chars >= 1.

number

{ "number_type": "integer" }

Required. Allowed values: "integer", "decimal". Controls the input widget and validation on stored values.

date_time

{ "time_type": "date_time" }

Required. Allowed values: "date_time" (date + time), "date_only", "time_only".

people

Required. Allowed values: "user", "department", "position". Determines the kind of entity ids that people_options (and stored values) must reference. Immutable in practice — changing it invalidates existing options.

boolean

Both labels required and non-empty. Shown in the UI for the two states.

choice

Required. Allowed values: "single" (one choice per row) or "multi" (many). Use the choice_options array (see below) to define the options themselves.

Companion arrays

choice_options — required for choice columns on create; ignored for other column types. Must contain at least one entry of the form:

position is the display order (integer, >= 0). On update, use the nested management object instead:

people_options — only valid for people columns. On create, pass an array of entity uuids matching config.assignee_type (user / department / position ids). Empty or omitted = all active entities of that type are allowed:

On update, use the management object:

Note: remove takes people-option row ids (as returned by the get-by-id endpoint), not entity ids.

Concrete create-body examples

Authorizations
x-api-keystringRequired
Path parameters
idstringRequired
Header parameters
x-tenant-idstring · uuidOptional

Tenant id (uuid v4)

Body
column_typestring · enumRequired

Must match the column's persisted type. Sending a different value is rejected.

Possible values:
namestring · min: 1Optional
is_requiredbooleanOptional
configone ofOptional

Type-specific config. Validated against column_type at the pipe stage.

or
or
or
or
or
statusstring · enumOptional

ACTIVE ↔ INACTIVE freely; DELETED soft-deletes the column. Restoring a DELETED column uses the restore endpoint.

Possible values:
Responses
200Success
application/json
idstring · uuidRequired
namestringRequired
column_typestring · enumRequiredPossible values:
is_requiredbooleanRequired
statusstring · enumRequiredPossible values:
configone ofRequired

Type-specific config. Shape depends on column_type.

or
or
or
or
or
deleted_atstring · date-time · nullableOptional

Set when status = DELETED. Anchors the 30-day permanent deletion countdown.

put/api/v1/public/custom-columns/{id}

Soft-delete custom column

delete

Soft-deletes a custom column. Permanent deletion runs after 30 days.

Calling this endpoint sets status = deleted and stamps deleted_at. Use the restore endpoint to bring it back within the retention window.

Authorizations
x-api-keystringRequired
Path parameters
idstringRequired
Header parameters
x-tenant-idstring · uuidOptional

Tenant id (uuid v4)

Responses
200Success
application/json
messagestringRequired

Message returned from API confirming the operation

Example: The operation was done successfully
delete/api/v1/public/custom-columns/{id}

Restore custom column

post

Restores a soft-deleted custom column to status = active and clears deleted_at.

Fails with 409 if the per-module field limit is already reached — delete another column first.

Authorizations
x-api-keystringRequired
Path parameters
idstringRequired
Header parameters
x-tenant-idstring · uuidOptional

Tenant id (uuid v4)

Responses
201Success
application/json
messagestringRequired

Message returned from API confirming the operation

Example: The operation was done successfully
post/api/v1/public/custom-columns/{id}/restore

Last updated