Mandatory Disclosures and Privacy
The API enforces a set of minimum disclosures before every publication. This guide explains what they are and how to fill them in.
This portal is a demonstration environment. The notes below describe the API's behavior and are not a substitute for legal advice.
Energy Certificate
Anyone advertising a property must state the figures from its energy certificate. When publishing, the API checks these fields on the property:
| Field | Required | Example |
|---|---|---|
energy_certificate.type | yes | consumption or demand |
energy_certificate.final_energy_demand_kwh | yes | 118.4 |
energy_certificate.energy_source | yes | district_heating |
energy_certificate.system_year | for a demand-based certificate | 1998 |
energy_certificate.efficiency_class | yes | D |
energy_certificate.valid_until | yes | 2031-04-30 |
An expired valid_until results in 422 with reason: "expired". For a heritage-protected property, set energy_certificate.exemption: "heritage_protection" instead; the other fields are then not required.
Commission Disclosure
Under a split-commission principle that applies to many consumer property sales, the commission must appear in the listing, and the buyer-side share generally can't exceed the seller-side share.
{
"commission": {
"buyer_percent": 3.57,
"seller_percent": 3.57,
"note": "includes applicable sales tax, due on signing"
}
}
If buyer_percent is greater than seller_percent, publication is rejected with code: "commission_invalid".
Other Minimum Disclosures
The disclosures section of the response from GET /listings/{id} lists the full checked set:
- Property type and location, stated as precisely as is customary
- Living or usable area and number of rooms
- Purchase price or cold rent, plus service charges and deposit for a rental
- Availability date
- Name and address of the marketing agency
Lead Data and Retention Periods
Lead data is personal data. For every lead, the API therefore tracks a retention_until, set automatically at creation:
| Situation | Default period |
|---|---|
| Inquiry with no further contact | 6 months from the last activity |
| Viewing took place | 12 months from the appointment |
| Financial disclosure provided | 12 months, then mandatory deletion |
| Contract concluded | Extended, per applicable record-keeping requirements |
After expiry, records are anonymized nightly: name, address and contact details are removed, statistical attributes are kept.
You act on a deletion request immediately with:
curl -X POST https://api.realestateagency.example/v1/leads/lead_71ab/deletion \
-H "apikey: $REAL_ESTATE_API_KEY" \
-H "Content-Type: application/json" \
-d '{ "reason": "data_subject_request", "source": "email dated 2026-08-18" }'
Only request a financial disclosure once a viewing appointment is confirmed. Before that, collecting the data usually isn't necessary - and anything that's never collected doesn't need to be protected or deleted either.