---
title: "Updating an existing Custom Field"
method: PUT
path: "/custom_fields/{id}"
tags: ["Custom Fields"]
---

# Updating an existing Custom Field

`PUT /custom_fields/{id}`

## Request

- Base URL: `https://api.mavenlink.com/api/v1`
- URL: `https://api.mavenlink.com/api/v1/custom_fields/{id}`
- Auth: none declared

Updates an existing custom field.

### Parameters that cannot be updated
Note that the `unique_constraint` and `value_type` parameters cannot be updated.
They are set during the process of [creating a custom field](/tag/Custom-Fields#operation/create-custom-field).

### Updating choices
This endpoint also allows you to update the list of choices for a custom field with
[single or multiple choices](/tag/Custom-Field-Choices). For important details
regarding how this endpoint affects the list of available choices and how to avoid
creating duplicate choices, see the description of the `choice` body parameter.


This endpoint returns structured Custom Field objects.
As with all Kantata OX API endpoints, the returned data will be referenced in sorted order in the `results` array
and will be indexed by ID in the `custom_fields` top-level JSON key.
Please see our [Response Format](#section/Response-Format) section for more information.

## Path parameters

- `id` integer, required

## Query parameters

- `include` string

## Request body

- object
  - `custom_field` object
    - `name` string: The name of the field.
    - `default_text` string: The message in an empty custom field, before a `string`, `date`, `number`, or `currency` value is entered in. This only appears in the UI.
    - `choices` object[]: The list of [choices](/tag/Custom-Field-Choices) a user can select from, for a custom field's value(s). Setting this field updates a custom field's complete list of choices; it behaves as an overwrite. **Include all existing choices in your request, whether you are updating their `label` or not.** Any choices not included in your request *will be deleted* from the custom field. **How to avoid creating duplicate choices** Choices have two attributes, a `label` and an `ID`. Different choices can have the same `label`, but every choice has a unique `ID`. To properly update an existing choice within a list, you must specify the `ID` of the choice you want to change. If you do not, a new choice with a unique, new `ID` is created instead. For example: ``` custom_field_choices: { .... choices: [ { "label": "Choice A", "id": "180291" }, { "label": "Choice B", "id": "180301" }, { "label": "Choice C" } ] .... } ``` Choices in the UI appear in the same order as listed in the array. The 1st choice is an existing choice with an ID of `180291`, and is either staying or being updated to `Choice A`. The 2nd choice is an existing choice with an ID of `180301`, and is either staying or being updated to `Choice B`. The 3rd choice is a new choice to create, `Choice C`, and its unique ID will be returned in the response.
      - `label` string: You can think of a label as the actual value a user can select for the custom field. *Note:* Different choices can have the same `label`.
      - `id` integer: The unique ID of an existing choice(s). If you do not specify the `ID` of an existing choice in an update request, a new choice with a unique, new `ID` is generated instead. Use this parameter to avoid replacing existing choices with new ones.
    - `custom_field_set_id` integer: The ID of the [Custom Field Set](/tag/Custom-Field-Sets) that the field belongs to. When a set ID is not specified, the field is added to a Project set titled 'Default Project Set'. This means it becomes a Project field.
    - `write_access` string: The permission level required for a user to create, update, or delete a custom field value for a subject.
    - `read_access` string: The `read_access` [permission setting on each custom field](https://knowledge.kantata.com/hc/en-us/articles/202924760#see) determines the minimum permission needed to view a custom field and its value. * `Workspace` (Project), `Resource`, and `Story` (Task) custom fields are project-specific objects, so their minimum permissions are set at the [project level](https://knowledge.kantata.com/hc/en-us/articles/115002779293-Project-Permissions): - `project_collaboration` (default) - `time_logging` - `financial` - `project_admin` Most account-level permissions supercede project-level permissions. Therefore, Account Administrators are able to view all Project, Resource, and Task custom fields and values across the account, regardless of project participation or `read_access` settings. * `Estimate`, `WorkspaceGroup` (Group), and `User` custom fields are account-wide objects, so their minimum permissions are set at the [account level](https://knowledge.kantata.com/hc/en-us/articles/203041364): - `account_collaboration` - `project_creator` - `project_lead` - `reports_viewer` - `reports_viewer_with_cost` - `account_admin` (default).

## Response `200`

Custom Field has been updated.

- object
  - `count` integer
  - `meta` object
    - `count` integer
    - `page_count` integer
    - `page_number` integer
    - `page_size` integer
  - `results` object[]
    - `key` string
    - `id` string
  - `custom_fields` object
  - `external_references` object
  - `users` object
  - `custom_field_choices` object
  - `custom_field_sets` object

## Other responses

- `400`: Bad Request
- `401`: Unauthorized request
- `403`: Forbidden request
- `404`: Page Not Found
- `422`: Unprocessable Entity
- `503`: Service is unavailable

---

[API](https://skmtc.dev/kantata/apis/kantata-ox-api-documentation.md) - [All operations](https://skmtc.dev/kantata/apis/kantata-ox-api-documentation/llms.txt) - [OpenAPI document](https://skmtc.dev/kantata/apis/kantata-ox-api-documentation/revisions/9d4ebed2fa98?raw)