Valuations endpoint
Valuations API
/api/v1/valuations supports the full CRUD lifecycle.
List
GET /valuations?page=1&limit=50&status=approved&customerEmail=jane@example.com
Returns a paginated list. Filters: status, customerEmail, customerName, location, from, to, minRetailValue, maxRetailValue. Sort with sortBy and sortOrder.
Create
POST /valuations
Body shape — see the [TypeScript types in the OpenAPI doc](/docs). Required:
customerName,customerEmailitemType(one of jewellery / watch / loose-diamond / loose-gemstone / other)retailValue(number, in tenant currency)
Returns the created valuation including its assigned reference number.
Retrieve
GET /valuations/{id}
Update
PATCH /valuations/{id}
Partial update — only fields you send are changed. The audit log captures the old + new value of each changed field.
Delete
DELETE /valuations/{id} — permanently deletes the valuation (admin role required). Returns 204 on success.
Share with a customer
POST /valuations/{id}/share returns a public access token + URL that lets the customer view the valuation without authentication.
Plan limits
The Basic plan caps you at 50 valuations/month. POSTs that would exceed return 403 with error: 'Plan Limit Reached'.