---
title: "List Custom Fields"
method: GET
path: "/api/v1/hris/custom-fields"
tags: ["Custom Fields", "Public API"]
---

# List Custom Fields

`GET /api/v1/hris/custom-fields`

## Request

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

Returns a paginated list of active custom fields. IDs are strings and each has a numeric `legacyId` companion for legacy integrations. Use this for active custom fields. For archived custom fields, use List Archived Custom Fields (`list-archived-custom-fields`) instead.

OAuth Scopes: employee:custom_fields

## Query parameters

- `page` integer
- `pageSize` integer

## Response `200`

Paginated list of active custom fields.

- object: A response object that contains a paginated list of results.
  - `data` object[]: The data for the current page.
    - `id` string: The string custom field or custom table ID.
    - `legacyId` integer: The legacy numeric custom field or custom table ID.
    - `name` string: The custom field or custom table name.
    - `type` string: The custom field or custom table type.
    - `isEncrypted` boolean: Whether the custom field is encrypted.
    - `isCalculated` boolean: Whether the custom field is calculated.
    - `isRequired` boolean: Whether the custom field is required.
    - `order` integer, nullable: The display order.
    - `pageId` string, nullable: The string parent tab/page ID.
    - `pageLegacyId` integer, nullable: The legacy numeric parent tab/page ID.
    - `sectionId` string, nullable: The string parent section ID.
    - `sectionLegacyId` integer, nullable: The legacy numeric parent section ID.
    - `customTableId` string, nullable: The string parent custom table ID when this is a custom table field.
    - `customTableLegacyId` integer, nullable: The legacy numeric parent custom table ID when this is a custom table field.
    - `sortOrderDirection` string, nullable: The custom table sort order direction.
    - `summarize` string, nullable: The custom table field summary setting.
    - `sortField` boolean, nullable: Whether this custom table field is the table sort field.
    - `values` object[], nullable: List values for list and multilist custom table fields.
      - `id` string: The string list value ID.
      - `legacyId` integer: The legacy numeric list value ID.
      - `display` string: The list value display name.
    - `fields` CustomFieldDefinitionResponseObject[], nullable: Fields on a custom table response.
      - `id` string: The string custom field or custom table ID.
      - `legacyId` integer: The legacy numeric custom field or custom table ID.
      - `name` string: The custom field or custom table name.
      - `type` string: The custom field or custom table type.
      - `isEncrypted` boolean: Whether the custom field is encrypted.
      - `isCalculated` boolean: Whether the custom field is calculated.
      - `isRequired` boolean: Whether the custom field is required.
      - `order` integer, nullable: The display order.
      - `pageId` string, nullable: The string parent tab/page ID.
      - `pageLegacyId` integer, nullable: The legacy numeric parent tab/page ID.
      - `sectionId` string, nullable: The string parent section ID.
      - `sectionLegacyId` integer, nullable: The legacy numeric parent section ID.
      - `customTableId` string, nullable: The string parent custom table ID when this is a custom table field.
      - `customTableLegacyId` integer, nullable: The legacy numeric parent custom table ID when this is a custom table field.
      - `sortOrderDirection` string, nullable: The custom table sort order direction.
      - `summarize` string, nullable: The custom table field summary setting.
      - `sortField` boolean, nullable: Whether this custom table field is the table sort field.
      - `values` object[], nullable: List values for list and multilist custom table fields.
        - `id` string: The string list value ID.
        - `legacyId` integer: The legacy numeric list value ID.
        - `display` string: The list value display name.
      - `fields` CustomFieldDefinitionResponseObject[], nullable: Fields on a custom table response.
  - `meta` PaginationMetaData: A response object that contains pagination metadata.
    - `page` integer: The page number of the results.
    - `pageSize` integer: The number of items per page.
    - `totalPages` integer: The total number of pages available.
    - `totalItems` integer: The total number of items available.
  - `_links` object, nullable: Hypermedia links for collection navigation (next, prev) and available collection actions (e.g., create). Actions are permission-based and may vary.

## Other responses

- `401`: Unauthorized.
- `403`: Forbidden.
- `422`: Invalid pagination.
- `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-fields/get.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)