API v1
v1
View as Markdown

Record a life event

POST /api/v1/vaults/{vault}/life-events

Write down something that happened. It goes on the timeline of everybody who was there, exactly as if it had been written on the page of the first of them.

The ids of the custom fields come from GET /life-event-types/{lifeEventType}/fields for a new life event, and from the fields of the life event itself once it exists. A field key cannot stand for an id, since a key is only unique inside its group.

A refusal names what it is about: life_event_type, happened_on, participants, a field under fields, or fields as a whole when a required field is left empty.

Parameters

Sent as JSON. Anything not listed here is ignored.

vault string Required

The vault the life events live in, named either by the readable name it reports as slug or by its id.

life_event_type uuid Required

The id of its type, as the life event types endpoints give it. A type switched off cannot be chosen for a new life event and answers 422.

happened_on string Required

The day it happened, written as a year, a month and a day.

participants array Required

The contacts who were there, in order, each named by its slug or its id. The first is the person the life event is recorded for. A contact of another vault answers 404.

title string Optional

A title, up to 255 characters. Without one, the life event is called by the name of its type.

narrative string Optional

What happened, up to 65,535 characters.

location string Optional

Where it happened, up to 255 characters.

duration_in_minutes integer Optional

How long it lasted, from 1 to 100,000 minutes.

fields object Optional

The values of the custom fields its type asks for, keyed by field id. A text field takes a string, a select field the id of its choice, a multiple select field a list of them, a date a year, a month and a day. A repeating group takes a list of repetitions, each holding its id when it already exists and its values keyed by the ids of the fields inside the group. A file field cannot be written here and answers 422.

Returns

The life event object that was recorded.

data object

The life event.

data.type string

Always life_event. 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.name string

What the life event is called: its title, or the name of its type when it has none.

data.attributes.title string

The title written for it, or null.

data.attributes.life_event_type object

Its type. A type deleted since still names the life events recorded as it.

data.attributes.life_event_type.id uuid

The id of the type, as the life event types endpoints give it.

data.attributes.life_event_type.name string

What the type is called.

data.attributes.group object

The group it was recorded on, as an object holding its id and its name, or null when it was not recorded on a group or the group has been deleted.

data.attributes.happened_on string

The day it happened, written as a year, a month and a day.

data.attributes.duration_in_minutes integer

How long it lasted, in minutes, or null.

data.attributes.narrative string

What was written about it, or null.

data.attributes.location string

Where it happened, or null.

data.attributes.participants array

The contacts who were there, in order. The first is the person the life event is recorded for.

data.attributes.participants[] object

One contact who was there.

data.attributes.participants[].id uuid

The id of the contact.

data.attributes.participants[].name string

The name the contact is shown under.

data.attributes.participants[].position integer

Where the contact stands in the list, counting from 0.

data.attributes.fields array

The values of the custom fields its type asks for. A field left empty is not listed.

data.attributes.fields[] object

One value.

data.attributes.fields[].field_id string

The id of the field, which is the key a value is written under when the life event is updated.

data.attributes.fields[].key string

How the field is named in an import or an export. It is unique inside its group only.

data.attributes.fields[].label string

What the field is called on the life event.

data.attributes.fields[].type string

The kind of field: text, date, select, address and so on.

data.attributes.fields[].row integer

For a field inside a repeating group, the id of the repetition it belongs to, which is the id an update keeps that repetition by. Null otherwise.

data.attributes.fields[].value string

The value, written as the contact page shows it. A file field gives the name of the file. Null when hidden.

data.attributes.fields[].is_hidden boolean

Whether the value was held back because the field is sensitive and the key does not hold the sensitive-fields scope.

data.attributes.created_from string

Where it was written from: contact, dashboard, group, api, mcp, day, import or module.

data.attributes.deleted_at timestamp

When it was deleted, as a count of seconds since 1970, or null.

data.attributes.created_at timestamp

When it was written down, as a count of seconds since 1970.

data.attributes.updated_at timestamp

When it last changed, as a count of seconds since 1970.

data.links object

Where to find this record.

data.links.self string

The absolute address this record is read from.

data.links.web string

The page of the contact the life event is recorded for, whose timeline shows it, in the application. It is the link to give a person.

Rate limit

Sixty requests per minute, per user, shared by every key and device. Every answer carries the budget left in X-RateLimit-Remaining.

POST
curl https://my.monicahq.com/api/v1/vaults/dunder-mifflin/life-events \
-X POST \
-H "Authorization: Bearer $MONICA_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"life_event_type": "b2f4d6a8-1c3e-4a5b-8d7f-0e9c2b4a6d81",
"happened_on": "2026-10-09",
"participants": [
"pam-beesly",
"jim-halpert"
],
"title": "Lunch at Cugino\u2019s",
"narrative": "Michael insisted on paying, then asked for the receipt.",
"location": "Scranton",
"duration_in_minutes": 60,
"fields": {
"412": "Chicken parm"
}
}'
const response = await fetch('https://my.monicahq.com/api/v1/vaults/dunder-mifflin/life-events', {
method: 'POST',
headers: { Authorization: `Bearer ${token}`, 'Content-Type': 'application/json' },
body: JSON.stringify({
life_event_type: 'b2f4d6a8-1c3e-4a5b-8d7f-0e9c2b4a6d81',
happened_on: '2026-10-09',
participants: ["pam-beesly","jim-halpert"],
title: 'Lunch at Cugino’s',
narrative: 'Michael insisted on paying, then asked for the receipt.',
location: 'Scranton',
duration_in_minutes: 60,
fields: {"412":"Chicken parm"},
}),
})
const data = await response.json()
$response = Http::withToken($token)->post('https://my.monicahq.com/api/v1/vaults/dunder-mifflin/life-events', [
'life_event_type' => 'b2f4d6a8-1c3e-4a5b-8d7f-0e9c2b4a6d81',
'happened_on' => '2026-10-09',
'participants' => ['pam-beesly', 'jim-halpert'],
'title' => 'Lunch at Cugino’s',
'narrative' => 'Michael insisted on paying, then asked for the receipt.',
'location' => 'Scranton',
'duration_in_minutes' => 60,
'fields' => ['412' => 'Chicken parm'],
]);
Response 201
{
"data": {
"type": "life_event",
"id": "7c1e5a92-4b3d-4f80-a6e2-93d0b1c4f857",
"attributes": {
"name": "Lunch at Cugino’s",
"title": "Lunch at Cugino’s",
"life_event_type": {
"id": "b2f4d6a8-1c3e-4a5b-8d7f-0e9c2b4a6d81",
"name": "Meal"
},
"group": null,
"happened_on": "2026-10-09",
"duration_in_minutes": 60,
"narrative": "Michael insisted on paying, then asked for the receipt.",
"location": "Scranton",
"participants": [
{
"id": "0d3f9b2e-6a41-4c7d-9e58-2b1a7c4e6f90",
"name": "Pam Beesly",
"position": 0
},
{
"id": "e5a8c1f3-7b29-4d06-8a4e-5c2d9f1b3a67",
"name": "Jim Halpert",
"position": 1
}
],
"fields": [
{
"field_id": "412",
"key": "dish",
"label": "Dish",
"type": "text",
"row": null,
"value": "Chicken parm",
"is_hidden": false
}
],
"created_from": "api",
"deleted_at": null,
"created_at": 1791547200,
"updated_at": 1791547200
},
"links": {
"self": "https://my.monicahq.com/api/v1/vaults/dunder-mifflin/life-events/7c1e5a92-4b3d-4f80-a6e2-93d0b1c4f857",
"web": "https://my.monicahq.com/vaults/dunder-mifflin/contacts/pam-beesly"
}
}
}

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