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

PublicApiKey

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

429

Returned when the rate limit is exceeded

get/api/v1/public/custom-columns

HTTPcURLJavaScriptPython

GET /api/v1/public/custom-columns HTTP/1.1
x-api-key: YOUR_API_KEY
Accept: */*

{
  "data": [
    {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "name": "text",
      "column_type": "text",
      "is_required": true,
      "status": "active",
      "config": {
        "min_chars": 1,
        "max_chars": 1
      },
      "deleted_at": "2026-07-10T16:16:00.172Z"
    }
  ],
  "meta": {
    "total": 1,
    "lastPage": 1,
    "currentPage": 1,
    "perPage": 1,
    "prev": 1,
    "next": 1
  }
}

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

{ "assignee_type": "user" }

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

{ "true_label": "Yes", "false_label": "No" }

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

choice

{ "choice_type": "single" }

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:

[{ "name": "Low", "position": 0 }, { "name": "High", "position": 1 }]

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

{
  "create": [{ "name": "New option", "position": 2 }],
  "update": [{ "id": "uuid", "name": "Renamed", "position": 0 }],
  "remove": ["uuid-of-option-to-delete"]
}

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:

["b86fa12a-76fc-46f5-8a3e-bf39e7be4c4e", "c91a..."]

On update, use the management object:

{
  "create": ["uuid-of-entity-to-allow"],
  "remove": ["uuid-of-people-option-row-to-remove"]
}

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

Concrete create-body examples

// TEXT
{ "module": "production", "column_type": "text", "name": "Notes", "status": "active",
  "config": { "min_chars": 0, "max_chars": 500 } }

// NUMBER
{ "module": "order", "column_type": "number", "name": "Weight", "status": "active",
  "config": { "number_type": "decimal" } }

// DATE_TIME
{ "module": "production", "column_type": "date_time", "name": "Delivered at", "status": "active",
  "config": { "time_type": "date_time" } }

// PEOPLE (any active user is allowed)
{ "module": "production", "column_type": "people", "name": "Reviewer", "status": "active",
  "config": { "assignee_type": "user" } }

// PEOPLE (restricted to specific user ids)
{ "module": "production", "column_type": "people", "name": "Approvers", "status": "active",
  "config": { "assignee_type": "user" },
  "people_options": ["b86fa12a-76fc-46f5-8a3e-bf39e7be4c4e", "c91…"] }

// BOOLEAN
{ "module": "production", "column_type": "boolean", "name": "QA passed", "status": "active",
  "config": { "true_label": "Yes", "false_label": "No" } }

// CHOICE (single-select)
{ "module": "production", "column_type": "choice", "name": "Priority", "status": "active",
  "config": { "choice_type": "single" },
  "choice_options": [
    { "name": "Low", "position": 0 },
    { "name": "Medium", "position": 1 },
    { "name": "High", "position": 2 }
  ] }

Authorizations

PublicApiKey

x-api-keystringRequired

Header parameters

x-tenant-idstring · uuidOptional

Tenant id (uuid v4)

Body

application/json

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.

429

Returned when the rate limit is exceeded

post/api/v1/public/custom-columns

HTTPcURLJavaScriptPython

POST /api/v1/public/custom-columns HTTP/1.1
x-api-key: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 241

{
  "module": "inventory",
  "column_type": "text",
  "name": "text",
  "status": "active",
  "is_required": false,
  "config": {
    "min_chars": 1,
    "max_chars": 1
  },
  "choice_options": [
    {
      "label": "text",
      "position": 1
    }
  ],
  "people_options": [
    "123e4567-e89b-12d3-a456-426614174000"
  ]
}

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "name": "text",
  "column_type": "text",
  "is_required": true,
  "status": "active",
  "config": {
    "min_chars": 1,
    "max_chars": 1
  },
  "deleted_at": "2026-07-10T16:16:00.172Z"
}

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

PublicApiKey

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.

429

Returned when the rate limit is exceeded

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

HTTPcURLJavaScriptPython

GET /api/v1/public/custom-columns/{id} HTTP/1.1
x-api-key: YOUR_API_KEY
Accept: */*

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "module": "inventory",
  "name": "text",
  "key": "text",
  "column_type": "text",
  "status": "active",
  "is_required": true,
  "config": {
    "min_chars": 1,
    "max_chars": 1
  },
  "choice_options": [
    {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "label": "text",
      "position": 1
    }
  ],
  "people_options": [
    {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "entity_id": "123e4567-e89b-12d3-a456-426614174000",
      "entity": {
        "id": "123e4567-e89b-12d3-a456-426614174000",
        "first_name": "text",
        "last_name": "text",
        "avatar_id": "text"
      }
    }
  ],
  "deleted_at": "2026-07-10T16:16:00.172Z"
}

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: active ↔ inactive 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

{ "assignee_type": "user" }

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

{ "true_label": "Yes", "false_label": "No" }

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

choice

{ "choice_type": "single" }

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:

[{ "name": "Low", "position": 0 }, { "name": "High", "position": 1 }]

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

{
  "create": [{ "name": "New option", "position": 2 }],
  "update": [{ "id": "uuid", "name": "Renamed", "position": 0 }],
  "remove": ["uuid-of-option-to-delete"]
}

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:

["b86fa12a-76fc-46f5-8a3e-bf39e7be4c4e", "c91a..."]

On update, use the management object:

{
  "create": ["uuid-of-entity-to-allow"],
  "remove": ["uuid-of-people-option-row-to-remove"]
}

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

Concrete create-body examples

// TEXT
{ "module": "production", "column_type": "text", "name": "Notes", "status": "active",
  "config": { "min_chars": 0, "max_chars": 500 } }

// NUMBER
{ "module": "order", "column_type": "number", "name": "Weight", "status": "active",
  "config": { "number_type": "decimal" } }

// DATE_TIME
{ "module": "production", "column_type": "date_time", "name": "Delivered at", "status": "active",
  "config": { "time_type": "date_time" } }

// PEOPLE (any active user is allowed)
{ "module": "production", "column_type": "people", "name": "Reviewer", "status": "active",
  "config": { "assignee_type": "user" } }

// PEOPLE (restricted to specific user ids)
{ "module": "production", "column_type": "people", "name": "Approvers", "status": "active",
  "config": { "assignee_type": "user" },
  "people_options": ["b86fa12a-76fc-46f5-8a3e-bf39e7be4c4e", "c91…"] }

// BOOLEAN
{ "module": "production", "column_type": "boolean", "name": "QA passed", "status": "active",
  "config": { "true_label": "Yes", "false_label": "No" } }

// CHOICE (single-select)
{ "module": "production", "column_type": "choice", "name": "Priority", "status": "active",
  "config": { "choice_type": "single" },
  "choice_options": [
    { "name": "Low", "position": 0 },
    { "name": "Medium", "position": 1 },
    { "name": "High", "position": 2 }
  ] }

Authorizations

PublicApiKey

x-api-keystringRequired

Path parameters

idstringRequired

Header parameters

x-tenant-idstring · uuidOptional

Tenant id (uuid v4)

Body

application/json

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.

429

Returned when the rate limit is exceeded

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

HTTPcURLJavaScriptPython

PUT /api/v1/public/custom-columns/{id} HTTP/1.1
x-api-key: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 426

{
  "column_type": "text",
  "name": "text",
  "is_required": true,
  "config": {
    "min_chars": 1,
    "max_chars": 1
  },
  "status": "active",
  "choice_options": {
    "create": [
      {
        "label": "text",
        "position": 1
      }
    ],
    "update": [
      {
        "id": "123e4567-e89b-12d3-a456-426614174000",
        "label": "text",
        "position": 1
      }
    ],
    "remove": [
      "123e4567-e89b-12d3-a456-426614174000"
    ]
  },
  "people_options": {
    "create": [
      "123e4567-e89b-12d3-a456-426614174000"
    ],
    "remove": [
      "123e4567-e89b-12d3-a456-426614174000"
    ]
  }
}

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "name": "text",
  "column_type": "text",
  "is_required": true,
  "status": "active",
  "config": {
    "min_chars": 1,
    "max_chars": 1
  },
  "deleted_at": "2026-07-10T16:16:00.172Z"
}

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

PublicApiKey

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

429

Returned when the rate limit is exceeded

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

HTTPcURLJavaScriptPython

DELETE /api/v1/public/custom-columns/{id} HTTP/1.1
x-api-key: YOUR_API_KEY
Accept: */*

{
  "message": "The operation was done successfully"
}

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

PublicApiKey

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

429

Returned when the rate limit is exceeded

post/api/v1/public/custom-columns/{id}/restore

HTTPcURLJavaScriptPython

POST /api/v1/public/custom-columns/{id}/restore HTTP/1.1
x-api-key: YOUR_API_KEY
Accept: */*

{
  "message": "The operation was done successfully"
}