API v1
v1
View as Markdown

Write the custom fields of a life event type

PUT /api/v1/life-event-types/{lifeEventType}/fields

Send the layout a life event of this nature should ask for.

This takes the finished layout rather than one change at a time, because that is the one gesture the product has for it. The layout is two lists, groups and fields, each sent whole. A list left out of the body keeps what is stored. A list sent replaces what is stored, so anything left out of it is gone.

A field is matched to the one already there by its key. Send a field back with its key to keep it, leave the key out to add a field, and leave a field out altogether to take it away. Changing what kind of field it is, or what a relation points at, writes the field again in place under the same key.

A group is matched by the placement_id you read it with. Leave that out to add a group, and leave a group out to take it away, which files its fields under no group rather than deleting them.

Every save publishes a new frozen version of the layout beside the old one. A life event already recorded names the version it was written on and never follows, so it keeps the fields and the values it was written with. This is the rule that makes the layout safe to change.

A kind of field the product does not offer, and a group without a name, are both refused, and the layout already there is left exactly as it was.

Parameters

Sent as JSON. Anything not listed here is ignored.

lifeEventType uuid Required

The id of the nature. A path that is not a uuid answers 404 without a query being run.

groups array Optional

The groups of the layout, in the order you want them drawn.

groups[].placement_id integer Optional

The id you read the group with, to keep it rather than replace it. Leave it out for a new group.

groups[].name string Required

What the group is headed. Up to 255 characters, and a group without one is refused.

groups[].fields array Optional

The fields in that group, in the order you want them asked for. Each is shaped like an entry of the top level fields list.

fields array Optional

The fields that belong to no group. They are asked for first, under no heading.

fields[].key string Optional

The key you read the field with, to keep it rather than replace it. Leave it out for a new field. Up to 64 characters.

fields[].label string Required

What the field is called on the form. Up to 255 characters.

fields[].type string Required

What kind of thing the field holds, from the list the read answers with. Anything else is refused.

fields[].is_required boolean Optional

Whether the life event refuses to save without it.

fields[].help_text string Optional

A sentence shown under the field. Up to 255 characters.

fields[].settings object Optional

Settings belonging to that kind of field alone, such as max_length on a text field or decimals on a number.

fields[].choices array Optional

What a select, multiselect or radio field offers, in order. Blank entries are dropped.

Returns

The layout as it now stands, read back exactly as the read answers it.

data array

The groups the layout is made of, in the order they are shown. An empty list when the nature asks for nothing.

data[] object

One group.

data[].type string

Always structure_version_section. It names the kind of record, so a caller holding several kinds can tell them apart.

data[].id string

The id of the group, as a string even when it reads as a number.

data[].attributes object

Everything the group holds.

data[].attributes.position integer

Where the group sits in the layout, counting from 1. The fields nobody grouped are a group too, and they come first.

data[].attributes.title string

What the group is headed. The fields nobody grouped answer with a heading that is not drawn.

data[].attributes.title_override string

The heading chosen for this group alone, or null when the underlying name is used.

data[].attributes.section_id string

The id of the reusable block behind the group. It belongs to the engine that stores the layout and a caller rarely needs it.

data[].attributes.section_name string

What that block is called in the library it lives in.

data[].attributes.section_version_number integer

Which frozen version of the block is placed here. This is what stops a change reaching a life event already recorded.

data[].attributes.section_version_status string

One of draft, published or retired, for the block rather than for the nature.

data[].attributes.is_collapsed_by_default boolean

Whether the group starts folded shut when somebody opens the life event.

data[].attributes.fields array

What a life event of this nature is asked for inside this group, in the order it is shown.

data[].attributes.fields array

What the group collects, in the order it is shown.

data[].attributes.fields[] object

One field.

data[].attributes.fields[].type string

Always field. It names the kind of record, so a caller holding several kinds can tell them apart.

data[].attributes.fields[].id string

The id of the field, as a string even when it reads as a number.

data[].attributes.fields[].attributes object

Everything the field holds.

data[].attributes.fields[].attributes.key string

How the field is named in an import or an export, settled when the field is added. Send it back to keep a field rather than replace it.

data[].attributes.fields[].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.fields[].attributes.label string

What the field is called on the form.

data[].attributes.fields[].attributes.help_text string

A sentence shown under the field, or null when there is none.

data[].attributes.fields[].attributes.placeholder string

What the empty box shows as an example, or null.

data[].attributes.fields[].attributes.position integer

Where the field sits in its group, counting from 1.

data[].attributes.fields[].attributes.is_required boolean

Whether the life event refuses to save without it.

data[].attributes.fields[].attributes.is_sensitive boolean

Whether the value is hidden until somebody asks to see it.

data[].attributes.fields[].attributes.is_highlighted boolean

Whether the value is repeated at the top of the life event.

data[].attributes.fields[].attributes.is_unique boolean

Whether two life events of this nature may hold the same value.

data[].attributes.fields[].attributes.is_identifying boolean

Whether two life events sharing this value are likely the same life event.

data[].attributes.fields[].attributes.is_repeatable boolean

Whether the field holds several values rather than one. It follows from the type.

data[].attributes.fields[].attributes.repeat_min integer

The fewest repetitions allowed, or null when there is no floor.

data[].attributes.fields[].attributes.repeat_max integer

The most repetitions allowed, or null when there is no ceiling.

data[].attributes.fields[].attributes.repetition_order string

How several values are ordered against each other, or null when the field holds one.

data[].attributes.fields[].attributes.options object

Settings belonging to this kind of field alone, or null. What it holds depends on the type.

data[].attributes.fields[].attributes.validation object

Extra rules a value has to satisfy, or null.

data[].attributes.fields[].attributes.default_value object

What the field starts filled with, or null.

data[].attributes.fields[].attributes.relation_target string

What a relation field points at, or null when the field is not a relation.

data[].attributes.fields[].attributes.created_at timestamp

When the field was added, as a count of seconds since 1970.

data[].attributes.fields[].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/life-event-types/8b2e5c70-1a94-4f38-b6d2-0e7c94a35f18/fields \
-X PUT \
-H "Authorization: Bearer $MONICA_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"groups[].placement_id": "41",
"groups[].name": "Where",
"fields[].key": "venue",
"fields[].label": "Venue",
"fields[].type": "text",
"fields[].is_required": "true",
"fields[].help_text": "The place it happened."
}'
const response = await fetch('https://my.monicahq.com/api/v1/life-event-types/8b2e5c70-1a94-4f38-b6d2-0e7c94a35f18/fields', {
method: 'PUT',
headers: { Authorization: `Bearer ${token}`, 'Content-Type': 'application/json' },
body: JSON.stringify({
groups[].placement_id: '41',
groups[].name: 'Where',
fields[].key: 'venue',
fields[].label: 'Venue',
fields[].type: 'text',
fields[].is_required: 'true',
fields[].help_text: 'The place it happened.',
}),
})
const data = await response.json()
$response = Http::withToken($token)->put('https://my.monicahq.com/api/v1/life-event-types/8b2e5c70-1a94-4f38-b6d2-0e7c94a35f18/fields', [
'groups[].placement_id' => '41',
'groups[].name' => 'Where',
'fields[].key' => 'venue',
'fields[].label' => 'Venue',
'fields[].type' => 'text',
'fields[].is_required' => 'true',
'fields[].help_text' => 'The place it happened.',
]);
Response 200
{
"data": [
{
"type": "structure_version_section",
"id": "41",
"attributes": {
"position": 1,
"title": "Where",
"title_override": "Where",
"section_id": "ec0a7b19-5d38-4c72-9a61-2f80d4b63e57",
"section_name": "Where",
"section_version_number": 1,
"section_version_status": "published",
"is_collapsed_by_default": false,
"fields": [
{
"type": "field",
"id": "88",
"attributes": {
"key": "venue",
"type": "text",
"label": "Venue",
"help_text": null,
"placeholder": null,
"position": 1,
"is_required": true,
"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": 1756339200,
"updated_at": 1756339200
}
}
]
}
}
]
}

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