Write the custom fields of a life event type
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.
The id of the nature. A path that is not a uuid answers 404 without a query being run.
The groups of the layout, in the order you want them drawn.
The id you read the group with, to keep it rather than replace it. Leave it out for a new group.
What the group is headed. Up to 255 characters, and a group without one is refused.
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.
The fields that belong to no group. They are asked for first, under no heading.
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.
What the field is called on the form. Up to 255 characters.
What kind of thing the field holds, from the list the read answers with. Anything else is refused.
Whether the life event refuses to save without it.
A sentence shown under the field. Up to 255 characters.
Settings belonging to that kind of field alone, such as max_length on a text field or decimals on a number.
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.
The groups the layout is made of, in the order they are shown. An empty list when the nature asks for nothing.
One group.
Always structure_version_section. It names the kind of record, so a caller holding several kinds can tell them apart.
The id of the group, as a string even when it reads as a number.
Everything the group holds.
Where the group sits in the layout, counting from 1. The fields nobody grouped are a group too, and they come first.
What the group is headed. The fields nobody grouped answer with a heading that is not drawn.
The heading chosen for this group alone, or null when the underlying name is used.
The id of the reusable block behind the group. It belongs to the engine that stores the layout and a caller rarely needs it.
What that block is called in the library it lives in.
Which frozen version of the block is placed here. This is what stops a change reaching a life event already recorded.
One of draft, published or retired, for the block rather than for the nature.
Whether the group starts folded shut when somebody opens the life event.
What a life event of this nature is asked for inside this group, in the order it is shown.
What the group collects, in the order it is shown.
One field.
Always field. It names the kind of record, so a caller holding several kinds can tell them apart.
The id of the field, as a string even when it reads as a number.
Everything the field holds.
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.
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.
What the field is called on the form.
A sentence shown under the field, or null when there is none.
What the empty box shows as an example, or null.
Where the field sits in its group, counting from 1.
Whether the life event refuses to save without it.
Whether the value is hidden until somebody asks to see it.
Whether the value is repeated at the top of the life event.
Whether two life events of this nature may hold the same value.
Whether two life events sharing this value are likely the same life event.
Whether the field holds several values rather than one. It follows from the type.
The fewest repetitions allowed, or null when there is no floor.
The most repetitions allowed, or null when there is no ceiling.
How several values are ordered against each other, or null when the field holds one.
Settings belonging to this kind of field alone, or null. What it holds depends on the type.
Extra rules a value has to satisfy, or null.
What the field starts filled with, or null.
What a relation field points at, or null when the field is not a relation.
When the field was added, as a count of seconds since 1970.
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.
Keys act as you, with exactly the access you have. Make one per integration so you can revoke it alone.