---
title: "Update a custom field"
method: PATCH
path: "/custom-fields/{id}"
tags: ["custom-fields"]
---

# Update a custom field

`PATCH /custom-fields/{id}`

Updates a custom field definition. Only provided fields are modified.

**Rate limit:** 120 requests per minute

## Path parameters

- `id` string, required

## Request body

- UpdateCustomFieldRequestBody
  - `default_value` string — The default value for single-valued custom fields.
  - `default_values` string[] — The default values for multi-valued custom fields.
  - `description` string — The description of the custom field.
  - `label` string — The label of the custom field.
  - `select_options` CustomFieldDefinitionSelectOption[] — The complete list of options for a select or multiselect custom field. Options missing from the list are deleted and their stored values are cleared asynchronously. Prefer the dedicated select option endpoints, which can rename an option without losing stored values.
    - `ai_description` string — The AI description of the option. This is used to help the AI understand when to select this option.
    - `label` string — The label of the option.
    - `slug` string — The slug of the option.
  - `slug` string — The slug of the custom field.

## Response `200`

- UpdateCustomFieldResponseBody
  - `data` CustomFieldDefinition
    - `created_at` string — When the custom field was created.
    - `default_value` string — The default value for single-valued custom fields.
    - `default_values` string[] — The default values for multi-valued custom fields.
    - `description` string — The description of the custom field.
    - `id` string — The ID of the custom field.
    - `is_read_only` boolean — Whether the custom field is read only. Fields synced from apps and integrations are read-only.
    - `label` string — The label of the custom field.
    - `number_metadata` NumberMetadata
      - `currency` string — The currency of the number custom field.
      - `decimal_places` integer — The decimal places of the number custom field.
      - `duration_display_format` string — The display format for duration format (auto, minutes, hours, days, months, years).
      - `duration_input_unit` string — The input unit for duration format (seconds, minutes, hours, days).
      - `format` 'with_commas' | 'percent' | 'currency' | 'duration' — The format of the number custom field.
    - `object_type` string — The type of object this custom field is for. This can be a built-in or custom object type.
    - `select_metadata` SelectMetadata
      - `options` CustomFieldDefinitionSelectOption[] — The list options of the select custom field. This is only present for select and multiselect custom fields.
        - `ai_description` string — The AI description of the option. This is used to help the AI understand when to select this option.
        - `label` string — The label of the option.
        - `slug` string — The slug of the option.
    - `slug` string — The slug of the custom field.
    - `source` string — The source of the custom field.
    - `type` string — The type of the custom field.
    - `updated_at` string — When the custom field was last updated.
  - `request_id` string — The request ID for tracking.

## Other responses

- `400` — The request was invalid or could not be completed.
- `403` — The authenticated caller or organization is not allowed to access this endpoint or operation.
- `404`
- `500` — An unexpected internal error occurred.

## Changes

- **2026-08-28** `fe3adb90ea45` — 1 info
  - added the non-success response with the status `403`
- **2026-07-26** `3e347e631c35` — 2 info
  - added the new optional request property `select_options/items/ai_description`
  - added the optional property `data/select_metadata/options/items/ai_description` to the response with the `200` status

[Change history](https://skmtc.dev/usepylon/apis/pylon-api/changes/custom-fields/:id/patch.md)

---

[API](https://skmtc.dev/usepylon/apis/pylon-api.md) · [All operations](https://skmtc.dev/usepylon/apis/pylon-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/usepylon/pylon-api/revisions/b4fea6aa5ea6/schema)