---
title: "Update a field"
method: PUT
path: "/api/board/{boardId}/configuration/fields/{fieldUuid}"
tags: ["Board"]
---

# Update a field

`PUT /api/board/{boardId}/configuration/fields/{fieldUuid}`

## Request

- Base URL: `https://core-api.getaptly.com`
- URL: `https://core-api.getaptly.com/api/board/{boardId}/configuration/fields/{fieldUuid}`
- Auth: one of:
  - API key in header `x-token`
  - HTTP bearer
- TypeScript: <https://skmtc.dev/getaptly/apis/aptly-api/docs/api/board/:boardId/configuration/fields/:fieldUuid/put.ts> (a function with typed inputs; its response is checked against the schema)

Updates a field's `name`, `optional`, `pinned`, `startCard`, `defaultValue` and - for select-type fields -
its full `data` option list. A field's `type` and `uuid` never change. Options re-sent by label
keep their uuid. Refused (403) for locked fields - except `startCard`, which any field accepts - and the options of integration-managed
fields. Requires `update` permission and "Edit Boards" access (not needed on a board that
same key created).

Renaming a field also rewrites its `Board["Field"]` merge tokens in the company's templates
(best-effort: a failure there never fails the update).

**Editing the stage pipeline** (`fieldUuid` = `stage`): send the full `data` list in the order
you want. You can add stages, reorder them and recolor them. Existing stages are matched by
`uuid` (or by `label` when you leave `uuid` out) and keep their `uuid`. A stage that isn't
matched is added: it gets a new `uuid` and may set `color`, `closed` and `won` (`won` is for
deal boards only and implies `closed`). Cards, automations and saved filters refer to stages
by name, so these are refused with 403: leaving an existing stage out (removing it), changing
an existing stage's `label` (renaming it) and changing an existing stage between open,
closed and won. The first stage is where new cards start, so whichever stage ends up first
must be open (unless it was already first). Labels must be unique and there can be at most 30
stages. Board views that are open in the Aptly app refresh to show the change.

## Path parameters

- `boardId` string, required
- `fieldUuid` string, required

## Request body

- object
  - `name` string
  - `optional` boolean
  - `pinned` boolean
  - `startCard` boolean: Show the field on the form when a card is created.
  - `defaultValue` string
  - `data` object[]
    - `label` string, required
    - `uuid` string
    - `color` string: Stage field only. Hex color.
    - `closed` boolean: Stage field only. For an existing stage it must match the stage as it is; for a new stage it makes it a closed stage.
    - `won` boolean: Stage field only. For an existing stage it must match the stage as it is; for a new stage on a deal board it makes it a won stage.

## Response `200`

The updated field.

- object
  - `data` BoardField
    - `uuid` string: Unique field identifier — use this as the key when reading/writing card data.
    - `name` string: Display name of the field.
    - `type` string: Field type. Fields created through the API use one of the types in `NewBoardFieldType` (`string`, `text`, `rich-text`, `number`, `money`, `percent`, `multiplier`, `boolean`, `date`, `datetime-local`, `email`, `emails`, `tel`, `phones`, `url`, `address`, `person`, `persons`, `user`, `file`, `files`, `heroImage`, `embedVideo`, `stringList`, `tags`, `singleselect`, `multiselect`, `checkboxlist`). Mirror fields (a copy of another board's field) are added with `POST /api/board/{boardId}/configuration/mirror-fields` and take the mirrored field's type. Boards built in the Aptly app can also contain relational and system types, e.g. `stageselect`, `sourceselect`, `relatedAptlets`, `mirror`, `mirror-contact`, `location`, `unit`, `board`, `calculation`, `ai-computed`, `cardId`, `daysOpened`, `timeSince`, `qualified`, `lostReason`, `lostDetails`, `relatedEvents`, `relatedDocuments`, `contactType`, `teams`.
    - `position` integer: Display order (zero-based).
    - `optional` boolean: Whether the field is optional on cards.
    - `startCard` boolean: Whether the field is shown on the form when a card is created.
    - `archived` boolean: Whether the field has been archived (hidden from the UI).

## Other responses

- `400`: `VALIDATION_ERROR` (per-field `meta.issues`) or a rule violation.
- `401`: Invalid or missing API key.
- `403`: The key lacks `update` permission or the "Edit Boards" access, the board isn't API-enabled, or the field can't be changed (locked, standard, mirror or integration-managed).
- `404`: Board (or field) not found.

---

[API](https://skmtc.dev/getaptly/apis/aptly-api.md) - [All operations](https://skmtc.dev/getaptly/apis/aptly-api/llms.txt) - [OpenAPI document](https://skmtc.dev/getaptly/apis/aptly-api/revisions/75c367e0b8e5?raw)