---
title: "Create Custom Table Field"
method: POST
path: "/api/v1/hris/custom-tables/{customTableId}/fields"
tags: ["Custom Tables", "Public API"]
---

# Create Custom Table Field

`POST /api/v1/hris/custom-tables/{customTableId}/fields`

## Request

- Base URL: `https://companySubDomain.bamboohr.com`
- URL: `https://companySubDomain.bamboohr.com/api/v1/hris/custom-tables/{customTableId}/fields`
- Auth: OAuth 2
  - Authorization code: `/authorize.php`
  - Token URL: `/token.php` scopes: `employee:custom_fields.write`
- TypeScript: <https://skmtc.dev/bamboohr/apis/bamboohr-api/docs/api/v1/hris/custom-tables/:customTableId/fields/post.ts> (a function with typed inputs; its response is checked against the schema)

Add a new column to an existing custom table; the new column is appended after the table's current columns. Requires the acting user to be an owner-admin. To create a table together with its initial columns, use Create Custom Table (`create-public-custom-table`) instead. To edit an existing column or replace the table's full column set, use Update Custom Table (`update-public-custom-table`) instead. For a single standalone field not backed by a table, use Custom Fields > Create Custom Field (`create-public-custom-field`) instead.

OAuth Scopes: employee:custom_fields.write

## Path parameters

- `customTableId` string, required

## Request body

- object: Adds a new column; any `id` provided is ignored and a new field id is always assigned.
  - `id` integer: The id of the Custom Table Field to be edited. Provide the existing column's id to update it in place; omit to add a new column.
  - `tableId` integer: The id of the Custom Table where the Custom Table Field will be added
  - `name` string, required: The name of the Custom Table Field to be edited / created
  - `type` 'text' | 'textarea' | 'list' | 'multilist' | 'checkbox' | 'dollar' | 'date' | 'int' | 'percentage' | 'phone' | 'state' | 'employee', required: The type of the Custom Table Field to be edited / created
  - `sortField` boolean: Whether the Custom Table Field is a sort field or not
  - `display` boolean: Whether the Custom Table Field is displayed or not
  - `summarize` 'none' | 'total' | 'average': The summarize of the Custom Table Field to be edited / created
  - `values` string[]: The values of the Custom Table Field to be edited / created

## Response `201`

Custom table field added.

- CustomTableFieldViewObject: Represents a single field in a custom table
  - `id` integer: The id of the Custom Field
  - `name` string: The name of the Custom Field
  - `type` string: The type of the Custom Field
  - `isEncrypted` boolean: Whether the Custom Field is encrypted or not
  - `isCalculated` boolean: Whether the Custom Field is calculated or not
  - `isRequired` boolean: Whether the Custom Field is required or not
  - `order` integer: The order of the Custom Field
  - `summarize` 'none' | 'total' | 'average': The aggregation applied when computing totals for this field. Only meaningful for custom table columns; always "none" for standalone custom fields and for the custom table object itself.
  - `values` string[]: The values of the Custom Field
  - `sortField` boolean: Whether this field is used for sorting the table

## Other responses

- `401`: Unauthorized.
- `403`: Forbidden.
- `404`: Not found.
- `422`: Validation failed.
- `500`: Internal server error.

## Changes

- **2026-11-03** `922fc15f43a7`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/bamboohr/apis/bamboohr-api/changes/api/v1/hris/custom-tables/:customTableId/fields/post.md)

---

[API](https://skmtc.dev/bamboohr/apis/bamboohr-api.md) - [All operations](https://skmtc.dev/bamboohr/apis/bamboohr-api/llms.txt) - [OpenAPI document](https://skmtc.dev/bamboohr/apis/bamboohr-api/revisions/922fc15f43a7?raw)