---
title: "Add Custom Field List Value"
method: POST
path: "/api/v1/hris/custom-fields/{customFieldId}/list-values"
tags: ["Custom Fields", "Public API"]
---

# Add Custom Field List Value

`POST /api/v1/hris/custom-fields/{customFieldId}/list-values`

## Request

- Base URL: `https://companySubDomain.bamboohr.com`
- URL: `https://companySubDomain.bamboohr.com/api/v1/hris/custom-fields/{customFieldId}/list-values`
- 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-fields/:customFieldId/list-values/post.ts> (a function with typed inputs; its response is checked against the schema)

Adds one or more dropdown options to a list-type custom field.

OAuth Scopes: employee:custom_fields.write

## Path parameters

- `customFieldId` string, required

## Request body

- object
  - `option` string: A single new list value.
  - `values` string[]: Multiple new list values.

## Response `201`

List value(s) added. A single "option" in the request body returns one object; a "values" array returns an array of objects.

- union
  - object
    - `id` string: The string list value ID.
    - `legacyId` integer: The legacy numeric list value ID.
    - `display` string: List value display name.
  - object[]
    - `id` string: The string list value ID.
    - `legacyId` integer: The legacy numeric list value ID.
    - `display` string: List value display name.

## Other responses

- `400`: Invalid argument.
- `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-fields/:customFieldId/list-values/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)