---
title: "Objektverwaltung"
url: "https://maklerportal.apim.eu/apis/objektverwaltung/versions/725feb93-ed74-4ebf-862d-00afd038d14d"
---

# Objektverwaltung

OpenAPI specification document.

```json
{"openapi":"3.0.3","info":{"title":"Objektverwaltung","version":"1.0.0","description":"Das führende Datenmodell für alle vermarkteten Objekte – Wohnungen, Häuser und\nGewerbeflächen. Objekte sind die Grundlage für Exposés, Matching und Bewertung.\n\nDer Bestand lässt sich über **OpenImmo** befüllen und exportieren, sodass\nbestehende Maklersoftware ohne Zwischenschritt angebunden werden kann.\n","contact":{"name":"API-Support Objektwerk GmbH","email":"api-support@objektwerk.example"}},"servers":[{"url":"https://api.maklerportal.example/v1","description":"Produktion"},{"url":"https://sandbox.api.maklerportal.example/v1","description":"Sandbox"}],"tags":[{"name":"Objekte"},{"name":"Medien"},{"name":"Import"}],"security":[{"apiKey":[]}],"paths":{"/objekte":{"get":{"tags":["Objekte"],"summary":"Objekte auflisten","operationId":"objekteAuflisten","parameters":[{"name":"status","in":"query","schema":{"$ref":"#/components/schemas/ObjektStatus"}},{"name":"typ","in":"query","schema":{"$ref":"#/components/schemas/Objekttyp"}},{"name":"plz","in":"query","description":"Filter auf die Postleitzahl.","schema":{"type":"string","example":"20251"}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":25}},{"name":"cursor","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"Trefferliste","content":{"application/json":{"schema":{"type":"object","properties":{"daten":{"type":"array","items":{"$ref":"#/components/schemas/Objekt"}},"seite":{"$ref":"#/components/schemas/Seite"}}}}}},"401":{"$ref":"#/components/responses/NichtAuthentifiziert"},"429":{"$ref":"#/components/responses/ZuVieleAnfragen"}}},"post":{"tags":["Objekte"],"summary":"Objekt anlegen","operationId":"objektAnlegen","security":[{"apiKey":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ObjektAnlegen"},"example":{"typ":"wohnung","titel":"3-Zimmer-Altbau am Falkenried","adresse":{"strasse":"Falkenried 42","plz":"20251","ort":"Hamburg"},"wohnflaeche_qm":86.5,"zimmer":3,"baujahr":1908,"kaufpreis_eur":645000,"provision":{"kaeufer_prozent":3.57,"verkaeufer_prozent":3.57}}}}},"responses":{"201":{"description":"Angelegt","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Objekt"}}}},"400":{"$ref":"#/components/responses/Validierungsfehler"},"401":{"$ref":"#/components/responses/NichtAuthentifiziert"}}}},"/objekte/{objektId}":{"parameters":[{"name":"objektId","in":"path","required":true,"schema":{"type":"string","example":"obj_8f2c1a"}}],"get":{"tags":["Objekte"],"summary":"Objekt abrufen","operationId":"objektAbrufen","responses":{"200":{"description":"Objekt","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Objekt"}}}},"404":{"$ref":"#/components/responses/NichtGefunden"}}},"patch":{"tags":["Objekte"],"summary":"Objekt ändern","description":"Ändert einzelne Felder. Bereits erzeugte Exposés bleiben unverändert.","operationId":"objektAendern","security":[{"apiKey":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ObjektAnlegen"},"example":{"kaufpreis_eur":629000}}}},"responses":{"200":{"description":"Geändert","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Objekt"}}}},"404":{"$ref":"#/components/responses/NichtGefunden"}}},"delete":{"tags":["Objekte"],"summary":"Objekt archivieren","description":"Nimmt das Objekt aus der Vermarktung. Der Datensatz bleibt lesbar.","operationId":"objektArchivieren","security":[{"apiKey":[]}],"responses":{"204":{"description":"Archiviert"},"404":{"$ref":"#/components/responses/NichtGefunden"}}}},"/objekte/{objektId}/medien":{"parameters":[{"name":"objektId","in":"path","required":true,"schema":{"type":"string","example":"obj_8f2c1a"}}],"get":{"tags":["Medien"],"summary":"Medien eines Objekts auflisten","operationId":"medienAuflisten","responses":{"200":{"description":"Medienliste","content":{"application/json":{"schema":{"type":"object","properties":{"daten":{"type":"array","items":{"$ref":"#/components/schemas/Medium"}}}}}}}}},"post":{"tags":["Medien"],"summary":"Medium hochladen","description":"Bilder, Grundrisse und Dokumente werden dem Objekt zugeordnet, nicht dem Exposé.","operationId":"mediumHochladen","security":[{"apiKey":[]}],"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","required":["datei","kategorie"],"properties":{"datei":{"type":"string","format":"binary"},"kategorie":{"$ref":"#/components/schemas/Medienkategorie"},"reihenfolge":{"type":"integer","minimum":1,"example":1},"bildunterschrift":{"type":"string","maxLength":160}}}}}},"responses":{"201":{"description":"Hochgeladen","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Medium"}}}},"413":{"description":"Datei zu groß (Grenze 25 MB)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Fehler"}}}}}}},"/import/openimmo":{"post":{"tags":["Import"],"summary":"OpenImmo-Datei importieren","description":"Nimmt eine OpenImmo-XML-Datei oder ein ZIP mit Bildern entgegen und legt die\nenthaltenen Objekte an bzw. aktualisiert sie. Der Import läuft asynchron.\n","operationId":"openimmoImportieren","security":[{"apiKey":[]}],"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","required":["datei"],"properties":{"datei":{"type":"string","format":"binary"},"modus":{"type":"string","enum":["ergaenzen","ersetzen"],"default":"ergaenzen","description":"`ersetzen` archiviert Objekte, die nicht in der Datei stehen."}}}}}},"responses":{"202":{"description":"Import angenommen","content":{"application/json":{"schema":{"type":"object","properties":{"import_id":{"type":"string","example":"imp_2f71"},"status":{"type":"string","enum":["in_arbeit","fertig","fehlgeschlagen"]},"objekte_erkannt":{"type":"integer","example":47}}}}}}}}}},"components":{"securitySchemes":{"apiKey":{"type":"apiKey","in":"header","name":"apikey","description":"Jeder Aufruf trägt einen API-Schlüssel im Header `apikey`. Den Schlüssel\nerzeugen Sie im Maklerportal unter \"Meine Anwendungen\"; er wird genau einmal\nangezeigt.\n\nAn jedem Schlüssel hängen die Scopes, die er nutzen darf. Fehlt einer,\nantwortet die API mit `403` und `code: \"scope_fehlt\"`; der fehlende Scope\nsteht in `details[].feld`.\n"}},"responses":{"NichtAuthentifiziert":{"description":"Schlüssel fehlt, ist gesperrt oder ungültig","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Fehler"}}}},"NichtGefunden":{"description":"Datensatz nicht gefunden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Fehler"}}}},"Validierungsfehler":{"description":"Die Anfrage entspricht nicht dem Schema","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Fehler"}}}},"ZuVieleAnfragen":{"description":"Rate Limit erreicht","headers":{"Retry-After":{"schema":{"type":"integer","example":12}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Fehler"}}}}},"schemas":{"Seite":{"type":"object","description":"Cursor-basierte Paginierung.","properties":{"anzahl":{"type":"integer","example":25},"gesamt":{"type":"integer","example":138},"cursor_naechste":{"type":"string","nullable":true,"example":"eyJzIjoyNX0"}}},"Fehlerdetail":{"type":"object","properties":{"feld":{"type":"string","example":"energieausweis.endenergiebedarf_kwh"},"grund":{"type":"string","example":"fehlt"}}},"Fehler":{"type":"object","description":"Einheitliches Fehlerformat aller Maklerportal-APIs.","required":["code","nachricht"],"properties":{"code":{"type":"string","example":"validierung_fehlgeschlagen"},"nachricht":{"type":"string","example":"Für die Veröffentlichung fehlen Pflichtangaben aus dem Energieausweis."},"details":{"type":"array","items":{"$ref":"#/components/schemas/Fehlerdetail"}}}},"ObjektStatus":{"type":"string","enum":["entwurf","aktiv","reserviert","verkauft","vermietet","archiviert"],"example":"aktiv"},"Objekttyp":{"type":"string","enum":["wohnung","haus","grundstueck","gewerbe","stellplatz"],"example":"wohnung"},"Medienkategorie":{"type":"string","enum":["titelbild","innenansicht","aussenansicht","grundriss","energieausweis","dokument"]},"Adresse":{"type":"object","required":["plz","ort"],"properties":{"strasse":{"type":"string","example":"Falkenried 42"},"plz":{"type":"string","pattern":"^[0-9]{5}$","example":"20251"},"ort":{"type":"string","example":"Hamburg"},"land":{"type":"string","default":"DE"},"lage_genauigkeit":{"type":"string","description":"Steuert, wie genau die Adresse im Exposé erscheint.","enum":["exakt","strasse","stadtteil"],"default":"strasse"}}},"Energieausweis":{"type":"object","description":"Kennwerte, die für die Veröffentlichung eines Exposés benötigt werden.","properties":{"art":{"type":"string","enum":["verbrauchsausweis","bedarfsausweis"]},"endenergiebedarf_kwh":{"type":"number","format":"float","example":118.4},"energietraeger":{"type":"string","example":"fernwaerme"},"baujahr_anlage":{"type":"integer","example":1998},"effizienzklasse":{"type":"string","enum":["A+","A","B","C","D","E","F","G","H"]},"gueltig_bis":{"type":"string","format":"date","example":"2031-04-30"},"befreiung":{"type":"string","description":"Gesetzt, wenn keine Ausweispflicht besteht.","enum":["denkmalschutz","kleingebaeude"]}}},"Provision":{"type":"object","properties":{"kaeufer_prozent":{"type":"number","format":"float","example":3.57},"verkaeufer_prozent":{"type":"number","format":"float","example":3.57},"hinweis":{"type":"string","example":"inkl. gesetzlicher Umsatzsteuer"}}},"ObjektAnlegen":{"type":"object","required":["typ","titel","adresse"],"properties":{"typ":{"$ref":"#/components/schemas/Objekttyp"},"titel":{"type":"string","maxLength":120,"example":"3-Zimmer-Altbau am Falkenried"},"beschreibung":{"type":"string","example":"Gepflegte Altbauwohnung im zweiten Obergeschoss mit zwei Südbalkonen."},"adresse":{"$ref":"#/components/schemas/Adresse"},"wohnflaeche_qm":{"type":"number","format":"float","example":86.5},"grundstuecksflaeche_qm":{"type":"number","format":"float","example":412},"zimmer":{"type":"number","format":"float","example":3},"baujahr":{"type":"integer","example":1908},"etage":{"type":"integer","example":2},"kaufpreis_eur":{"type":"integer","example":645000},"kaltmiete_eur":{"type":"integer","example":1450},"nebenkosten_eur":{"type":"integer","example":280},"verfuegbar_ab":{"type":"string","format":"date","example":"2026-11-01"},"energieausweis":{"$ref":"#/components/schemas/Energieausweis"},"provision":{"$ref":"#/components/schemas/Provision"}}},"Objekt":{"allOf":[{"$ref":"#/components/schemas/ObjektAnlegen"},{"type":"object","properties":{"id":{"type":"string","example":"obj_8f2c1a"},"status":{"$ref":"#/components/schemas/ObjektStatus"},"medien_anzahl":{"type":"integer","example":14},"angelegt_am":{"type":"string","format":"date-time","example":"2026-08-14T08:12:44Z"},"geaendert_am":{"type":"string","format":"date-time","example":"2026-08-20T09:38:02Z"}}}]},"Medium":{"type":"object","properties":{"id":{"type":"string","example":"med_31c9"},"kategorie":{"$ref":"#/components/schemas/Medienkategorie"},"url":{"type":"string","format":"uri","example":"https://cdn.maklerportal.example/objekte/obj_8f2c1a/med_31c9.jpg"},"reihenfolge":{"type":"integer","example":1},"bildunterschrift":{"type":"string","example":"Wohnzimmer mit Blick auf den Innenhof"},"groesse_byte":{"type":"integer","example":2418112}}}}}}
```