---
title: "Update List Field Values"
method: PUT
path: "/api/v1/meta/lists/{listFieldId}"
tags: ["Account Information", "Public API"]
---

# Update List Field Values

`PUT /api/v1/meta/lists/{listFieldId}`

Create, update, or archive options for a list field. To update an existing option, specify its `id`. To create a new option, omit `id`. To archive an option, set `archived` to `yes` — the option is soft-deleted and will continue to appear in GET responses for historical data integrity. To reactivate an archived option, set `archived` to `no`. The `archivedDate` field is server-set when an option is first archived and is not cleared if the option is later reactivated. Options on list fields with `manageable: no` cannot be modified and will return a 405.

OAuth Scopes: field.write

## Path parameters

- `listFieldId` string, required

## Query parameters

- `format` 'json'

## Request body

- ListFieldValues — Payload for creating, updating, or archiving options on a list field.
  - `options` object[] — The list field options to create, update, or archive.
    - `id` integer — The existing option ID. Omit this field to create a new option. Required when archiving an existing option.
    - `value` string — The display value for the option. Required when creating a new option (i.e., when id is omitted).
    - `archived` 'yes' | 'no' — Whether the option should be archived. Use `yes` to soft-delete an option or `no` to reactivate a previously archived option. Archived options continue to appear in GET responses for historical data integrity.
    - `adpCode` string — Optional payroll-mapping code associated with the option.

## Response `200`

All requested changes were applied. Returns the full updated list.

- ListFieldDetail — A single list field and its available options.
  - `id` integer — The list ID.
  - `fieldId` integer — The field ID.
  - `name` string — The display name of the list field.
  - `alias` string, nullable — The API alias for the list field.
  - `manageable` 'yes' | 'no' — Whether the list field options can be modified via the API.
  - `multiple` 'yes' | 'no' — Whether this field supports multiple values.
  - `options` ListFieldOption[] — The available options for this list field.
    - `id` integer — The option ID.
    - `name` string — The display value of the option. In XML format, this is the text content of the <option> element.
    - `archived` 'yes' | 'no' — Whether this option is archived. Archived options are preserved for historical data integrity and continue to appear in responses. Filter by archived: no to show only active options.
    - `createdDate` string, nullable — The date the option was created, in ISO 8601 format. Server-set on creation; not client-supplied.
    - `archivedDate` string, nullable — The date the option was archived, in ISO 8601 format. Server-set when archived is first set to yes; persists even if the option is later un-archived.
    - `manageable` 'yes' | 'no' — Whether this individual option can be modified via the API.
    - `frequency` string, nullable — The pay frequency for the option. Only present on pay-group list fields.

## Other responses

- `400` — The request body is invalid or malformed.
- `403` — The list is not editable, or the authenticated caller does not have sufficient permissions.
- `404` — The specified list field or option ID does not exist.
- `405` — One or more of the specified options belong to a non-manageable list field and cannot be modified.
- `409` — A duplicate list value conflicted with the value specified.

---

[API](https://skmtc.net/bamboohr/apis/bamboohr-api.md) · [All operations](https://skmtc.net/bamboohr/apis/bamboohr-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/bamboohr/bamboohr-api/versions/19ebf391a399/schema)