Skip to content

Property report ​

Integrate with an AI assistant
Download or copy the integration prompt for Property report and paste it into Claude Code, Cursor or Copilot: it contains auth, end-to-end examples and a checklist.
Open

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 URLhttps://api.dokicasa.it
AuthAuthorization: Bearer <api_token>
Content-Typeapplication/json
ResponseAsynchronous: 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 ​

  1. You send the cadastral references, the groups you want and your webhook URL.
  2. We reply 202 with the report_id and the estimated amount.
  3. 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.
  4. 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 ​

GroupContentNotes
datiCadastral data, address, unit status
mappaCoordinates, Street View, static map
intestatariCurrent owners with shares, and historyPersonal data. Starts a scan unless we have one from the last 90 days
documentiDocuments already available for the property, with linksIf there are none the group is EMPTY and free
valutazioneMarket estimate, €/m², area dataMay be unavailable for some properties
comparabiliReal sales nearby, with a valuationIf there are none the group is EMPTY and free
propensionePropensity to sell and to rent
storiaAnalysis of the deeds and property ratingThe 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 EMPTY or FAILED groups, 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: charges shows amount 0 and 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

bash
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"
  }'
FieldRequiredDescription
comuneYesCadastral code (F205), or the name together with provincia
provinciaIf comune is a nameProvince code
foglioYesCadastral sheet
particellaYesParcel
subalternoNoUp to 4 digits. Without it, see Parcel with several units
sezione_urbanaNoNeeded where the same sheet and parcel exist in several sections
sezioneNoCensus section
catastoNoF buildings (default) or T land
gruppiYesOne or more groups, no duplicates
referenceNoYour own reference, up to 120 characters. Returned in the webhook
webhook_urlYesPublic https URL: internal addresses are not allowed

Response:

json
{
  "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:

json
{
  "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 ​

statusMeaningoutputCharge
READYAll groups deliveredproperty_id, groupsREADY groups
PARTIALOnly some groups deliveredproperty_id, groupsREADY groups
NOT_AVAILABLEProperty found, no group deliveredproperty_id, groupsNone
SUBALTERNO_REQUIREDThe parcel has several unitsunits, units_count, incompleteNone
MULTIPLE_MATCHESSeveral properties matchalternativesNone
PROPERTY_NOT_FOUNDNot returned by the cadastremessage, sometimes unitsNone
SEARCH_FAILEDSearch failed: retry latermessageNone

Group status ​

statusMeaningCharged
READYData in dataYes
EMPTYNo data availableNo
FAILEDFailed: reason in code and messageNo

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.

json
{
  "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.

GroupMain fields
daticatasto, comune, provincia, foglio, particella, subalterno, categoria, classe, consistenza, rendita, indirizzo_completo, stato; for land qualita, ha, are, ca, reddito_dominicale, reddito_agrario
mappalat, lng, geocode_source, street_view_url, static_map_url
intestatariowners[] (nome, cognome, denominazione, codice_fiscale, partita_iva, quota, titolarita), searched_at, history[]
documentidocuments[] (id, name, document_type, extra_type, url, created_at). Open url with your token (Authorization: Bearer <api_token>)
valutazionevalid, price_per_sqm, surface_sqm, estimation, zone, demographics, market_context
comparabiliquery, zone_stats, confidence, comparables_count, returned, valuation, comparables[]
propensionescore_sale, score_rent, label, confidence, reasons, suggested_action, calculated_at
storiaanalysis, 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 ​

HTTPerrorMeaning
400AMOUNT_NOT_ENOUGHInsufficient balance: total_amount and available_amount in the response
401Missing or invalid token
403GROUP_NOT_ENABLEDGroups with no price on your list, listed in groups
404NOT_FOUNDReport missing or from another account
422COMUNE_NOT_FOUNDCadastral code not recognised
422PROVINCIA_REQUIREDMunicipality given by name without provincia
422PROVINCE_NOT_COVEREDTrento or Bolzano
422WEBHOOK_URL_NOT_ALLOWEDThe webhook points to a non-public address
422Invalid fields: details in errors
429More than 30 calls per minute