Getting started
Welcome to the Appraisal documentation. Use the left navigation to browse endpoints and guides.
Environments
https://appraisal.realitycs.it
https://sandbox-appraisal.realitycs.it
All the requests do require an OAUTH 2.0 auth token in the header, see the authentication page for details.
How it works
The service is built around the appraisal (perizia), a resource you create once and then enrich. You submit the property being appraised, you get back a richiesta_uid, and every analysis endpoint takes that identifier in the path.
- Insert the appraisal with the data of the property. The response contains the
richiesta_uid. - Request any of the analyses below, passing the identifier in the path:
/perizia/<uuid>/<analysis>. - Update the appraisal whenever the data of the property changes, then read the analyses again.
| Analysis | Content |
|---|---|
| Property Value | Estimated value of the property, with its range and interpretation |
| ESG | Values associated with the energy certification and the energy class |
| Risk | Danger and vulnerability indices, and physical risk in euro |
| Forecast | Forecast of the sale price |
| Comps Ita | Comparables linked to the appraisal |
Request format
Creation and update are POST calls taking a JSON body, the analyses are GET calls with no body:
Content-Type: application/json
The richiesta_uid
The identifier returned by Insert Appraisal is derived from the perizia_id and bene_id you pass in: the same pair always maps to the same richiesta_uid.
Inserting twice is not the same as updating
Because the identifier is derived from your own two ids, re-posting to /perizia with the same perizia_id and bene_id addresses the same appraisal rather than creating a second one. Use perizia_id and bene_id to model your own key: a pair per property being appraised. To change the data of an existing appraisal use Update Appraisal with the uuid in the path.
Mandatory input depends on the analysis
Insert Appraisal accepts the full description of the property, but which of those fields are required is not a property of the creation call: it depends on the analyses you intend to read afterwards. Each analysis page carries its own Mandatory Input section listing what must have been provided at insert or update time.
Plan this before the first call: if a field an analysis needs was not submitted, you have to go through Update Appraisal before that analysis can answer.
Identifying the property typology
One of tipologia_id or categoria_catastale is required. For non residential properties prefer categoria_catastale. The accepted values for both are listed in Taxonomies, together with the other codified fields such as stato_id, classe_energetica and riscaldamento_id.
Response format
The analyses return their payload directly, wrapped in a key named after the analysis (property_value, esg, pericolosita, vulnerabilita, rischio, forecast). There is no _metadata envelope.
The warnings field is for debugging
If a response carries a warnings field, it is meant for debugging only. Do not build logic on its content and do not surface it to end users.
Comparables are an exclusive alternative
Comps Ita exposes the comparables of an appraisal through this service. It requires a specific user configuration and is an exclusive alternative to the standalone Comps finder API: the two are not meant to be used together. Contact the Sales team to have it activated.
Changes
All updates to the endpoints are tracked in the Changelog.