---
title: "Create a custom column"
method: POST
path: "/v1/custom_columns"
tags: ["Custom column"]
---

# Create a custom column

`POST /v1/custom_columns`

## Request

- Base URL: `https://api.cardda.com`
- URL: `https://api.cardda.com/v1/custom_columns`
- Auth: HTTP bearer

Creates a custom column in the company of the `company-id` header. Requires the
`custom_columns_create` permission on the company. A `company_id` in the body is ignored.

## Headers

- `company-id` string, uuid, required

## Request body

- CustomColumnCreate: Payload to create a custom column. Requires the `custom_columns_create` permission on the company. The column is created in the company of the `company-id` header; a `company_id` in the body is ignored.
  - `label` string, required: Human-facing label.
  - `internal_name` string, required: Internal name used for programmatic references.
  - `field` string, required: The field/input type of the column.
  - `source_table` string: The source table the column reads from, when applicable.
  - `default_value` string: Default value applied when no value is set.
  - `applicable_models` string[], required
  - `options` object[]
    - `key` string
    - `value` string
  - `required_on_purchase_orders` boolean: Whether a purchase order cannot be requested without this column. Only valid on a column whose `applicable_models` include `purchase_orders` (422 otherwise); removing `purchase_orders` from them later switches it off. Only honoured when the caller has `custom_columns_manage`: without it, it is silently dropped. Applies on create (the order must be born with a value) and on edit (a value cannot be emptied); orders that already existed are not changed.

## Response `201`

Custom column created

- CustomColumn: A custom column definition — a company-configurable field ("rendición" / expense-tracking metadata) that can be attached to transactions and other applicable models. Values are stored per record and surfaced through `custom_column_values`.
  - `id` string, uuid, required
  - `company_id` string, uuid, required
  - `label` string: Human-facing label shown in the UI.
  - `internal_name` string, nullable: Internal name used for programmatic references.
  - `field` string: The field/input type of the column. `options` drives a select-style column with a fixed set of choices.
  - `source_table` string, nullable: The source table the column reads from, when applicable.
  - `default_value` string, nullable: Default value applied when no value is set.
  - `applicable_models` string[]: The models this column applies to (e.g. `transactions`, `card_transactions`, `payables`).
  - `options` object[]: For option-type columns, the allowed key/value choices.
    - `key` string
    - `value` string
  - `required_on_purchase_orders` boolean: Whether a purchase order cannot be requested without this column. Only valid on a column whose `applicable_models` include `purchase_orders` (422 otherwise); removing `purchase_orders` from them later switches it off. Only honoured when the caller has `custom_columns_manage`: without it, it is silently dropped. Applies on create (the order must be born with a value) and on edit (a value cannot be emptied); orders that already existed are not changed.
  - `created_at` string, date-time
  - `updated_at` string, date-time

## Other responses

- `401`: Unauthorized
- `404`: Not Found — the `company-id` header is missing or names a company the caller does not belong to.
- `422`: Validation error

---

[API](https://skmtc.dev/cardda/apis/accounting-api.md) - [All operations](https://skmtc.dev/cardda/apis/accounting-api/llms.txt) - [OpenAPI document](https://skmtc.dev/cardda/apis/accounting-api/revisions/49cf78d0f7ab?raw)