Property report
With a single call you get a property's data starting from its cadastral references only. You choose which data groups to receive: each group has its own price and you pay only for the ones delivered.
| Base URL | https://api.dokicasa.it |
| Auth | Authorization: Bearer <api_token> |
| Content-Type | application/json |
| Response | Asynchronous: 202 right away, result by webhook |
WARNING
There is no sandbox: every call works on real data, can start cadastral searches and is charged. For testing, ask us to make the groups free on your account.
How it works
- You send the cadastral references, the groups you want and your webhook URL.
- We reply
202with thereport_idand the estimated amount. - We look for the property in our data. If it is missing or out of date, we start a cadastral search on the whole parcel: the search is included in the price.
- We collect the groups and send you one webhook with input and output.
Timing depends on the groups: a few seconds if the property is already in our data, a few minutes if the cadastre is needed, longer with intestatari and storia. After 2 hours we deliver whatever is ready: missing groups are FAILED with code TIMEOUT and are not charged.
Data groups
| Group | Content | Notes |
|---|---|---|
dati | Cadastral data, address, unit status | |
mappa | Coordinates, Street View, static map | |
intestatari | Current owners with shares, and history | Personal data. Starts a scan unless we have one from the last 90 days |
documenti | Documents already available for the property, with links | If there are none the group is EMPTY and free |
valutazione | Market estimate, €/m², area data | May be unavailable for some properties |
comparabili | Real sales nearby, with a valuation | If there are none the group is EMPTY and free |
propensione | Propensity to sell and to rent | |
storia | Analysis of the deeds and property rating | The slowest group: may need a cadastral report and the AI analysis |
Pricing and charges
Each group has a price on your price list and the full report costs the sum of the chosen groups. A group with no price on your list is not active: the call returns 403 GROUP_NOT_ENABLED. Contact us to enable them.
- You pay only for groups delivered with data (status
READY). - You don't pay for
EMPTYorFAILEDgroups, the unit list, a property not found or a failed search. - The same group on the same property is not charged again for 30 days:
chargesshows amount0and the report where you already paid for it. - The charge happens when the report ends, from your balance. Before starting we check that your balance covers this report and those still running: otherwise
400 AMOUNT_NOT_ENOUGH.
Requesting a report
POST /api/property-report
curl -X POST https://api.dokicasa.it/api/property-report \
-H "Authorization: Bearer $API_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"comune": "F205",
"foglio": "412",
"particella": "87",
"subalterno": "3",
"gruppi": ["dati", "mappa", "valutazione"],
"reference": "file-123",
"webhook_url": "https://partner.example/hook"
}'| Field | Required | Description |
|---|---|---|
comune | Yes | Cadastral code (F205), or the name together with provincia |
provincia | If comune is a name | Province code |
foglio | Yes | Cadastral sheet |
particella | Yes | Parcel |
subalterno | No | Up to 4 digits. Without it, see Parcel with several units |
sezione_urbana | No | Needed where the same sheet and parcel exist in several sections |
sezione | No | Census section |
catasto | No | F buildings (default) or T land |
gruppi | Yes | One or more groups, no duplicates |
reference | No | Your own reference, up to 120 characters. Returned in the webhook |
webhook_url | Yes | Public https URL: internal addresses are not allowed |
Response:
{
"status": "PROCESSING",
"report_id": 1842,
"groups": ["dati", "mappa", "valutazione"],
"estimated_amount": 4.5
}estimated_amount is the sum of the group prices: the final amount can be lower.
If you repeat the same request while the first is still running, you get the same report_id and one webhook.
NOTE
The provinces of Trento and Bolzano are not covered: they use the land register system.
The webhook
When the work is done we send a POST to your webhook_url:
{
"event": "property_report.completed",
"report_id": 1842,
"status": "PARTIAL",
"reference": "file-123",
"input": {
"comune": "F205",
"foglio": "412",
"particella": "87",
"subalterno": "3",
"gruppi": ["dati", "mappa", "valutazione"],
"reference": "file-123"
},
"output": {
"property_id": 4595749,
"groups": {
"dati": { "status": "READY", "data": { "categoria": "A/2", "rendita": "500,00", "stato": "ACTIVE" } },
"mappa": { "status": "READY", "data": { "lat": 45.46, "lng": 9.19 } },
"valutazione": {
"status": "FAILED",
"code": "NOT_AVAILABLE",
"message": "Valutazione non disponibile per questo immobile. Non addebitata."
}
}
},
"charges": {
"total_amount": 2.5,
"groups": {
"dati": { "amount": 2 },
"mappa": { "amount": 0.5 }
}
},
"requested_at": "2026-11-03T10:15:00+01:00",
"completed_at": "2026-11-03T10:16:12+01:00"
}The message texts are in Italian.
Signature and delivery
The Signature header is the HMAC-SHA256 of the raw body, signed with your api_token. Same mechanism as the other webhooks: see Signature.
Reply with a 2xx right away: we wait 3 seconds and make up to 3 attempts, the second after about 10 seconds and the third after about 100. If your server was down, the report stays available through the GET.
Report status
status | Meaning | output | Charge |
|---|---|---|---|
READY | All groups delivered | property_id, groups | READY groups |
PARTIAL | Only some groups delivered | property_id, groups | READY groups |
NOT_AVAILABLE | Property found, no group delivered | property_id, groups | None |
SUBALTERNO_REQUIRED | The parcel has several units | units, units_count, incomplete | None |
MULTIPLE_MATCHES | Several properties match | alternatives | None |
PROPERTY_NOT_FOUND | Not returned by the cadastre | message, sometimes units | None |
SEARCH_FAILED | Search failed: retry later | message | None |
Group status
status | Meaning | Charged |
|---|---|---|
READY | Data in data | Yes |
EMPTY | No data available | No |
FAILED | Failed: reason in code and message | No |
FAILED codes: NOT_AVAILABLE, OWNERS_NOT_FOUND, TIMEOUT.
Parcel with several units
If you omit subalterno and the parcel has several units, you get the list for free and repeat the call with the one you want. If there is only one unit, the report continues on it.
{
"event": "property_report.completed",
"report_id": 1843,
"status": "SUBALTERNO_REQUIRED",
"output": {
"message": "La particella ha piu' unita': ripetere la chiamata indicando il subalterno.",
"incomplete": false,
"units_count": 2,
"units": [
{ "catasto": "F", "foglio": "412", "particella": "87", "subalterno": "3", "status": "ACTIVE" },
{ "catasto": "F", "foglio": "412", "particella": "87", "subalterno": "4", "status": "SUPPRESSED" }
]
}
}incomplete: true means the cadastre did not return every unit, so the list may have a gap. Suppressed units stay in the list and can be requested: the dati group reports "stato": "SUPPRESSED".
With MULTIPLE_MATCHES, repeat the call with sezione_urbana, picking it from alternatives.
Group content
Each group is in output.groups.<group>.data. Field names are in Italian, the same as in the Italian page, which has an example for every group.
| Group | Main fields |
|---|---|
dati | catasto, comune, provincia, foglio, particella, subalterno, categoria, classe, consistenza, rendita, indirizzo_completo, stato; for land qualita, ha, are, ca, reddito_dominicale, reddito_agrario |
mappa | lat, lng, geocode_source, street_view_url, static_map_url |
intestatari | owners[] (nome, cognome, denominazione, codice_fiscale, partita_iva, quota, titolarita), searched_at, history[] |
documenti | documents[] (id, name, document_type, extra_type, url, created_at). Open url with your token (Authorization: Bearer <api_token>) |
valutazione | valid, price_per_sqm, surface_sqm, estimation, zone, demographics, market_context |
comparabili | query, zone_stats, confidence, comparables_count, returned, valuation, comparables[] |
propensione | score_sale, score_rent, label, confidence, reasons, suggested_action, calculated_at |
storia | analysis, rating, atti[], recap_comunale, structured_output, immobili_soppressi_collegati, codici_fiscali, last_refreshed_at, is_stale |
IMPORTANT
intestatari contains personal data: you may process it only if you have a legal basis to do so.
Reading a report
GET /api/property-report/{id}
Same format as the webhook. While the report is PROCESSING, output is null: data is visible once the report ends. A report from another account returns 404.
Errors
| HTTP | error | Meaning |
|---|---|---|
400 | AMOUNT_NOT_ENOUGH | Insufficient balance: total_amount and available_amount in the response |
401 | Missing or invalid token | |
403 | GROUP_NOT_ENABLED | Groups with no price on your list, listed in groups |
404 | NOT_FOUND | Report missing or from another account |
422 | COMUNE_NOT_FOUND | Cadastral code not recognised |
422 | PROVINCIA_REQUIRED | Municipality given by name without provincia |
422 | PROVINCE_NOT_COVERED | Trento or Bolzano |
422 | WEBHOOK_URL_NOT_ALLOWED | The webhook points to a non-public address |
422 | Invalid fields: details in errors | |
429 | More than 30 calls per minute |