# Record a valuation

`POST /api/v1/vaults/{vault}/possessions/{possession}/valuations`

Record what a possession is worth on a date.

The type, the date, the amount and its currency are required. There is no endpoint to change a valuation: to correct one, record a new valuation.

Documents are attached afterwards, one at a time, with the endpoint below. 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.
- `type` (string, required): Where the figure comes from: own_estimate, appraisal, insurance_declaration, auction_result, comparable_listing or offer_received.
- `valued_on` (string, required): The day the estimate applies to, written as 2026-03-14.
- `amount` (number, required): What the possession is worth. Zero or more, up to 9999999999.99. A figure below zero is refused with “Write an amount of zero or more.”
- `currency` (string, required): The currency of the amount: usd, eur, gbp, cad, aud, chf, jpy, brl, inr or cny.
- `confidence` (string, optional, defaults to unknown): How sure somebody is of the figure: unknown, certain, probable or uncertain.
- `valuer` (string, optional): Who estimated it, up to 255 characters. Markup is stripped.
- `method` (string, optional): How it was estimated, up to 255 characters.
- `reference_number` (string, optional): The reference of the appraisal, the listing or the offer, up to 255 characters.
- `source_url` (string, optional): A full web address where the valuation can be checked, up to 255 characters.
- `note` (string, optional): Anything worth remembering about the valuation, up to 5,000 characters.

## Returns

The valuation object that was recorded.

- `data` (object): The possession valuation.
- `data.type` (string): Always possession_valuation. 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.type` (string): Where the figure comes from: own_estimate, appraisal, insurance_declaration, auction_result, comparable_listing or offer_received.
- `data.attributes.valued_on` (string): The day the estimate applies to, written as 2026-03-14.
- `data.attributes.confidence` (string): How sure somebody is of the figure: unknown, certain, probable or uncertain.
- `data.attributes.amount` (string): What the possession is worth, as a string with two decimals.
- `data.attributes.currency` (string): The currency of the amount, in lower case. Nothing is ever converted.
- `data.attributes.is_current` (boolean): Whether this valuation gives the current value of the possession: the latest by date, the latest recorded on a tie.
- `data.attributes.valuer` (string): Who estimated it, as text, or null.
- `data.attributes.method` (string): How it was estimated, or null.
- `data.attributes.reference_number` (string): The reference of the appraisal, the listing or the offer, or null.
- `data.attributes.source_url` (string): Where the valuation can be checked, or null.
- `data.attributes.note` (string): Anything worth remembering about the valuation, or null.
- `data.attributes.documents` (array): The certificates, listings and offers attached to it, oldest first.
- `data.attributes.created_at` (timestamp): When the valuation was recorded, as a count of seconds since 1970. A valuation is never changed, so it has no time of change.
- `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 Valuations 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/valuations \
  -X POST \
  -H "Authorization: Bearer $MONICA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
      "type": "appraisal",
      "valued_on": "2026-03-14",
      "amount": 650,
      "currency": "usd",
      "confidence": "certain",
      "valuer": "Scranton Jewelers",
      "method": "Inspection and comparable sales",
      "reference_number": "APP-2026-0212",
      "source_url": "https://scrantonjewelers.example.com/appraisals/0212",
      "note": "Michael insists the gold paint adds to its worth."
  }'
```

```javascript
const response = await fetch('https://my.monicahq.com/api/v1/vaults/dunder-mifflin/possessions/9c4e2a71-5b38-4f06-8d1e-2a7f3c6b9e15/valuations', {
  method: 'POST',
  headers: { Authorization: `Bearer ${token}`, 'Content-Type': 'application/json' },
  body: JSON.stringify({
    type: 'appraisal',
    valued_on: '2026-03-14',
    amount: 650,
    currency: 'usd',
    confidence: 'certain',
    valuer: 'Scranton Jewelers',
    method: 'Inspection and comparable sales',
    reference_number: 'APP-2026-0212',
    source_url: 'https://scrantonjewelers.example.com/appraisals/0212',
    note: 'Michael insists the gold paint adds to its worth.',
  }),
})
const data = await response.json()
```

```php
$response = Http::withToken($token)->post('https://my.monicahq.com/api/v1/vaults/dunder-mifflin/possessions/9c4e2a71-5b38-4f06-8d1e-2a7f3c6b9e15/valuations', [
    'type' => 'appraisal',
    'valued_on' => '2026-03-14',
    'amount' => 650,
    'currency' => 'usd',
    'confidence' => 'certain',
    'valuer' => 'Scranton Jewelers',
    'method' => 'Inspection and comparable sales',
    'reference_number' => 'APP-2026-0212',
    'source_url' => 'https://scrantonjewelers.example.com/appraisals/0212',
    'note' => 'Michael insists the gold paint adds to its worth.',
]);
```

## Response

`201`

```json
{
    "data": {
        "type": "possession_valuation",
        "id": "3d7b1e94-8a2c-4f60-b5d3-6e19c0a7f248",
        "attributes": {
            "type": "appraisal",
            "valued_on": "2026-03-14",
            "confidence": "certain",
            "amount": "650.00",
            "currency": "usd",
            "is_current": true,
            "valuer": "Scranton Jewelers",
            "method": "Inspection and comparable sales",
            "reference_number": "APP-2026-0212",
            "source_url": "https://scrantonjewelers.example.com/appraisals/0212",
            "note": "Michael insists the gold paint adds to its worth.",
            "documents": [],
            "created_at": 1773446400
        },
        "links": {
            "self": "https://my.monicahq.com/api/v1/vaults/dunder-mifflin/possessions/9c4e2a71-5b38-4f06-8d1e-2a7f3c6b9e15/valuations/3d7b1e94-8a2c-4f60-b5d3-6e19c0a7f248",
            "web": "https://my.monicahq.com/vaults/dunder-mifflin/possessions/9c4e2a71-5b38-4f06-8d1e-2a7f3c6b9e15/valuations"
        }
    }
}
```
