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, customerEmail
• itemType (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'.