API v1
v1
View as Markdown

Change an insurance record

PUT /api/v1/vaults/{vault}/possessions/{possession}/insurance-records/{insuranceRecord}

Change what one insurance record says, under the rules that recorded it.

A field left out of the request keeps its value, and a field sent as null is cleared. The other records are not touched.

The change is written to the account log.

Parameters

Sent as JSON. Anything not listed here is ignored.

vault string Required

The vault the possession is kept in, named either by the readable name it reports as slug or by its id. A vault of another account answers 404.

possession uuid Required

The id of the possession. A possession of another vault or of another account answers 404.

insuranceRecord uuid Required

The id of the insurance record. A record of another possession answers 404.

insurer string Optional

Who insures the possession, up to 255 characters.

status string Optional

Where the policy stands: active, pending, expired or cancelled.

insured_value number Optional

The value the possession is insured for. Zero or more, up to 9999999999.99. A figure below zero is refused with “Write an amount of zero or more.”

currency string Optional

The currency of the insured value and the excess.

policy_number string Optional

The number of the policy, up to 255 characters.

coverage string Optional

What the policy covers, up to 255 characters.

excess number Optional

What is paid before the insurer pays. Zero or more, up to 9999999999.99. A figure below zero is refused with “Write an amount of zero or more.”

starts_on string Optional

The day the policy period starts, written as 2026-01-01.

ends_on string Optional

The day the policy period ends or renews, written as 2027-01-01. A day before the start is refused with “The end cannot come before the start.”

is_listed_individually boolean Optional

Whether the policy names this possession rather than the general contents of the home. False when left out on creation.

contact_name string Optional

Who to call at the insurer, up to 255 characters.

contact_email string Optional

The email of that person, a full email address.

contact_phone string Optional

The phone of that person, up to 50 characters.

note string Optional

Conditions, exclusions, what the insurer asked for, up to 5,000 characters.

Returns

The insurance record object as it now reads. A record of another possession or of another account answers 404.

data object

The possession insurance record.

data.type string

Always possession_insurance_record. 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.insurer string

Who insures the possession, as text.

data.attributes.status string

Where the policy stands: active, pending, expired or cancelled. It is the one entered and never follows the dates.

data.attributes.is_current boolean

Whether this is the record the possession is insured under now: the active one with the latest start.

data.attributes.policy_number string

The number of the policy, or null.

data.attributes.coverage string

What the policy covers, or null.

data.attributes.insured_value string

The value the possession is insured for, as a string with two decimals.

data.attributes.excess string

What is paid before the insurer pays, or null when it is not recorded.

data.attributes.currency string

The currency of the insured value and the excess, in lower case. Nothing is ever converted.

data.attributes.starts_on string

The day the policy period starts, written as 2026-01-01, or null.

data.attributes.ends_on string

The day the policy period ends or renews, or null for a policy with no end date.

data.attributes.is_listed_individually boolean

Whether the policy names this possession, rather than covering it under the general contents of the home.

data.attributes.contact_name string

Who to call at the insurer, or null.

data.attributes.contact_email string

The email of that person, or null.

data.attributes.contact_phone string

The phone of that person, or null.

data.attributes.note string

Conditions, exclusions, what the insurer asked for, or null.

data.attributes.created_at timestamp

When the record 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.

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 Insurance section of the possession in the application, which opens for somebody signed in rather than for a key. 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.

PUT
curl https://my.monicahq.com/api/v1/vaults/dunder-mifflin/possessions/9c4e2a71-5b38-4f06-8d1e-2a7f3c6b9e15/insurance-records/5a2e8c14-6b3f-4d71-9e08-c7f1a3b5d2e6 \
-X PUT \
-H "Authorization: Bearer $MONICA_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"status": "expired",
"policy_number": "SAB-2026-0042",
"coverage": "Theft, fire and accidental damage",
"excess": 50,
"starts_on": "2026-01-01",
"ends_on": "2027-01-01",
"is_listed_individually": true,
"contact_name": "Gabe Lewis",
"contact_email": "[email protected]",
"note": "Not covered when Michael lends it to Dwight."
}'
const response = await fetch('https://my.monicahq.com/api/v1/vaults/dunder-mifflin/possessions/9c4e2a71-5b38-4f06-8d1e-2a7f3c6b9e15/insurance-records/5a2e8c14-6b3f-4d71-9e08-c7f1a3b5d2e6', {
method: 'PUT',
headers: { Authorization: `Bearer ${token}`, 'Content-Type': 'application/json' },
body: JSON.stringify({
status: 'expired',
policy_number: 'SAB-2026-0042',
coverage: 'Theft, fire and accidental damage',
excess: 50,
starts_on: '2026-01-01',
ends_on: '2027-01-01',
is_listed_individually: true,
contact_name: 'Gabe Lewis',
contact_email: '[email protected]',
note: 'Not covered when Michael lends it to Dwight.',
}),
})
const data = await response.json()
$response = Http::withToken($token)->put('https://my.monicahq.com/api/v1/vaults/dunder-mifflin/possessions/9c4e2a71-5b38-4f06-8d1e-2a7f3c6b9e15/insurance-records/5a2e8c14-6b3f-4d71-9e08-c7f1a3b5d2e6', [
'status' => 'expired',
'policy_number' => 'SAB-2026-0042',
'coverage' => 'Theft, fire and accidental damage',
'excess' => 50,
'starts_on' => '2026-01-01',
'ends_on' => '2027-01-01',
'is_listed_individually' => true,
'contact_name' => 'Gabe Lewis',
'contact_email' => '[email protected]',
'note' => 'Not covered when Michael lends it to Dwight.',
]);
Response 200
{
"data": {
"type": "possession_insurance_record",
"id": "5a2e8c14-6b3f-4d71-9e08-c7f1a3b5d2e6",
"attributes": {
"insurer": "Sabre Insurance",
"status": "active",
"is_current": true,
"policy_number": "SAB-2026-0042",
"coverage": "Theft, fire and accidental damage",
"insured_value": "500.00",
"excess": "50.00",
"currency": "usd",
"starts_on": "2026-01-01",
"ends_on": "2027-01-01",
"is_listed_individually": true,
"contact_name": "Gabe Lewis",
"contact_email": "[email protected]",
"contact_phone": null,
"note": "Not covered when Michael lends it to Dwight.",
"created_at": 1761436800,
"updated_at": 1761436800
},
"links": {
"self": "https://my.monicahq.com/api/v1/vaults/dunder-mifflin/possessions/9c4e2a71-5b38-4f06-8d1e-2a7f3c6b9e15/insurance-records/5a2e8c14-6b3f-4d71-9e08-c7f1a3b5d2e6",
"web": "https://my.monicahq.com/vaults/dunder-mifflin/possessions/9c4e2a71-5b38-4f06-8d1e-2a7f3c6b9e15/insurance"
}
}
}

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