---
title: "Interessenten & Leads"
url: "https://maklerportal.apim.eu/apis/interessenten/versions/b41f900a-058f-49ba-a5a3-a3864c83629f"
---

# Interessenten & Leads

OpenAPI specification document.

```json
{"openapi":"3.0.3","info":{"title":"Interessenten & Leads","version":"1.0.0","description":"Nimmt Anfragen zu Objekten entgegen, führt Suchprofile und gleicht beides\nautomatisch ab. Jede Anfrage bekommt eine nachvollziehbare Bewertung, damit\nknappe Besichtigungsplätze an die passenden Interessenten gehen.\n\nInteressentendaten sind personenbezogen. Jeder Datensatz trägt deshalb ein\n`aufbewahrung_bis`; nach Ablauf wird nächtlich anonymisiert. Ein Löschverlangen\nsetzen Sie über `POST /interessenten/{id}/loeschung` sofort um.\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":"Interessenten"},{"name":"Anfragen"},{"name":"Matching"}],"security":[{"apiKey":[]}],"paths":{"/interessenten":{"get":{"tags":["Interessenten"],"summary":"Interessenten auflisten","operationId":"interessentenAuflisten","parameters":[{"name":"suchprofil_aktiv","in":"query","schema":{"type":"boolean"}},{"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/Interessent"}},"seite":{"$ref":"#/components/schemas/Seite"}}}}}},"401":{"$ref":"#/components/responses/NichtAuthentifiziert"}}},"post":{"tags":["Interessenten"],"summary":"Interessent anlegen","operationId":"interessentAnlegen","security":[{"apiKey":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/InteressentAnlegen"},"example":{"vorname":"Anna","nachname":"Bergmann","email":"a.bergmann@example.org","telefon":"+49 40 1234567","einwilligung":{"zweck":"objektvermittlung","erteilt_am":"2026-08-18T10:22:00Z"},"suchprofil":{"typ":["wohnung"],"orte":["Hamburg"],"zimmer_min":3,"kaufpreis_max_eur":700000}}}}},"responses":{"201":{"description":"Angelegt","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Interessent"}}}},"400":{"$ref":"#/components/responses/Validierungsfehler"}}}},"/interessenten/{interessentId}":{"parameters":[{"name":"interessentId","in":"path","required":true,"schema":{"type":"string","example":"int_71ab"}}],"get":{"tags":["Interessenten"],"summary":"Interessent abrufen","operationId":"interessentAbrufen","responses":{"200":{"description":"Interessent","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Interessent"}}}},"404":{"$ref":"#/components/responses/NichtGefunden"}}}},"/interessenten/{interessentId}/loeschung":{"parameters":[{"name":"interessentId","in":"path","required":true,"schema":{"type":"string","example":"int_71ab"}}],"post":{"tags":["Interessenten"],"summary":"Löschung veranlassen","description":"Setzt ein Betroffenenrecht sofort um. Personenbezogene Felder werden\nunwiderruflich entfernt; steuerlich aufbewahrungspflichtige Vorgänge\nbleiben pseudonymisiert erhalten.\n","operationId":"interessentLoeschen","security":[{"apiKey":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["grund"],"properties":{"grund":{"type":"string","enum":["betroffenenrecht","frist_abgelaufen","doublette"]},"quelle":{"type":"string","example":"e-mail vom 2026-08-18"}}}}}},"responses":{"202":{"description":"Löschung eingeleitet","content":{"application/json":{"schema":{"type":"object","properties":{"interessent_id":{"type":"string"},"anonymisiert_am":{"type":"string","format":"date-time"}}}}}}}}},"/anfragen":{"get":{"tags":["Anfragen"],"summary":"Anfragen auflisten","operationId":"anfragenAuflisten","parameters":[{"name":"objekt_id","in":"query","schema":{"type":"string","example":"obj_8f2c1a"}},{"name":"status","in":"query","schema":{"$ref":"#/components/schemas/Anfragestatus"}}],"responses":{"200":{"description":"Trefferliste","content":{"application/json":{"schema":{"type":"object","properties":{"daten":{"type":"array","items":{"$ref":"#/components/schemas/Anfrage"}},"seite":{"$ref":"#/components/schemas/Seite"}}}}}}}},"post":{"tags":["Anfragen"],"summary":"Anfrage erfassen","description":"Typischerweise vom Kontaktformular der eigenen Website aufgerufen.","operationId":"anfrageErfassen","security":[{"apiKey":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["objekt_id","interessent_id"],"properties":{"objekt_id":{"type":"string","example":"obj_8f2c1a"},"interessent_id":{"type":"string","example":"int_71ab"},"nachricht":{"type":"string","maxLength":2000},"kanal":{"type":"string","enum":["website","portal","telefon","messe"]}}}}}},"responses":{"201":{"description":"Erfasst","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Anfrage"}}}}}}},"/anfragen/{anfrageId}/bewertung":{"parameters":[{"name":"anfrageId","in":"path","required":true,"schema":{"type":"string","example":"anf_5c02"}}],"get":{"tags":["Matching"],"summary":"Bewertung einer Anfrage abrufen","description":"Zeigt, wie gut Suchprofil und Objekt zusammenpassen – mit den einzelnen\nKriterien, damit die Einstufung nachvollziehbar bleibt.\n","operationId":"anfrageBewertungAbrufen","responses":{"200":{"description":"Bewertung","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Bewertung"},"example":{"anfrage_id":"anf_5c02","punkte":82,"einstufung":"hoch","kriterien":[{"kriterium":"kaufpreis","erfuellt":true,"gewicht":30},{"kriterium":"zimmeranzahl","erfuellt":true,"gewicht":25},{"kriterium":"lage","erfuellt":true,"gewicht":20},{"kriterium":"finanzierungsnachweis","erfuellt":false,"gewicht":25}]}}}}}}},"/matching/objekte/{objektId}":{"parameters":[{"name":"objektId","in":"path","required":true,"schema":{"type":"string","example":"obj_8f2c1a"}}],"get":{"tags":["Matching"],"summary":"Passende Interessenten zu einem Objekt","description":"Liefert Interessenten mit passendem Suchprofil, absteigend nach Punktzahl.","operationId":"matchingZuObjekt","parameters":[{"name":"mindestpunkte","in":"query","schema":{"type":"integer","minimum":0,"maximum":100,"default":60}}],"responses":{"200":{"description":"Treffer","content":{"application/json":{"schema":{"type":"object","properties":{"daten":{"type":"array","items":{"$ref":"#/components/schemas/Bewertung"}}}}}}}}}}},"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"}}}},"Anfragestatus":{"type":"string","enum":["neu","bewertet","eingeladen","abgesagt","abgeschlossen"],"example":"bewertet"},"Einwilligung":{"type":"object","description":"Nachweis der datenschutzrechtlichen Einwilligung.","required":["zweck","erteilt_am"],"properties":{"zweck":{"type":"string","enum":["objektvermittlung","newsletter"]},"erteilt_am":{"type":"string","format":"date-time","example":"2026-08-18T10:22:00Z"},"widerrufen_am":{"type":"string","format":"date-time","nullable":true,"example":null}}},"Suchprofil":{"type":"object","properties":{"typ":{"type":"array","items":{"type":"string","enum":["wohnung","haus","grundstueck","gewerbe"]}},"orte":{"type":"array","items":{"type":"string","example":"Hamburg"}},"zimmer_min":{"type":"number","format":"float","example":3},"wohnflaeche_min_qm":{"type":"number","format":"float","example":75},"kaufpreis_max_eur":{"type":"integer","example":700000},"kaltmiete_max_eur":{"type":"integer","example":1600},"finanzierungsnachweis":{"type":"boolean","example":false}}},"InteressentAnlegen":{"type":"object","required":["nachname","email","einwilligung"],"properties":{"vorname":{"type":"string","example":"Anna"},"nachname":{"type":"string","example":"Bergmann"},"email":{"type":"string","format":"email","example":"a.bergmann@example.org"},"telefon":{"type":"string","example":"+49 40 1234567"},"einwilligung":{"$ref":"#/components/schemas/Einwilligung"},"suchprofil":{"$ref":"#/components/schemas/Suchprofil"}}},"Interessent":{"allOf":[{"$ref":"#/components/schemas/InteressentAnlegen"},{"type":"object","properties":{"id":{"type":"string","example":"int_71ab"},"aufbewahrung_bis":{"type":"string","format":"date","description":"Automatisch gesetzte Löschfrist. Danach wird anonymisiert.","example":"2027-02-18"},"angelegt_am":{"type":"string","format":"date-time","example":"2026-08-18T10:22:04Z"}}}]},"Anfrage":{"type":"object","properties":{"id":{"type":"string","example":"anf_5c02"},"objekt_id":{"type":"string","example":"obj_8f2c1a"},"interessent_id":{"type":"string","example":"int_71ab"},"status":{"$ref":"#/components/schemas/Anfragestatus"},"kanal":{"type":"string","example":"website"},"nachricht":{"type":"string","example":"Guten Tag, ist die Wohnung noch verfügbar? Wir würden sie gern besichtigen."},"eingegangen_am":{"type":"string","format":"date-time","example":"2026-08-19T17:05:31Z"}}},"Kriterium":{"type":"object","properties":{"kriterium":{"type":"string","example":"kaufpreis"},"erfuellt":{"type":"boolean","example":true},"gewicht":{"type":"integer","example":30}}},"Bewertung":{"type":"object","properties":{"anfrage_id":{"type":"string","example":"anf_5c02"},"interessent_id":{"type":"string","example":"int_71ab"},"punkte":{"type":"integer","minimum":0,"maximum":100,"example":82},"einstufung":{"type":"string","enum":["niedrig","mittel","hoch"]},"kriterien":{"type":"array","items":{"$ref":"#/components/schemas/Kriterium"}}}}}}}
```