REST-API: Inserate in der Form von OpenImmo 2.0
Inserate lesen und schreiben in der Form von OpenImmo 2.0. Zwei Ids, Entwürfe, Quittungen, Hinweise und jedes Mitglied eines Inserats.
Zuletzt aktualisiert:
Ein Inserat bei /v1/listings hat die Form von OpenImmo 2.0, dem offenen Standard für Immobiliendaten. Die Namen, die Verschachtelung und die erlaubten Werte sind die des Standards. Diese Seite beschreibt in eigenen Worten, wie Athaus ihn nutzt. Was ein Mitglied bedeutet, legt der Standard selbst fest.
Ein Inserat ist ein Objekt mit diesen Teilen:
| Teil | Inhalt |
|---|---|
data | die Immobilie: Typ, Lage, Preise, Flächen, Zustand, Energie, Ausstattung, Texte, Verwaltung |
metadata | woher das Inserat kommt: deine Ids unter source |
contact | die zuständige Person des Inserats (Die zuständige Person) |
media | die Fotos und Dokumente, benannt über externalMediaId (Fotos und Dokumente) |
userDefined | der Erweiterungsplatz des Standards, für Daten, für die er kein Mitglied hat |
Beim Lesen steht contact nur da, wenn das Inserat eine eigene Person hat, media nur, wenn es Dateien hat, und userDefined nur, wenn es Einträge gibt. Athaus fügt einem Inserat, das es zurückgibt, vier Mitglieder hinzu: listingId, status, createdAt und updatedAt. Ein Client, der nur den Standard kennt, überliest sie.
Über OpenImmo reisen Inserate auch sonst. Athaus sendet OpenImmo XML 1.2.7 an Portale und liest jede Fassung 1.2.x aus einem angebundenen CRM. Das Senden von OpenImmo 2.0 JSON gibt es im Code, aber heute nimmt es kein Portal an. Alle nutzen dasselbe Inserat. Diese Seite handelt von der REST-API.
Die JSON-Form von /v1 folgt OpenImmo 2.0.0. Die Fassung 1.2.7 ist ein XML-Übertragungsformat mit deutschen Elementnamen und hat keine JSON- oder REST-Form. XML 1.2.7 bleibt für den Import und für die Portale unterstützt.
Zwei Ids
| Id | Wessen | Wo |
|---|---|---|
externalListingId | deine | im Pfad jedes Aufrufs; sie ist metadata.source.offererMarketingKey |
listingId | unsere | in Antworten, und bei Anfragen, Besichtigungen und Dateien als das Inserat, zu dem sie gehören |
Beim Anlegen und bei PUT sind beide Mitglieder von metadata.source Pflicht: offererMarketingKey und offererEstateId. Athaus speichert nur offererMarketingKey. offererEstateId wird nicht gespeichert und kommt in Antworten mit demselben Wert wie der Schlüssel zurück. Schick in beiden denselben Wert. Der Schlüssel ist deine Referenz und muss im Büro eindeutig sein (reference_already_exists). Eine Adresse gehört samt Wohnung je Büro zu einem Inserat (address_already_exists, siehe mehrere Wohnungen in einem Haus). Eine Id besteht aus 1 bis 128 Buchstaben, Ziffern, Punkten, Unterstrichen oder Bindestrichen und beginnt und endet nicht mit einem Punkt; alles andere ist ein 400.
Mehrere Wohnungen in einem Haus
Ein Haus mit mehreren Wohnungen sind mehrere Inserate an einer Adresse. Unterscheide sie mit data.location.unit (die Wohnungs- oder Einheitsnummer), staircase und entrance. Je Büro gibt es ein Inserat für jede Kombination aus Straße, Hausnummer, Postleitzahl, Ort, Wohnung, Treppenhaus und Eingang. Groß- und Kleinschreibung und doppelte Leerzeichen zählen nicht: WE 3b und we 3B sind dieselbe Wohnung.
- Ohne
unit,staircaseundentranceist allein die Adresse der Schlüssel, wie bisher: Ein zweites Inserat an derselben Adresse ist409 address_already_exists. Das schützt vor Doppelten, wenn eine Anbindung ohne ihren Key wiederholt. - Das
409nennt das Inserat deines eigenen Büros, das die Adresse und Wohnung hält, mitexternalListingIdundlistingId. Es gibt zwei Auswege: dieses Inserat ändern oder eineunitschicken, die beide unterscheidet. - Ein
PATCH, der ein Inserat auf eine vergebene Wohnung verschiebt, ist dasselbe409. Wohnung, Treppenhaus oder Eingang eines laufenden Inserats zu leeren ist409 listing_active, wie bei jedem Teil der Adresse. Ein Komma in einem der drei wird als Leerzeichen gespeichert. - Ein Entwurf, der nur Postleitzahl und Ort kennt, hat keine Straße und hält keine Adresse: Davon kann es beliebig viele geben. Die Adresse wird geprüft, sobald eine Straße dazukommt.
- Das OpenImmo-XML für Portale trägt die Wohnung in
wohnungsnr(Treppenhaus und Eingang angehängt, nur bei exakter Adresse). Neubauprojekte mit ihren Einheiten gehören nicht dazu.
Ein Inserat anlegen
Ein Inserat anzulegen antwortet 202 mit einer Quittung. Das Inserat ist vor der Antwort geschrieben, du kannst es sofort lesen.
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": { "de": "Helle Zweizimmerwohnung" } }
},
"metadata": { "source": { "offererEstateId": "WE-12", "offererMarketingKey": "WE-12" } }
}'{
"requestId": "req_0f3a9c2b7d4e41a8b6c15e9d3a7f2b04",
"listingId": "0190f3a2-7c1e-7b0e-9a41-5d2f6e8c3b17",
"externalListingId": "WE-12",
"warnings": []
}Der Kopf Location zeigt auf das neue Inserat. In data.location.geometry ist eine Koordinate als GeoJSON-Punkt Pflicht: erst der Längengrad, dann der Breitengrad. Anlegen veröffentlicht nicht. Ein neues Inserat ist ein Entwurf, bis es veröffentlicht wird (Status).
Ein Inserat lesen
curl "https://api.athaus.ai/v1/listings/WE-12" \
-H "Authorization: Bearer ath_live_..."Das Inserat steht unter 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": { "de": "Helle Zweizimmerwohnung" } }
},
"metadata": { "source": { "offererEstateId": "WE-12", "offererMarketingKey": "WE-12" } }
}
}Mit If-None-Match und dem aktuellen ETag antwortet der Aufruf 304 ohne Rumpf. GET /v1/listings listet die Ids seitenweise (Blättern).
Status
status ist eines von draft, active, paused, reserved und closed. closed heißt verkauft oder vermietet. Welches von beiden, steht in data.management.marketStatus. Auch reserved und closed erscheinen dort. status ist nur zu lesen: Du setzt ihn nicht mit PATCH, und data.management.marketStatus im Rumpf speichert Athaus nicht (FIELD_IGNORED). Den Stand ändern diese Aufrufe:
POST /v1/listings/{externalListingId}/publishstellt das Inserat online. Es gelten dieselben Prüfungen wie beim Knopf in der App: der Tarif, die Pflichtangaben, der Energieausweis, ein Foto. Hat der Key den Scopeapproveund steht die Automatik des Büros für das Veröffentlichen auf "Automatisch", antwortet der Aufruf200mit dem Inserat,statusistactive. Sonst antwortet er202mit einem Vorschlag, den eine Person in der App bestätigt (Was das Büro verlässt).Idempotency-Keyist Pflicht. Ein unvollständiges Inserat ist409listing_incomplete,errorsnennt, was fehlt.POST /v1/listings/{externalListingId}/unpublishnimmt ein laufendes Inserat sofort vom Markt und antwortet200,statusistpaused. Zurücknehmen entfernt nur, darum wartet es auf niemanden. Läuft das Inserat nicht, ist es409listing_not_online.POST /v1/listings/{externalListingId}/unit-statussetzt den Stand eines Inserats, das eine Einheit eines Neubauprojekts ist, und antwortet200mit dem Inserat. Es steht bei den Projekten.projectIdim Inserat zeigt, dass es eine Einheit ist.
Entwürfe
Oft ist die Adresse noch nicht bekannt, wenn ein Inserat zum ersten Mal erfasst wird. Mit draft=true bei POST und PUT sind nur metadata.source, data.distributionType und data.estateType Pflicht, alles andere wird geprüft, wenn das Inserat veröffentlicht wird. OpenImmo kennt weder einen Entwurfsparameter noch eine Veröffentlichen-Operation, draft ist also eine Ergänzung von 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" } } }'Ändern und löschen
PUT /v1/listings/{externalListingId}verlangt einen vollständigen Rumpf (oderdraft=true) und ändert das Inserat dann wiePATCH: Was der Rumpf nicht nennt, bleibt,nullleert es. Bei einer unbekannten Id antwortetPUTmit404. MitcreateIfMissing=truelegt Athaus das Inserat stattdessen an, so kann ein Sender immerPUTschicken.PATCH /v1/listings/{externalListingId}ändert Teile als Merge Patch (RFC 7396): Ein Mitglied, das du schickst, ersetzt das gespeicherte,nullentfernt es, eine Liste wird ganz ersetzt. Das Ergebnis muss weiter ein gültiges Inserat sein. OpenImmo kennt keinPATCH, das ist eine Ergänzung.DELETE /v1/listings/{externalListingId}entfernt das Inserat und antwortet202. Ein veröffentlichtes Inserat, ein laufender Maklervertrag und anstehende Besichtigungen halten es auf (409).
Alle drei nehmen If-Match und antworten 412, wenn sich der Zustand geändert hat (Schreiben).
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 } } } } }'Hinweise
Ein Schreibaufruf, der geklappt hat, kann trotzdem Hinweise tragen. Sie stehen in warnings der Quittung, jeder mit type und message. Es gibt einen Typ:
| Typ | Bedeutung |
|---|---|
FIELD_IGNORED | ein Mitglied wurde angenommen, aber Athaus speichert es nicht |
Daten, für die der Standard kein Mitglied hat
userDefined ist der Erweiterungsplatz des Standards. Athaus schreibt diese Namen hinein und liest sie zurück:
| Name | Typ | Inhalt |
|---|---|---|
location.district | string | der Stadtteil oder das Viertel |
tenure | string | Eigentum, Erbbaurecht, Wohnungseigentum oder Genossenschaft (englisch: freehold, leasehold, commonhold, cooperative) |
price.deposit | decimal | die Mietkaution |
price.associationFee | decimal | das monatliche Hausgeld an die Eigentümergemeinschaft |
conditions.interiorQuality | string | BASIC, STANDARD, UPSCALE oder LUXURY |
management.petsPolicy | string | ALLOWED, NOT_ALLOWED oder CASE_BY_CASE |
management.usage | string | freier Text zur Nutzung |
structure.parkingSpaces | integer | die Zahl der Stellplätze, wenn keine Art bekannt ist |
Fünf weitere Namen beginnen mit de. und gehören zum deutschen Profil (Länderprofile).
Fotos und Dokumente
Eine Datei lädst du einmal hoch und benennst sie dann im Inserat. Die beiden Schritte hängen nicht aneinander: Du kannst Dateien hochladen, bevor es das Inserat gibt.
1. Hochladen. POST /v1/medias nimmt die Datei selbst als Rumpf, kein JSON. Content-Type ist ihr Typ: image/jpeg, image/png, image/webp oder application/pdf, höchstens 25 MB. Ob die Bytes zu dem Typ passen, prüft Athaus; eine PDF mit image/png ist ein 415. Was die Datei ist, sagt die Abfrage:
| Parameter | Bedeutung |
|---|---|
kind | photo, floor_plan oder document. Ohne Angabe ist ein Bild ein photo und eine PDF ein document. Ein photo muss ein Bild sein. |
documentType | bei einem document, welches Papier es ist: energy_certificate, floor_plan, living_area, land_registry, declaration_of_division, budget_plan, logs, utilities, lease, property_tax, expose, modernization oder other |
fileName | der Name, unter dem die Datei in der App und im Download steht |
externalMediaId | deine Id für die Datei, die das Inserat in media nennt. Ohne sie nimmt Athaus die id der Antwort. Sie ist im Büro eindeutig, solange die Datei auf ein Inserat wartet (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.jpgDie Antwort ist 201 mit id, externalMediaId, kind, documentType, fileName, mimeType, sizeBytes und bei Bildern width und height. Die id bleibt die Id der Datei unter /v1/files. Mit Idempotency-Key ist ein Wiederholen sicher: Dieselben Bytes und Parameter geben dieselbe Antwort und legen keine zweite Datei an. Eine Datei, die kein Inserat innerhalb von sieben Tagen nennt, entfernt Athaus wieder. Im Büro warten höchstens 200 Dateien und 1 GB auf ein Inserat (413 payload_too_large).
2. Benennen. media im Inserat ist eine Liste von externalMediaId mit einem title. Die Reihenfolge der Liste ist die Reihenfolge der Dateien je Art. Das erste Foto ist das Titelbild.
"media": [
{ "externalMediaId": "front", "title": "Straßenseite" },
{ "externalMediaId": "plan-eg" },
{ "externalMediaId": "energieausweis" }
]| Du sendest | Wirkung |
|---|---|
kein media | die Dateien bleiben, wie sie sind |
| eine Liste | genannte Uploads werden Dateien des Inserats, genannte Dateien des Inserats bekommen Reihenfolge und Titel, Dateien, die über die API kamen und nicht mehr genannt sind, werden entfernt |
media: [] oder media: null (bei PATCH) | alle Dateien, die über die API kamen, werden entfernt |
Dateien, die jemand in der App hinzugefügt hat, haben keine externalMediaId. Eine Liste entfernt sie nie. Du kannst sie ordnen und betiteln, indem du ihre id als externalMediaId nennst. Lädst du eine Datei unter der Id einer Datei hoch, die das Inserat schon hat, und nennst sie in media, ersetzt sie diese. Die Ersatzdatei trägt die Id des Uploads, die alte Adresse unter /v1/files gilt dann nicht mehr.
Eine Id, die kein Upload und keine Datei des Inserats ist, doppelt vorkommt oder zu einem anderen Büro gehört, ist ein 400 mit dem Eintrag media[n].externalMediaId. Ein Inserat nimmt höchstens 40 Dateien und 500 MB auf (413 payload_too_large). Bei einem Fehler wird nichts angelegt.
3. Lesen. Das Inserat gibt media zurück, wenn es Dateien hat: je Datei externalMediaId, title, id, kind, documentType, fileName, mimeType, sizeBytes, width, height und contentUrl. Die contentUrl (/v1/files/{id}/content) holst du mit demselben Key (Dateien herunterladen). Die Reihenfolge ist: Fotos, Grundrisse, Dokumente, je nach Rang.
Athaus holt keine Datei von einer Adresse, die du nennst. Die Bytes kommen immer von dir.
Die zuständige Person
contact benennt die Person, die im Exposé und im Portalexport steht. Athaus speichert den Namen (firstName und lastName, oder name, das am letzten Leerzeichen geteilt wird), emailAddress und phoneNumber. Hat ein Inserat keinen contact, bleibt es bei der zuständigen Person des Büros, und die Antwort hat kein contact. Sobald eines der vier Mitglieder gesetzt ist, ersetzt es die zuständige Person als Ganzes: Was fehlt, steht nicht im Exposé.
Wie beim Rest gilt: Ein Mitglied, das fehlt, bleibt; ein genanntes null leert es; contact: null entfernt die Person. Alle anderen Mitglieder von contact (Anrede, Mobilnummer, Adresse, displayedInformation und so weiter) speichert Athaus nicht. Jedes, das du sendest, steht in einer Warnung FIELD_IGNORED.
Die Mitglieder eines Inserats
Das ist jedes Mitglied, das Athaus annimmt und zurückgibt. Typen, die Listen von Werten sind, stehen am Ende. Was ein Mitglied bedeutet, sagt der Standard.
ListingPatch
| Mitglied | Typ | Pflicht | Hinweis |
|---|---|---|---|
data | object | any | nein | |
metadata | object | any | nein | |
userDefined | object[] | any | nein | |
media | object[] | any | nein | |
contact | object | any | nein |
ListingEnergy
| Mitglied | Typ | Pflicht | Hinweis |
|---|---|---|---|
energyType | object | nein | |
energyType.heatMethod | string | nein | Eines von CENTRAL, INDIVIDUAL, STOREY. |
energyType.heatForm | object | nein | |
energyType.heatForm.air | boolean | nein | |
energyType.heatForm.radiator | boolean | nein | |
energyType.heatForm.stove | boolean | nein | |
energyType.heatForm.underfloor | boolean | nein | |
energyType.heatForm.wallCeiling | boolean | nein | |
energyType.energySource | object | nein | |
energyType.energySource.coal | boolean | nein | |
energyType.energySource.districtHeating | boolean | nein | |
energyType.energySource.electric | boolean | nein | |
energyType.energySource.gas | boolean | nein | |
energyType.energySource.geothermal | boolean | nein | |
energyType.energySource.liquidGas | boolean | nein | |
energyType.energySource.oil | boolean | nein | |
energyType.energySource.solarHeat | boolean | nein | |
energyType.energySource.solarPower | boolean | nein | |
energyType.energySource.wind | boolean | nein | |
energyType.energySource.wood | boolean | nein | |
energyType.energySource.woodPellet | boolean | nein | |
energyType.energyGeneration | object | nein | |
energyType.energyGeneration.fossilburning | boolean | nein | |
energyType.energyGeneration.heatpump | boolean | nein | |
energyType.energyGeneration.combinedHeatAndPowerPlant | boolean | nein | |
energyType.maxElectricalPower | integer | nein | -9007199254740991 bis 9007199254740991. |
countrySpecific | object | nein | |
countrySpecific.de | object | nein | |
countrySpecific.de.energyCertificates | object[] | nein | |
countrySpecific.de.energyCertificates[].nameOfCertificate | string | nein | |
countrySpecific.de.energyCertificates[].certificateType | string | nein | Eines von ENEV2008, ENEV2014, ENEV2026, NOT_AVAILABLE, NOT_NECESSARY, AT_VISIT. |
countrySpecific.de.energyCertificates[].certificateBasedOn | string | nein | Eines von NEED, CONSUMPTION. |
countrySpecific.de.energyCertificates[].isResidentialBuilding | boolean | nein | |
countrySpecific.de.energyCertificates[].primaryEnergySource | string | nein | Eines von NO_INFORMATION, SOLAR, WIND, COAL, GAS, OIL, WOOD, DISTRICT_HEATING, ELECTRICITY. |
countrySpecific.de.energyCertificates[].efficiencyClass | string | nein | Eines von A_PLUS, A, B, C, D, E, F, G, H. |
countrySpecific.de.energyCertificates[].releaseDate | string (date) | nein | |
countrySpecific.de.energyCertificates[].validUntil | string (date) | nein | |
countrySpecific.de.energyCertificates[].yearOfConstructionBuilding | integer | nein | -9007199254740991 bis 9007199254740991. |
countrySpecific.de.energyCertificates[].yearOfConstructionHeating | integer | nein | -9007199254740991 bis 9007199254740991. |
countrySpecific.de.energyCertificates[].overallEnergyNeed | number | nein | |
countrySpecific.de.energyCertificates[].primaryEnergyNeed | number | nein | |
countrySpecific.de.energyCertificates[].electricityNeed | number | nein | |
countrySpecific.de.energyCertificates[].heatingNeed | number | nein | |
countrySpecific.de.energyCertificates[].overallEnergyConsumption | number | nein | |
countrySpecific.de.energyCertificates[].primaryEnergyConsumption | number | nein | |
countrySpecific.de.energyCertificates[].isWaterHeatingIncluded | boolean | nein | |
countrySpecific.de.energyCertificates[].electricityConsumption | number | nein | |
countrySpecific.de.energyCertificates[].heatingConsumption | number | nein | |
countrySpecific.de.energyCertificates[].energyConsumptionIndicator | number | nein | |
countrySpecific.de.houseEnergyStandardType | string | nein | Eines von 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 | nein |
Projekte
Ein Projekt hat diese Mitglieder; die Einheiten eines Projekts sind Inserate.
ProjectEventObject
| Mitglied | Typ | Pflicht | Hinweis |
|---|---|---|---|
object | string | ja | Immer project. |
id | string | ja | The projectId. |
externalProjectId | string | ja | |
projectId | string | ja |
ProjectDeleted
| Mitglied | Typ | Pflicht | Hinweis |
|---|---|---|---|
object | string | ja | Immer project. |
id | string | ja | |
deleted | boolean | ja | Immer true. |
Weiter lesen
REST-API: Länderprofile
Der Kern der API ist für jedes Land derselbe. Was je Land abweicht, steht in einem Profil. Deutschland ist das erste.
REST-API: Schreiben und Idempotenz
Inserate und Kontakte anlegen, ändern und löschen. Merge Patch, Idempotency-Key für sichere Wiederholungen, ETag und If-Match gegen Überschreiben.
REST-API Referenz
Jede Operation von /v1 mit Parametern, Antwort und Beispiel, aus dem Vertrag der API erzeugt.