# Configure a field

`PUT /api/v1/templates/{template}/versions/{version}/sections/{section}/fields/{field}`

Change what a field is called and how it behaves.

As with adding one, changing a field of a section that has been published opens a draft of the section and changes it there, leaving the published section and every other template placing it alone.

The type, whether the field repeats, and what a relation points at are settled when the field is added and are not sent here. Everything else may be sent: a setting left out keeps its value, and a setting sent as null goes back to its default. The label and the five switches cannot be null.

## Parameters

- `template` (uuid, required): The id of the template. A path that is not a uuid answers 404 without a query being run, so neither the slug nor a sequential number reaches anything here.
- `version` (integer, required): The number of the version within its template, counting from 1, which is the number shown in the version history and the number a change note refers to. It is not a row id, so version 1 of one template and version 1 of another are different things reached through different templates.
- `section` (integer, required): The id of the placement, which is not the id of the section. It is the id a placement comes back with when a version is read.
- `field` (integer, required): The id of the field. It changes the first time a published section is changed, because the change opens a draft of the section and the fields are copied into it. The key does not change, and the answer carries the new id.
- `label` (string, optional): What the field is called on the form. It cannot be null.
- `help_text` (string, optional): A sentence shown under the field, or null to remove it.
- `placeholder` (string, optional): What the empty box shows as an example, or null to remove it.
- `is_required` (boolean, optional): Whether the record refuses to save without it.
- `is_sensitive` (boolean, optional): Whether the value is hidden until somebody asks to see it.
- `is_highlighted` (boolean, optional): Whether the value is repeated at the top of the record.
- `is_unique` (boolean, optional): Whether two records may hold the same value.
- `is_identifying` (boolean, optional): Whether two records sharing this value are likely the same record, so the pair is proposed as a duplicate.
- `value_list_id` (integer, optional): The list a field offering choices takes them from, as the id the value lists endpoint gives. A list of another account is refused. Null removes it.
- `default_value` (object, optional): What the field starts filled with.
- `options` (object, optional): Settings belonging to this kind of field alone. A file or image field takes accepted_mime_types, a list of at most 20 mime types such as image/png, and an image field takes image types only. Anything else answers 422 on options.
- `validation` (object, optional): Extra rules a value has to satisfy.
- `repeat_min` (integer, optional): The fewest repetitions allowed.
- `repeat_max` (integer, optional): The most repetitions allowed.
- `repetition_order` (string, optional): How several values are ordered: newest_last or newest_first.

## Returns

The field as it now stands, carrying the id it holds in the section version that took the change.

- `data` (object): The field.
- `data.type` (string): Always field. It names the kind of record, so a caller holding several kinds can tell them apart without looking at where they came from.
- `data.id` (string): The id of this record, as a string even when it reads as a number. It is what every endpoint naming this record takes.
- `data.attributes` (object): Everything the record holds.
- `data.attributes.key` (string): How the field is named in an import or an export, settled when the field is added.
- `data.attributes.type` (string): What kind of thing the field holds: one of text, textarea, number, boolean, url, email, phone, select, multiselect, radio, date, recurring_date, duration (a whole number of minutes), relation, file, image, avatar, address, repeater, divider, heading or help. The last three carry no value and are there to lay the form out.
- `data.attributes.label` (string): What the field is called on the form.
- `data.attributes.help_text` (string): A sentence shown under the field, or null when there is none.
- `data.attributes.placeholder` (string): What the empty box shows as an example, or null.
- `data.attributes.position` (integer): Where the field sits in its section, counting from 1.
- `data.attributes.is_required` (boolean): Whether the record refuses to save without it.
- `data.attributes.is_sensitive` (boolean): Whether the value is hidden until somebody asks to see it.
- `data.attributes.is_highlighted` (boolean): Whether the value is repeated at the top of the record.
- `data.attributes.is_unique` (boolean): Whether two records of this template may hold the same value.
- `data.attributes.is_identifying` (boolean): Whether two records sharing this value are likely the same record, so the pair is proposed as a duplicate. Not the same as unique: a household can legitimately share one telephone number, and proposing a pair is right where refusing the value would be wrong.
- `data.attributes.is_repeatable` (boolean): Whether the field holds several values rather than one. It follows from the type and is settled when the field is added.
- `data.attributes.repeat_min` (integer): The fewest repetitions allowed, or null when there is no floor.
- `data.attributes.repeat_max` (integer): The most repetitions allowed, or null when there is no ceiling.
- `data.attributes.repetition_order` (string): How several values are ordered against each other, or null when the field holds one.
- `data.attributes.options` (object): Settings belonging to this kind of field alone, or null. What it holds depends on the type.
- `data.attributes.validation` (object): Extra rules a value has to satisfy, or null.
- `data.attributes.default_value` (object): What the field starts filled with, or null.
- `data.attributes.relation_target` (string): What a relation field points at, or null when the field is not a relation. It is settled when the field is added.
- `data.attributes.created_at` (timestamp): When the field was added, as a count of seconds since 1970.
- `data.attributes.updated_at` (timestamp): When it last changed, as a count of seconds, or null.

## Rate limit

Sixty requests per minute, per user, shared by every key and device. Every answer carries the budget left in `X-RateLimit-Remaining`.

## Request

```sh
curl https://my.monicahq.com/api/v1/templates/7b1c4e92-3d58-4f07-9a26-8c5b0e14d3af/versions/4/sections/904/fields/5521 \
  -X PUT \
  -H "Authorization: Bearer $MONICA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
      "label": "Street name",
      "help_text": "Including the number.",
      "placeholder": "221B Baker Street"
  }'
```

```javascript
const response = await fetch('https://my.monicahq.com/api/v1/templates/7b1c4e92-3d58-4f07-9a26-8c5b0e14d3af/versions/4/sections/904/fields/5521', {
  method: 'PUT',
  headers: { Authorization: `Bearer ${token}`, 'Content-Type': 'application/json' },
  body: JSON.stringify({
    label: 'Street name',
    help_text: 'Including the number.',
    placeholder: '221B Baker Street',
  }),
})
const data = await response.json()
```

```php
$response = Http::withToken($token)->put('https://my.monicahq.com/api/v1/templates/7b1c4e92-3d58-4f07-9a26-8c5b0e14d3af/versions/4/sections/904/fields/5521', [
    'label' => 'Street name',
    'help_text' => 'Including the number.',
    'placeholder' => '221B Baker Street',
]);
```

## Response

`200`

```json
{
    "data": {
        "type": "field",
        "id": "5521",
        "attributes": {
            "key": "nickname",
            "type": "text",
            "label": "Nickname",
            "help_text": null,
            "placeholder": null,
            "position": 1,
            "is_required": false,
            "is_sensitive": false,
            "is_highlighted": false,
            "is_unique": false,
            "is_identifying": false,
            "is_repeatable": false,
            "repeat_min": null,
            "repeat_max": null,
            "repetition_order": null,
            "options": null,
            "validation": null,
            "default_value": null,
            "relation_target": null,
            "created_at": 1756335600,
            "updated_at": 1756335600
        }
    }
}
```
