--- title: "Update Custom Table" method: PUT path: "/api/v1/hris/custom-tables/{customTableId}" tags: ["Custom Tables", "Public API"] --- # Update Custom Table `PUT /api/v1/hris/custom-tables/{customTableId}` ## Request - Base URL: `https://companySubDomain.bamboohr.com` - URL: `https://companySubDomain.bamboohr.com/api/v1/hris/custom-tables/{customTableId}` - Auth: OAuth 2 - Authorization code: `/authorize.php` - Token URL: `/token.php` scopes: `employee:custom_fields.write` - TypeScript: (a function with typed inputs; its response is checked against the schema) Updates an existing custom table's metadata and, optionally, replaces its full set of columns. Requires the acting user to be an owner-admin. The `tab` value is the target tab's page ID; use Custom Fields > List Custom Fields (`list-custom-fields`) to find the `pageId` of an existing field on the desired tab — changing `tab` moves the table to that page. Any `id` in the request body is ignored; the table edited is always the one identified by the path. Omitted optional fields reset rather than persist: leaving out `allowEdits` resets it to `true`, and leaving out `sortOrderDirection` resets it to `desc`. Omitting `columns` leaves existing columns unchanged; including `columns` replaces the entire column set, deleting any existing column whose `id` is not present in the array — include a column's `id` to update it in place, or omit `id` to add a new column. To add a single column without resending the rest, use Create Custom Table Field (`create-public-custom-table-field`) instead; to delete a single column without resending the rest, use Delete Custom Table Field (`delete-public-custom-table-field`) instead; to reorder columns without resending field definitions, use Reorder Custom Table Fields (`reorder-public-custom-table-fields`) instead. A request that changes nothing returns the table unchanged rather than an error. OAuth Scopes: employee:custom_fields.write ## Path parameters - `customTableId` string, required ## Request body - object: For editing a table, `columns` is optional; when provided, it replaces the table's entire column set. - `id` integer: The id of the Custom Table. Ignored on write: the table id always comes from the path (edit) or is assigned by the server (create). - `name` string, required: The name of the Custom Table to be edited / created - `type` 'grid' | 'history', required: The type of the Custom Table to be edited / created - `tab` union, required: The id of the tab where the Custom Table will be added or moved. Accepts either the integer or numeric-string form of a page id, such as the `pageId` returned by List Custom Fields. - integer - string - `sortOrderDirection` 'asc' | 'desc': The sort order direction of the Custom Table - `allowEdits` boolean: Whether the Custom Table allows edits or not - `columns` CustomTableFieldRequest[]: The columns of the Custom Table to be edited / created - `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: The name of the Custom Table Field to be edited / created - `type` 'text' | 'textarea' | 'list' | 'multilist' | 'checkbox' | 'dollar' | 'date' | 'int' | 'percentage' | 'phone' | 'state' | 'employee': 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 `200` The updated custom table object. - CustomTableViewObject - `id` integer: The id of the Custom Table - `name` string: The name of the Custom Table - `type` string: The type of the Custom Table - `isEncrypted` boolean: Whether the Custom Table is encrypted or not - `isCalculated` boolean: Whether the Custom Table is calculated or not - `isRequired` boolean: Whether the Custom Table is required or not - `order` integer: The order of the Custom Table - `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 - `fields` CustomTableFieldViewObject[]: The fields of the 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 - `sortOrderDirection` string: The sort order direction of the Custom 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/put.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)