Create report

POST /api/report/appraisal

Entry point of the whole flow: submits the property to analyse and creates the report. The response returns the uuid that identifies it, and that every other endpoint of this section takes as a path parameter.

Example Request

curl --location 'https://insights.immobiliare.it/api/report/appraisal' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <token>' \
--data '{
    "address": "Via Roma, 10, Prato, PO",
    "lat": 43.865818409317896,
    "lng": 11.039137599752786,
    "asset_group_id": 1,
    "asset_typology_id": 1,
    "construction_year": 2000,
    "maintenance_status_id": 3,
    "energy_class_id": 8,
    "floor": [0],
    "rooms": 5,
    "bathroom": 2,
    "elevator": false,
    "surfaces": [
        {
            "surface_type_id": 1,
            "surface_mq": 90,
            "coefficient": 100,
            "until_mq": null,
            "coefficient_over": null
        }
    ],
    "report_type_id": 2,
    "reference": "Report API",
    "report_scope_id": "1"
}'

Request Fields

Property

Field	Required	Description	Type	Example	Notes
`lat`	yes	Latitude of the property	number	`43.865818409317896`
`lng`	yes	Longitude of the property	number	`11.039137599752786`
`address`	optional	Address of the property	string	`Via Roma, 10, Prato, PO`	Shown on the report
`asset_group_id`	yes	Macro group of the property type	number	`1`	`ASSET_GROUPS` taxonomy
`asset_typology_id`	yes	Property type	number	`1`	`ASSET_TYPES` taxonomy
`construction_year`	yes	Year of construction	number	`2000`
`maintenance_status_id`	yes	Maintenance condition	number	`3`	`MAINTENANCE_STATUS` taxonomy
`energy_class_id`	yes	Energy class	number	`8`	`ENERGY_CLASSES` taxonomy
`floor`	yes	Floors the unit is on	array	`[0]`	Array even for a single floor
`rooms`	yes	Number of rooms	number	`5`
`bathroom`	yes	Number of bathrooms	number	`2`	Singular, not `bathrooms`
`elevator`	yes	Whether the building has a lift	boolean	`false`
`surfaces`	yes	Surfaces of the property	array		At least one entry, see below

surfaces[]

Field	Required	Default	Description	Type	Example	Notes
`surface_type_id`	yes		Type of surface	number	`1`	`SURFACE_TYPES` taxonomy
`surface_mq`	yes		Extent of the surface, in m²	number	`90`
`coefficient`	optional		Commercial coefficient to weight the surface with, in %	number	`100`
`until_mq`	optional	`null`	Threshold up to which `coefficient` applies, in m²	number	`null`
`coefficient_over`	optional	`null`	Coefficient applied beyond `until_mq`, in %	number	`null`

Cadastral data

Field	Required	Default	Description	Type	Example
`comune_cadastral`	optional		Cadastral municipality code	string	`E007`
`sezione_cadastral`	optional	`null`	Cadastral section	string	`null`
`foglio_cadastral`	optional		Cadastral sheet	string	`13`
`particella_cadastral`	optional		Cadastral parcel	string	`527`

Report

Field	Required	Description	Type	Example	Notes
`report_type_id`	yes	Type of report to generate	number	`2`	`REPORT_TYPES` taxonomy
`report_scope_id`	optional	Scope of the report	string	`1`
`reference`	optional	Your own reference for the report	string	`Report API`	Echoed back on the report

Agent

Field	Required	Default	Description	Type	Example	Notes
`show_agent`	optional	`false`	Whether to show the agent on the report	boolean	`true`
`agent_id`	optional		Identifier of the agent	number	`1`
`agent_email`	optional		Email of the agent shown on the report	string	`agent@example.com`	Returned by `sales.header`
`agent_phone`	optional		Phone of the agent shown on the report	string	`+39333...`

Generation mode

Field	Required	Default	Description	Type	Example	Notes
`force_no_async`	optional	`false`	Waits for the report to be generated before answering	boolean	`true`	See the note below
`callback`	optional		Callback to be invoked once the generation is complete	object		Contains the `url` key

Where the taxonomy ids come from

Every *_id field marked as a taxonomy is codified against Taxonomies, which returns all the accepted values grouped by taxonomy. Read it once and cache it rather than hardcoding the ids.

SURFACE_TYPES also carries the default coefficient, until_mq and coefficient_over of each type of surface, so you can prefill the surfaces[] entries instead of computing the coefficients yourself.

Synchronous and asynchronous generation

By default the creation is asynchronous: the call returns the uuid immediately, while the report is still being computed. Requesting a data block before it is ready answers 400 with error_code DATA_NOT_EXIST, so the client has to wait for the generation to complete by polling Report status or by declaring a callback.

Setting force_no_async to true makes the call synchronous: the response is held until the report is ready, so the data blocks can be requested straight away.

Synchronous calls are slow

A synchronous creation keeps the connection open for the whole generation, which takes tens of seconds. Make sure your client and any proxy in between tolerate that before setting force_no_async, and prefer the asynchronous flow with Report status for interactive integrations.

Example Response

{
  "_metadata": {
    "message": "",
    "query": {},
    "status": 200
  },
  "data": {
    "uuid": "95318f91-dbc4-4a20-ae71-e511ef6282cf"
  }
}

Errors

Status	`error_code`	Message	Description
400	`DATA_NOT_VALID`	`Dati in post mancanti`	Empty or unparsable body
400	`REQUEST_NOT_VALID`	`lat and lng are mandatory`	`lat` or `lng` missing
400	`DATA_NOT_VALID`	`<field> non indicato`	A required field is missing
400	`DATA_NOT_VALID`	`surfaces non idnicato o formato non valido`	`surfaces` missing or malformed
403		`authentication_required`	Missing, invalid or expired access token

Validation stops at the first missing field, so fix them one at a time or validate client side before calling. See also the general Error Handling page.