REST API: listings in the OpenImmo 2.0 shape
Read and write listings in the shape of OpenImmo 2.0. Two ids, drafts, receipts, warnings, and every member of a listing.
Last updated:
A listing at /v1/listings has the shape of OpenImmo 2.0, the open standard for real estate data. The names, the nesting and the allowed values are the standard's. This page describes how Athaus uses it, in our own words. The standard itself defines what each member means.
A listing is an object with these parts:
| Part | Content |
|---|---|
data | the property: type, location, prices, spaces, conditions, energy, features, texts, management |
metadata | where the listing comes from: your ids under source |
contact | the person responsible for the listing (The contact person) |
media | the photos and documents, named by externalMediaId (Photos and documents) |
userDefined | the extension slot of the standard, for data it has no member for |
On reading, contact is there only when the listing has a person of its own, media only when it has files, and userDefined only when it has entries. Athaus adds four members to a listing it returns: listingId, status, createdAt and updatedAt. A client that only knows the standard ignores them.
OpenImmo is also how listings travel elsewhere. Athaus sends OpenImmo XML 1.2.7 to portals and reads any 1.2.x version from a connected CRM. Sending OpenImmo 2.0 JSON exists in the code, but no portal accepts it today. All of them use the same listing; this page is about the REST API.
The JSON shape of /v1 follows OpenImmo 2.0.0. Version 1.2.7 is an XML transfer format with German element names and has no JSON or REST form. XML 1.2.7 stays supported for import and for the portals.
Two ids
| Id | Whose | Where |
|---|---|---|
externalListingId | yours | in the path of every call; it is metadata.source.offererMarketingKey |
listingId | ours | in responses, and in inquiries, viewings and files as the listing they belong to |
On create and on PUT, both members of metadata.source are required: offererMarketingKey and offererEstateId. Athaus stores only offererMarketingKey. offererEstateId is not stored and comes back in responses with the same value as the key. Send the same value in both. The key is your reference and must be unique in the office (reference_already_exists). An address, together with its unit, belongs to one listing per office (address_already_exists, see several flats in one house). An id is 1 to 128 letters, digits, dots, underscores or hyphens, and does not start or end with a dot; anything else is a 400.
Several flats in one house
A house with several flats is several listings at one address. Tell them apart with data.location.unit (the flat or unit number), staircase and entrance. Athaus holds one listing per office for each combination of street, house number, postal code, city, unit, staircase and entrance. Case and extra spaces do not count: WE 3b and we 3B are the same unit.
- Without
unit,staircaseandentrance, the address alone is the key, as before: a second listing at the same address is409 address_already_exists. This protects against doubles when an integration retries without its key. - The
409names the listing of your own office that holds the address and unit, with itsexternalListingIdandlistingId. There are two ways out: change that listing, or send aunitthat tells the two apart. - A
PATCHthat moves a listing onto a taken unit is the same409. Clearingunit,staircaseorentranceof a running listing is409 listing_active, like clearing any address part. A comma inside one of the three is stored as a space. - A draft that only knows a postal code and a city has no street, so it holds no address: any number of such drafts can exist. The address is checked when a street is added.
- The OpenImmo XML for portals carries the unit in
wohnungsnr(with staircase and entrance appended, for the exact address only). New-build projects with their units are not part of this.
Create a listing
Creating a listing answers 202 with a receipt. The listing is written before the answer, so you can read it at once.
curl -X POST "https://api.athaus.ai/v1/listings" \
-H "Authorization: Bearer ath_live_..." \
-H "Idempotency-Key: $(uuidgen)" \
-H "Content-Type: application/json" \
-d '{
"data": {
"estateType": "APARTMENT",
"estateSubType": { "apartment": "MULTI_STOREY" },
"distributionType": "BUY",
"location": {
"postalcode": "10435",
"city": "Berlin",
"street": "Kastanienallee",
"houseNumber": "12",
"country": "DEU",
"geometry": { "type": "Point", "coordinates": [13.4128, 52.5395] }
},
"prices": { "currency": "EUR", "buy": { "price": { "amount": 350000 } } },
"spaces": { "spaceMeasureUnit": "SQUARE_METER", "residential": { "livingSpace": 62 } },
"structure": { "rooms": { "numberOfRooms": 2 } },
"texts": { "headline": { "en": "Bright two-room apartment" } }
},
"metadata": { "source": { "offererEstateId": "WE-12", "offererMarketingKey": "WE-12" } }
}'{
"requestId": "req_0f3a9c2b7d4e41a8b6c15e9d3a7f2b04",
"listingId": "0190f3a2-7c1e-7b0e-9a41-5d2f6e8c3b17",
"externalListingId": "WE-12",
"warnings": []
}The header Location points to the new listing. A coordinate is required in data.location.geometry as a GeoJSON point: longitude first, then latitude. Creating does not publish. A new listing is a draft until it is published (Status).
Read a listing
curl "https://api.athaus.ai/v1/listings/WE-12" \
-H "Authorization: Bearer ath_live_..."The listing sits under listing:
{
"listing": {
"listingId": "0190f3a2-7c1e-7b0e-9a41-5d2f6e8c3b17",
"status": "draft",
"createdAt": "2026-11-11T09:30:00Z",
"updatedAt": "2026-11-11T09:30:00Z",
"data": {
"estateType": "APARTMENT",
"estateSubType": { "apartment": "MULTI_STOREY" },
"distributionType": "BUY",
"location": {
"postalcode": "10435",
"city": "Berlin",
"street": "Kastanienallee",
"houseNumber": "12",
"country": "DEU",
"geometry": { "type": "Point", "coordinates": [13.4128, 52.5395] }
},
"prices": { "currency": "EUR", "buy": { "price": { "amount": 350000 } } },
"spaces": { "spaceMeasureUnit": "SQUARE_METER", "residential": { "livingSpace": 62 } },
"structure": { "rooms": { "numberOfRooms": 2 } },
"texts": { "headline": { "en": "Bright two-room apartment" } }
},
"metadata": { "source": { "offererEstateId": "WE-12", "offererMarketingKey": "WE-12" } }
}
}With If-None-Match and the current ETag the call answers 304 without a body. GET /v1/listings lists the ids page by page (Pagination).
Status
status is one of draft, active, paused, reserved and closed. closed means sold or let. Which one it is stands in data.management.marketStatus. reserved and closed show there too. status is read-only: you do not set it with PATCH, and Athaus does not store data.management.marketStatus from a body (FIELD_IGNORED). These calls change the state:
POST /v1/listings/{externalListingId}/publishputs the listing online. The checks are those of the button in the app: the plan, the mandatory details, the energy certificate, a photo. If the key has the scopeapproveand the office's automation for publishing is set to "Automatic", the call answers200with the listing, andstatusisactive. Otherwise it answers202with a proposal that a person confirms in the app (What leaves the office).Idempotency-Keyis required. A listing that is not complete is409listing_incomplete, anderrorsnames what is missing.POST /v1/listings/{externalListingId}/unpublishtakes a running listing off the market at once and answers200, andstatusispaused. Taking down only removes, so it waits for nobody. A listing that is not running is409listing_not_online.POST /v1/listings/{externalListingId}/unit-statussets the status of a listing that is a unit of a new-build project and answers200with the listing. It is described with the projects.projectIdin the listing shows that it is a unit.
Drafts
An address is often not known yet when a listing is first entered. With draft=true on POST and PUT, only metadata.source, data.distributionType and data.estateType are required, and everything else is checked when the listing is published. OpenImmo has no draft parameter and no publish operation, so draft is an addition of Athaus.
curl -X POST "https://api.athaus.ai/v1/listings?draft=true" \
-H "Authorization: Bearer ath_live_..." \
-H "Content-Type: application/json" \
-d '{ "data": { "estateType": "APARTMENT", "distributionType": "BUY" }, "metadata": { "source": { "offererEstateId": "WE-15", "offererMarketingKey": "WE-15" } } }'Change and delete
PUT /v1/listings/{externalListingId}needs a complete body (ordraft=true) and then changes the listing likePATCH: what the body does not name stays,nullclears it. For an unknown idPUTanswers404. WithcreateIfMissing=trueAthaus creates the listing instead, so a sender can alwaysPUT.PATCH /v1/listings/{externalListingId}changes parts as a merge patch (RFC 7396): a member you send replaces the stored one,nullremoves it, a list is replaced whole. The result must still be a valid listing. OpenImmo has noPATCH; this is an addition.DELETE /v1/listings/{externalListingId}removes the listing and answers202. A published listing, a running brokerage agreement and upcoming viewings stop it (409).
All three accept If-Match and answer 412 when the state changed (Writing).
curl -X PATCH "https://api.athaus.ai/v1/listings/WE-12" \
-H "Authorization: Bearer ath_live_..." \
-H "Content-Type: application/merge-patch+json" \
-d '{ "data": { "prices": { "buy": { "price": { "amount": 340000 } } } } }'Warnings
A write that worked can still carry notes. They stand in warnings of the receipt, each with a type and a message. There is one type:
| Type | Meaning |
|---|---|
FIELD_IGNORED | a member was accepted but Athaus does not store it |
Data the standard has no member for
userDefined is the extension slot of the standard. Athaus writes these names into it and reads them back:
| Name | Type | Content |
|---|---|---|
location.district | string | the district or quarter |
tenure | string | freehold, leasehold, commonhold or cooperative |
price.deposit | decimal | the rent deposit |
price.associationFee | decimal | the monthly fee to the owners' association |
conditions.interiorQuality | string | BASIC, STANDARD, UPSCALE or LUXURY |
conditions.interiorQuality | string | BASIC, STANDARD, UPSCALE or LUXURY |
management.petsPolicy | string | ALLOWED, NOT_ALLOWED or CASE_BY_CASE |
management.usage | string | free text on the use |
structure.parkingSpaces | integer | the number of parking spaces when no type is known |
Five more names start with de. and belong to the German profile (Country profiles).
Photos and documents
You upload a file once and then name it in the listing. The two steps do not depend on each other: you can upload files before the listing exists.
1. Upload. POST /v1/medias takes the file itself as the body, not JSON. Content-Type is its type: image/jpeg, image/png, image/webp or application/pdf, at most 25 MB. Athaus checks that the bytes are of that type; a PDF sent as image/png is a 415. The query says what the file is:
| Parameter | Meaning |
|---|---|
kind | photo, floor_plan or document. Without it an image is a photo and a PDF a document. A photo must be an image. |
documentType | for a document, which paper it is: energy_certificate, floor_plan, living_area, land_registry, declaration_of_division, budget_plan, logs, utilities, lease, property_tax, expose, modernization or other |
fileName | the name the file carries in the app and in downloads |
externalMediaId | your id for the file, which the listing names in media. Without it Athaus uses the id of the answer. It is unique in the office while the file waits for a listing (409 reference_already_exists). |
curl -X POST "https://api.athaus.ai/v1/medias?externalMediaId=front&fileName=front.jpg" \
-H "Authorization: Bearer $ATHAUS_KEY" \
-H "Idempotency-Key: $(uuidgen)" \
-H "Content-Type: image/jpeg" \
--data-binary @front.jpgThe answer is 201 with id, externalMediaId, kind, documentType, fileName, mimeType, sizeBytes and, for images, width and height. The id stays the id of the file under /v1/files. With Idempotency-Key a retry is safe: the same bytes and parameters return the same answer and store no second file. Athaus removes a file that no listing names within seven days. At most 200 files and 1 GB wait for a listing in an office (413 payload_too_large).
2. Name. media in the listing is a list of externalMediaId with a title. The order of the list is the order of the files within each kind. The first photo is the cover.
"media": [
{ "externalMediaId": "front", "title": "Street side" },
{ "externalMediaId": "plan-ground-floor" },
{ "externalMediaId": "energy-certificate" }
]| You send | Effect |
|---|---|
no media | the files stay as they are |
| a list | named uploads become files of the listing, named files of the listing get their order and title, and files that came through the API and are no longer named are removed |
media: [] or media: null (with PATCH) | every file that came through the API is removed |
Files someone added in the app have no externalMediaId. A list never removes them. You can order and title them by naming their id as externalMediaId. If you upload a file under the id of a file the listing already has and name it in media, it replaces that file. The replacement carries the id of the upload, and the old address under /v1/files stops working.
An id that is neither an upload nor a file of the listing, appears twice, or belongs to another office is a 400 with the entry media[n].externalMediaId. A listing takes at most 40 files and 500 MB (413 payload_too_large). On an error nothing is created.
3. Read. The listing returns media when it has files: per file externalMediaId, title, id, kind, documentType, fileName, mimeType, sizeBytes, width, height and contentUrl. You fetch the contentUrl (/v1/files/{id}/content) with the same key (Downloading files). The order is photos, floor plans, documents, each by rank.
Athaus does not fetch a file from an address you name. The bytes always come from you.
The contact person
contact names the person who appears in the exposé and in the portal export. Athaus stores the name (firstName and lastName, or name, which is split at the last space), emailAddress and phoneNumber. A listing without contact keeps the responsible person of the office, and the answer has no contact. As soon as one of the four members is set, it replaces the responsible person as a whole: what is missing does not appear in the exposé.
As elsewhere, a member that is missing stays, a named null clears it, and contact: null removes the person. Every other member of contact (salutation, mobile number, address, displayedInformation and so on) is not stored. Each one you send appears in a FIELD_IGNORED warning.
The members of a listing
This is every member Athaus accepts and returns. Types that are lists of values are at the end. The standard says what each member means.
ListingPatch
| Member | Type | Required | Note |
|---|---|---|---|
data | object | any | no | |
metadata | object | any | no | |
userDefined | object[] | any | no | |
media | object[] | any | no | |
contact | object | any | no |
ListingEnergy
| Member | Type | Required | Note |
|---|---|---|---|
energyType | object | no | |
energyType.heatMethod | string | no | One of CENTRAL, INDIVIDUAL, STOREY. |
energyType.heatForm | object | no | |
energyType.heatForm.air | boolean | no | |
energyType.heatForm.radiator | boolean | no | |
energyType.heatForm.stove | boolean | no | |
energyType.heatForm.underfloor | boolean | no | |
energyType.heatForm.wallCeiling | boolean | no | |
energyType.energySource | object | no | |
energyType.energySource.coal | boolean | no | |
energyType.energySource.districtHeating | boolean | no | |
energyType.energySource.electric | boolean | no | |
energyType.energySource.gas | boolean | no | |
energyType.energySource.geothermal | boolean | no | |
energyType.energySource.liquidGas | boolean | no | |
energyType.energySource.oil | boolean | no | |
energyType.energySource.solarHeat | boolean | no | |
energyType.energySource.solarPower | boolean | no | |
energyType.energySource.wind | boolean | no | |
energyType.energySource.wood | boolean | no | |
energyType.energySource.woodPellet | boolean | no | |
energyType.energyGeneration | object | no | |
energyType.energyGeneration.fossilburning | boolean | no | |
energyType.energyGeneration.heatpump | boolean | no | |
energyType.energyGeneration.combinedHeatAndPowerPlant | boolean | no | |
energyType.maxElectricalPower | integer | no | -9007199254740991 to 9007199254740991. |
countrySpecific | object | no | |
countrySpecific.de | object | no | |
countrySpecific.de.energyCertificates | object[] | no | |
countrySpecific.de.energyCertificates[].nameOfCertificate | string | no | |
countrySpecific.de.energyCertificates[].certificateType | string | no | One of ENEV2008, ENEV2014, ENEV2026, NOT_AVAILABLE, NOT_NECESSARY, AT_VISIT. |
countrySpecific.de.energyCertificates[].certificateBasedOn | string | no | One of NEED, CONSUMPTION. |
countrySpecific.de.energyCertificates[].isResidentialBuilding | boolean | no | |
countrySpecific.de.energyCertificates[].primaryEnergySource | string | no | One of NO_INFORMATION, SOLAR, WIND, COAL, GAS, OIL, WOOD, DISTRICT_HEATING, ELECTRICITY. |
countrySpecific.de.energyCertificates[].efficiencyClass | string | no | One of A_PLUS, A, B, C, D, E, F, G, H. |
countrySpecific.de.energyCertificates[].releaseDate | string (date) | no | |
countrySpecific.de.energyCertificates[].validUntil | string (date) | no | |
countrySpecific.de.energyCertificates[].yearOfConstructionBuilding | integer | no | -9007199254740991 to 9007199254740991. |
countrySpecific.de.energyCertificates[].yearOfConstructionHeating | integer | no | -9007199254740991 to 9007199254740991. |
countrySpecific.de.energyCertificates[].overallEnergyNeed | number | no | |
countrySpecific.de.energyCertificates[].primaryEnergyNeed | number | no | |
countrySpecific.de.energyCertificates[].electricityNeed | number | no | |
countrySpecific.de.energyCertificates[].heatingNeed | number | no | |
countrySpecific.de.energyCertificates[].overallEnergyConsumption | number | no | |
countrySpecific.de.energyCertificates[].primaryEnergyConsumption | number | no | |
countrySpecific.de.energyCertificates[].isWaterHeatingIncluded | boolean | no | |
countrySpecific.de.energyCertificates[].electricityConsumption | number | no | |
countrySpecific.de.energyCertificates[].heatingConsumption | number | no | |
countrySpecific.de.energyCertificates[].energyConsumptionIndicator | number | no | |
countrySpecific.de.houseEnergyStandardType | string | no | One of UNSPECIFIED, LOW_ENERGY_40, LOW_ENERGY_60, PASSIVE_HOUSE, ENERGY_EFFICIENT_40, ENERGY_EFFICIENT_55, ENERGY_EFFICIENT_70, LOW_ENERGY_HOUSE, NULL_ENERGY_HOUSE, PLUS_ENERGY_HOUSE. |
countrySpecific.de.primaryEnergySource | string | no |
Projects
A project has these members; the units of a project are listings.
ProjectEventObject
| Member | Type | Required | Note |
|---|---|---|---|
object | string | yes | Always project. |
id | string | yes | The projectId. |
externalProjectId | string | yes | |
projectId | string | yes |
ProjectDeleted
| Member | Type | Required | Note |
|---|---|---|---|
object | string | yes | Always project. |
id | string | yes | |
deleted | boolean | yes | Always true. |
Keep reading
REST API: country profiles
The core of the API is the same for every country. What differs per country sits in a profile. Germany is the first.
REST API: writing and idempotency
Create, change and delete listings and contacts. Merge patch, Idempotency-Key for safe retries, ETag and If-Match against overwriting.
REST API reference
Every operation of /v1 with parameters, response and example, generated from the contract of the API.