API v1
v1
View as Markdown

Read the custom fields of a life event type

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

Read what a life event of one nature is asked for: the groups, and the fields in each.

A group is a heading drawn above its fields. The fields nobody grouped are a group too, placed first with its heading not drawn, because a field belongs to a group and to nothing else.

A nature nobody has given fields to answers an empty list rather than 404. That is the state every nature starts in.

Each field carries the key it is known by. Send that key back when you write the layout and the field is kept rather than replaced, which is what stops the values already recorded against it being orphaned.

This endpoint also answers QUERY, with the same parameters sent in the request body. How QUERY works.

Path 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.

Returns

The groups of the layout, each with its fields. A nature belonging to somebody else answers 404.

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.

GET
curl https://my.monicahq.com/api/v1/life-event-types/8b2e5c70-1a94-4f38-b6d2-0e7c94a35f18/fields \
-H "Authorization: Bearer $MONICA_TOKEN"
const response = await fetch('https://my.monicahq.com/api/v1/life-event-types/8b2e5c70-1a94-4f38-b6d2-0e7c94a35f18/fields', {
headers: { Authorization: `Bearer ${token}` },
})
const data = await response.json()
$response = Http::withToken($token)->get('https://my.monicahq.com/api/v1/life-event-types/8b2e5c70-1a94-4f38-b6d2-0e7c94a35f18/fields');
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.