API v1
v1
View as Markdown

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

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.

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 default: 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.

POST
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."
}'
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()
$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
{
"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"
}
}
}

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