# 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

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

## Request

```sh
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": "gabe@sabre.example.com",
      "note": "Not covered when Michael lends it to Dwight."
  }'
```

```javascript
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: 'gabe@sabre.example.com',
    note: 'Not covered when Michael lends it to Dwight.',
  }),
})
const data = await response.json()
```

```php
$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' => 'gabe@sabre.example.com',
    'note' => 'Not covered when Michael lends it to Dwight.',
]);
```

## Response

`200`

```json
{
    "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": "gabe@sabre.example.com",
            "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"
        }
    }
}
```
