---
title: "Replace customer field settings"
method: PUT
path: "/v1/customer-field-settings"
tags: ["Settings"]
---

# Replace customer field settings

`PUT /v1/customer-field-settings`

## Request

- Base URL: `https://api.officina.it`
- URL: `https://api.officina.it/v1/customer-field-settings`
- Auth: HTTP bearer

Creates, updates, reorders and deletes customer custom field
definitions, updates the optional-field visibility toggles and the
birthday agenda switch in one call.

`custom_fields` is the complete list: an entry with `id` updates
that field (values stored on customers are kept), an entry without
`id` creates one (the id is returned), an existing field left out
is deleted. Array position is the display order. When
`custom_fields` is absent the definitions are left unchanged.

Omitted attributes are kept, never reset: an absent
`field_visibility` key, an absent `birthday_calendar_event`, and an
absent `visible` or `reminder_days_before` on an existing field all
keep their stored value. New fields default to `visible: true` and
no reminder.

Only the birthday and the internal notes can be hidden; fiscal,
price-list and e-invoicing fields always show.

A hidden field creates no agenda events whatever its switch says;
the switch stays stored and applies again once the field is shown.
With `field_visibility.birthday` set to `false` no birthday events
are created even when `birthday_calendar_event` is `true`. Events
already in the agenda are never touched here.

Returns 422 `parameter_invalid` (with `param` pointing at the entry)
for an unknown or repeated `id`, a repeated name
(case-insensitive), a name outside 2–30 characters, an unknown
`type` or more than 10 fields.

## Request body

- object
  - `field_visibility` object: Quali campi facoltativi restano visibili nella scheda cliente. Le chiavi assenti mantengono il valore attuale.
    - `birthday` boolean
    - `comments` boolean: Note interne.
  - `birthday_calendar_event` boolean: Crea un evento in agenda il giorno del compleanno di ogni cliente con data di nascita. Conta solo se `field_visibility.birthday` è `true`. Assente: invariato.
  - `custom_fields` object[]: L'insieme completo dei campi personalizzati, nell'ordine di visualizzazione. Quelli non elencati vengono rimossi; se il campo è assente la configurazione non cambia.
    - `id` string: Id di un campo esistente (da GET) per modificarlo. Omettere per crearne uno nuovo: l'id viene generato e restituito. Un id sconosciuto o ripetuto è un 422.
    - `name` string, required: Unico fra i campi (senza distinzione tra maiuscole e minuscole).
    - `type` 'string' | 'integer' | 'datetime', required
    - `visible` boolean: Mostra il campo nei moduli e nei dettagli cliente (`custom_field_values`). Assente: invariato per un campo esistente, `true` per uno nuovo.
    - `reminder_days_before` integer, nullable: Genera un evento in agenda per la data di questo campo. `null` nessun evento, `0` il giorno stesso della scadenza. Solo per i campi `datetime`: sugli altri tipi viene ignorato. Assente: invariato per un campo esistente, nessun evento per uno nuovo. Oggi l'anticipo non e' configurabile: un valore diverso da zero viene normalizzato a `0`.
    - `order` integer: Ignorato: l'ordine è la posizione nell'array. Accettato così che il corpo di una GET possa essere rispedito.

## Response `200`

success

## Other responses

- `400`: Request body is unparseable or X-API-Version is missing.
- `401`: Missing, malformed, expired, or wrong-audience bearer token.
- `402`: The company has no active subscription, or its plan does not include API access. API access is included in the Business and Illimitato plans.
- `403`: The authenticated user lacks the required permission.
- `422`: A request field is missing or invalid (fast-fail).
- `500`: Unhandled server error. Detail is logged, not exposed.

---

[API](https://skmtc.dev/officina/apis/officina-it-api.md) · [All operations](https://skmtc.dev/officina/apis/officina-it-api/llms.txt) · [OpenAPI document](https://skmtc.dev/officina/apis/officina-it-api/revisions/7da3fccfe551?raw)