AthausDoku

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:

TeilInhalt
datadie Immobilie: Typ, Lage, Preise, Flächen, Zustand, Energie, Ausstattung, Texte, Verwaltung
metadatawoher das Inserat kommt: deine Ids unter source
contactdie zuständige Person des Inserats (Die zuständige Person)
mediadie Fotos und Dokumente, benannt über externalMediaId (Fotos und Dokumente)
userDefinedder 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

IdWessenWo
externalListingIddeineim Pfad jedes Aufrufs; sie ist metadata.source.offererMarketingKey
listingIdunserein 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, staircase und entrance ist allein die Adresse der Schlüssel, wie bisher: Ein zweites Inserat an derselben Adresse ist 409 address_already_exists. Das schützt vor Doppelten, wenn eine Anbindung ohne ihren Key wiederholt.
  • Das 409 nennt das Inserat deines eigenen Büros, das die Adresse und Wohnung hält, mit externalListingId und listingId. Es gibt zwei Auswege: dieses Inserat ändern oder eine unit schicken, die beide unterscheidet.
  • Ein PATCH, der ein Inserat auf eine vergebene Wohnung verschiebt, ist dasselbe 409. Wohnung, Treppenhaus oder Eingang eines laufenden Inserats zu leeren ist 409 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}/publish stellt 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 Scope approve und steht die Automatik des Büros für das Veröffentlichen auf "Automatisch", antwortet der Aufruf 200 mit dem Inserat, status ist active. Sonst antwortet er 202 mit einem Vorschlag, den eine Person in der App bestätigt (Was das Büro verlässt). Idempotency-Key ist Pflicht. Ein unvollständiges Inserat ist 409 listing_incomplete, errors nennt, was fehlt.
  • POST /v1/listings/{externalListingId}/unpublish nimmt ein laufendes Inserat sofort vom Markt und antwortet 200, status ist paused. Zurücknehmen entfernt nur, darum wartet es auf niemanden. Läuft das Inserat nicht, ist es 409 listing_not_online.
  • POST /v1/listings/{externalListingId}/unit-status setzt den Stand eines Inserats, das eine Einheit eines Neubauprojekts ist, und antwortet 200 mit dem Inserat. Es steht bei den Projekten. projectId im 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 (oder draft=true) und ändert das Inserat dann wie PATCH: Was der Rumpf nicht nennt, bleibt, null leert es. Bei einer unbekannten Id antwortet PUT mit 404. Mit createIfMissing=true legt Athaus das Inserat stattdessen an, so kann ein Sender immer PUT schicken.
  • PATCH /v1/listings/{externalListingId} ändert Teile als Merge Patch (RFC 7396): Ein Mitglied, das du schickst, ersetzt das gespeicherte, null entfernt es, eine Liste wird ganz ersetzt. Das Ergebnis muss weiter ein gültiges Inserat sein. OpenImmo kennt kein PATCH, das ist eine Ergänzung.
  • DELETE /v1/listings/{externalListingId} entfernt das Inserat und antwortet 202. 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:

TypBedeutung
FIELD_IGNOREDein 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:

NameTypInhalt
location.districtstringder Stadtteil oder das Viertel
tenurestringEigentum, Erbbaurecht, Wohnungseigentum oder Genossenschaft (englisch: freehold, leasehold, commonhold, cooperative)
price.depositdecimaldie Mietkaution
price.associationFeedecimaldas monatliche Hausgeld an die Eigentümergemeinschaft
conditions.interiorQualitystringBASIC, STANDARD, UPSCALE oder LUXURY
management.petsPolicystringALLOWED, NOT_ALLOWED oder CASE_BY_CASE
management.usagestringfreier Text zur Nutzung
structure.parkingSpacesintegerdie 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:

ParameterBedeutung
kindphoto, floor_plan oder document. Ohne Angabe ist ein Bild ein photo und eine PDF ein document. Ein photo muss ein Bild sein.
documentTypebei 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
fileNameder Name, unter dem die Datei in der App und im Download steht
externalMediaIddeine 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.jpg

Die 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 sendestWirkung
kein mediadie Dateien bleiben, wie sie sind
eine Listegenannte 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

MitgliedTypPflichtHinweis
dataobject | anynein
metadataobject | anynein
userDefinedobject[] | anynein
mediaobject[] | anynein
contactobject | anynein

ListingEnergy

MitgliedTypPflichtHinweis
energyTypeobjectnein
energyType.heatMethodstringneinEines von CENTRAL, INDIVIDUAL, STOREY.
energyType.heatFormobjectnein
energyType.heatForm.airbooleannein
energyType.heatForm.radiatorbooleannein
energyType.heatForm.stovebooleannein
energyType.heatForm.underfloorbooleannein
energyType.heatForm.wallCeilingbooleannein
energyType.energySourceobjectnein
energyType.energySource.coalbooleannein
energyType.energySource.districtHeatingbooleannein
energyType.energySource.electricbooleannein
energyType.energySource.gasbooleannein
energyType.energySource.geothermalbooleannein
energyType.energySource.liquidGasbooleannein
energyType.energySource.oilbooleannein
energyType.energySource.solarHeatbooleannein
energyType.energySource.solarPowerbooleannein
energyType.energySource.windbooleannein
energyType.energySource.woodbooleannein
energyType.energySource.woodPelletbooleannein
energyType.energyGenerationobjectnein
energyType.energyGeneration.fossilburningbooleannein
energyType.energyGeneration.heatpumpbooleannein
energyType.energyGeneration.combinedHeatAndPowerPlantbooleannein
energyType.maxElectricalPowerintegernein-9007199254740991 bis 9007199254740991.
countrySpecificobjectnein
countrySpecific.deobjectnein
countrySpecific.de.energyCertificatesobject[]nein
countrySpecific.de.energyCertificates[].nameOfCertificatestringnein
countrySpecific.de.energyCertificates[].certificateTypestringneinEines von ENEV2008, ENEV2014, ENEV2026, NOT_AVAILABLE, NOT_NECESSARY, AT_VISIT.
countrySpecific.de.energyCertificates[].certificateBasedOnstringneinEines von NEED, CONSUMPTION.
countrySpecific.de.energyCertificates[].isResidentialBuildingbooleannein
countrySpecific.de.energyCertificates[].primaryEnergySourcestringneinEines von NO_INFORMATION, SOLAR, WIND, COAL, GAS, OIL, WOOD, DISTRICT_HEATING, ELECTRICITY.
countrySpecific.de.energyCertificates[].efficiencyClassstringneinEines von A_PLUS, A, B, C, D, E, F, G, H.
countrySpecific.de.energyCertificates[].releaseDatestring (date)nein
countrySpecific.de.energyCertificates[].validUntilstring (date)nein
countrySpecific.de.energyCertificates[].yearOfConstructionBuildingintegernein-9007199254740991 bis 9007199254740991.
countrySpecific.de.energyCertificates[].yearOfConstructionHeatingintegernein-9007199254740991 bis 9007199254740991.
countrySpecific.de.energyCertificates[].overallEnergyNeednumbernein
countrySpecific.de.energyCertificates[].primaryEnergyNeednumbernein
countrySpecific.de.energyCertificates[].electricityNeednumbernein
countrySpecific.de.energyCertificates[].heatingNeednumbernein
countrySpecific.de.energyCertificates[].overallEnergyConsumptionnumbernein
countrySpecific.de.energyCertificates[].primaryEnergyConsumptionnumbernein
countrySpecific.de.energyCertificates[].isWaterHeatingIncludedbooleannein
countrySpecific.de.energyCertificates[].electricityConsumptionnumbernein
countrySpecific.de.energyCertificates[].heatingConsumptionnumbernein
countrySpecific.de.energyCertificates[].energyConsumptionIndicatornumbernein
countrySpecific.de.houseEnergyStandardTypestringneinEines 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.primaryEnergySourcestringnein

Projekte

Ein Projekt hat diese Mitglieder; die Einheiten eines Projekts sind Inserate.

ProjectEventObject

MitgliedTypPflichtHinweis
objectstringjaImmer project.
idstringjaThe projectId.
externalProjectIdstringja
projectIdstringja

ProjectDeleted

MitgliedTypPflichtHinweis
objectstringjaImmer project.
idstringja
deletedbooleanjaImmer true.

Weiter lesen

Auf dieser Seite