# Updating an existing Custom Field

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.

### Updating choices
This endpoint also allows you to update the list of choices for a custom field with
single or multiple 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 for more information.

Endpoint: PUT /custom_fields/{id}
Version: 1.0.0

## Path parameters:

  - `id` (integer, required)
    The ID of the Model.

## Query parameters:

  - `include` (string)
    Any of the below associations can be included in your request by providing the include param, e.g. include=association1,association2.
- choices (CustomFieldChoice) - Includes the ID of a Custom Field's choices.
- creator (User) - Includes the ID of a Custom Field's creator.
- custom_field_set (CustomFieldSet) - Includes the ID of the Custom Field Set that a field belongs to.
- external_references (ExternalReference) - Includes references to external integrations for this object.

## Request fields (application/json):

  - `custom_field` (object)

  - `custom_field.name` (string)
    The name of the field.

  - `custom_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.

  - `custom_field.choices` (array)
    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.

  - `custom_field.choices.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.

  - `custom_field.choices.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.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.

  - `custom_field.write_access` (string)
    The permission level required for a user to create, update, or delete a custom field value for a subject.

  - `custom_field.read_access` (string)
    The read_access [permission setting on each custom field](https://mavenlink.zendesk.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://mavenlink.zendesk.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://mavenlink.zendesk.com/hc/en-us/articles/203041364):
  - account_collaboration
  - project_creator
  - project_lead
  - reports_viewer
  - reports_viewer_with_cost
  - account_admin (default).

## Response 200 fields (application/json):

  - `count` (integer)

  - `meta` (object)

  - `meta.count` (integer)

  - `meta.page_count` (integer)

  - `meta.page_number` (integer)

  - `meta.page_size` (integer)

  - `results` (array)

  - `results.key` (string)

  - `results.id` (string)

  - `custom_fields` (object)

  - `external_references` (object)

  - `users` (object)

  - `custom_field_choices` (object)

  - `custom_field_sets` (object)

## Response 400 fields (application/json):

  - `errors` (array)

  - `errors.type` (string)

  - `errors.message` (string)