API v1
v1
View as Markdown

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

Sent as JSON. Anything not listed here is ignored.

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.

PUT
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"
}'
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()
$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
{
"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
}
}
}

Keys act as you, with exactly the access you have. Make one per integration so you can revoke it alone.