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

# Update a field

`PATCH /fields/{id}`

## Request

- Base URL: `https://api.parley.so/v1`
- URL: `https://api.parley.so/v1/fields/{id}`
- Auth: HTTP bearer

Rename a custom field, change its automation, or add, rename, and remove single_select options. Omitted properties are left unchanged, and the type can't change. System fields can't be updated. Requires the owner or admin role.

## Path parameters

- `id` string, required: The field ID.

## Request body

- object
  - `name` string: Field name. Unique among the fields of one record type.
  - `automation` 'off' | 'suggest' | 'auto': Whether Parley fills the field from emails and documents: off, suggest (proposes values for someone to accept), or auto (sets values directly).
  - `automationInstructions` string, nullable: Guidance Parley follows when it fills the field.
  - `options` object: Changes to a single_select field's options, applied as rename, then remove, then add. Options you don't mention are left unchanged.
    - `add` string[]: Labels to add at the end of the list. Labels that already exist are ignored.
    - `rename` object: Map from a current label to its new label. Records that use the old label get the new one. A rename whose old label is gone and whose new label exists is ignored, so repeating it is safe.
    - `remove` string[]: Labels to remove. Labels that don't exist are ignored. If records use a removed label, the update fails with 409 OPTIONS_IN_USE and lists them, unless clearRemovedValues is true.
    - `clearRemovedValues` boolean: Clear the value on records that use a removed option, instead of failing.

## Response `200`

OK

- Field
  - `id` string, required: The field ID.
  - `name` string, required: Field name. Unique among the fields of one record type.
  - `recordType` 'project' | 'account' | 'contact' | 'task', required: The kind of record the field belongs to.
  - `type` 'text' | 'long_text' | 'number' | 'boolean' | 'datetime' | 'email' | 'url' | 'address' | 'single_select' | 'collection' | 'user', required: The field's value type. It can't be changed after the field is created.
  - `options` string[], required: Option labels of a single_select field, in order. Empty for other types.
  - `automation` 'off' | 'suggest' | 'auto', required: Whether Parley fills the field from emails and documents: off, suggest (proposes values for someone to accept), or auto (sets values directly).
  - `automationInstructions` string, nullable, required: Guidance Parley follows when it fills the field.
  - `system` boolean, required: A built-in field. It can't be renamed, reconfigured, or deleted, but its values can be set like any other field's.
  - `readOnly` boolean, required: Parley maintains the field's values, so they can't be set through fields on a record.
  - `createdAt` string, date-time, required: When the field was created.
  - `updatedAt` string, date-time, required: When the field definition was last updated. Setting values on records does not change it.

## Other responses

- `400`: The request was invalid. VALIDATION_FAILED, INVALID_OPTIONS.
- `401`: Missing or invalid credentials. UNAUTHORIZED.
- `403`: You don't have permission. FORBIDDEN.
- `404`: Not found. NOT_FOUND.
- `409`: The request conflicts with the current state. NAME_TAKEN, OPTIONS_IN_USE, CONCURRENT_UPDATE.
- `429`: Too many requests, or a usage limit was reached. TOO_MANY_REQUESTS.

## Changes

- **2026-11-02** `6b78aeee07bc`: 1 breaking
  - added the pattern `^[^\p{Cc}\p{Bidi_Control}]*$` to the request property `name`

[Operation history](https://skmtc.dev/parley/apis/parley-api/changes/fields/:id/patch.md)

---

[API](https://skmtc.dev/parley/apis/parley-api.md) - [All operations](https://skmtc.dev/parley/apis/parley-api/llms.txt) - [OpenAPI document](https://skmtc.dev/parley/apis/parley-api/revisions/6b78aeee07bc?raw)