---
title: "Add a mirror field"
method: POST
path: "/api/board/{boardId}/configuration/mirror-fields"
tags: ["Board"]
---

# Add a mirror field

`POST /api/board/{boardId}/configuration/mirror-fields`

## Request

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

Adds a field to the board that mirrors a field of another board. The new field takes the
target field's type (and, for select types, a copy of its option list), is named
`Mirror <target field name>` unless you supply `name`, and is read-only unless you set
`readOnly: false`.

This only adds the field - the same as the Aptly app. A card shows a mirrored value once
it is linked to a card on the target board (for example through a related-cards field) and
is next saved; existing cards are not backfilled when the field is added.

Requires `update` permission and the key's "Edit Boards" access (off by default). A key's
board allowlist applies to **both** boards: the target board must be one the key can access
and must be API-enabled. The target field must be one of `string`, `text`, `rich-text`,
`address`, `email`, `url`, `datetime-local`, `date`, `number`, `percent`, `stageselect`,
`singleselect`, `multiselect`, `tags`, `boolean`, `person`, `persons`, `relatedAptlets`,
`files`, `file`, `money`, `user` or `lockAlias`, and can't itself be a mirror field. Mirroring
the same target field twice on one board returns `409`.

## Path parameters

- `boardId` string, required

## Request body

- object
  - `targetBoardUuid` string, required: The uuid of the board to mirror a field from.
  - `targetFieldUuid` string, required: The uuid of the field on that board to mirror.
  - `name` string: Display name for the new field. Defaults to `Mirror <target field name>`.
  - `readOnly` boolean: Whether users may edit the mirrored value on this board. Defaults to `true`.

## Response `201`

The created 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 the target field's type can't be mirrored, or the target field is itself a mirror field.
- `401`: Invalid or missing API key.
- `403`: The key lacks `update` permission or the "Edit Boards" access, either board is outside the key's board allowlist, or the board or target board isn't API-enabled.
- `404`: The board, the target board or the target field was not found.
- `409`: The board already mirrors that target field. `meta.fieldUuid` is the existing mirror field.

---

[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)