# Add a field

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

Add a piece of data to a section, through the template that places it.

Fields belong to the section version rather than to the section, which is what makes freezing reach all the way down. So if the section placed here has been published, adding a field opens a draft of the section first and adds it there. The published section is untouched, and every other template placing it goes on exactly as before. The answer names the section version that took the change.

The type is settled here and cannot be changed afterwards, and so is what a relation points at and whether the field repeats, because records get written against those promises. Everything else can be changed later.

A field offering choices has to say which value list they come from, and a relation field has to say what it points at. Three types carry no value at all and are there to lay the form out: divider, heading and help.

## 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.
- `type` (string, required): 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.
- `label` (string, required): What the field is called on the form. Up to 255 characters.
- `key` (string, optional): How the field is named in an import or an export. Derived from the label when absent, and settled once.
- `value_list_id` (integer, optional): The list a field offering choices takes them from, as the id the value lists endpoint gives. Required for select, multiselect and radio.
- `relation_target` (string, optional): What a relation field points at: contact or entity. Required for a relation field.
- `relation_entity_type_id` (uuid, optional): Which kind of entity a relation field points at. Required when relation_target is entity.
- `parent_id` (integer, optional): The repeater this field sits inside. Only a repeater can hold other fields, and a repeater cannot sit inside another.

## Returns

The field that was added, placed last in its section, with every setting at its default.

- `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 \
  -X POST \
  -H "Authorization: Bearer $MONICA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
      "type": "text",
      "label": "Nickname"
  }'
```

```javascript
const response = await fetch('https://my.monicahq.com/api/v1/templates/7b1c4e92-3d58-4f07-9a26-8c5b0e14d3af/versions/4/sections/904/fields', {
  method: 'POST',
  headers: { Authorization: `Bearer ${token}`, 'Content-Type': 'application/json' },
  body: JSON.stringify({
    type: 'text',
    label: 'Nickname',
  }),
})
const data = await response.json()
```

```php
$response = Http::withToken($token)->post('https://my.monicahq.com/api/v1/templates/7b1c4e92-3d58-4f07-9a26-8c5b0e14d3af/versions/4/sections/904/fields', [
    'type' => 'text',
    'label' => 'Nickname',
]);
```

## Response

`201`

```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
        }
    }
}
```
