---
title: "Besichtigungstermine"
url: "https://maklerportal.apim.eu/apis/besichtigungstermine/versions/b8696a0c-e900-480e-9ce8-7b7f1517d03d"
---

# Besichtigungstermine

OpenAPI specification document.

```json
{"openapi":"3.0.3","info":{"title":"Besichtigungstermine","version":"1.0.0","description":"Plant Einzel- und Sammelbesichtigungen, verwaltet Zu- und Absagen und sammelt\nRückmeldungen nach dem Termin ein.\n\nDie API kennt zwei Modelle: **feste Termine**, zu denen Sie einladen, und\n**Verfügbarkeitsfenster**, aus denen Interessenten selbst einen Platz wählen.\nBeides lässt sich pro Objekt mischen.\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":"Termine"},{"name":"Verfügbarkeiten"},{"name":"Rückmeldungen"}],"security":[{"apiKey":[]}],"paths":{"/termine":{"get":{"tags":["Termine"],"summary":"Termine auflisten","operationId":"termineAuflisten","parameters":[{"name":"objekt_id","in":"query","schema":{"type":"string","example":"obj_8f2c1a"}},{"name":"von","in":"query","schema":{"type":"string","format":"date-time"}},{"name":"bis","in":"query","schema":{"type":"string","format":"date-time"}},{"name":"status","in":"query","schema":{"$ref":"#/components/schemas/Terminstatus"}}],"responses":{"200":{"description":"Trefferliste","content":{"application/json":{"schema":{"type":"object","properties":{"daten":{"type":"array","items":{"$ref":"#/components/schemas/Termin"}},"seite":{"$ref":"#/components/schemas/Seite"}}}}}},"401":{"$ref":"#/components/responses/NichtAuthentifiziert"}}},"post":{"tags":["Termine"],"summary":"Termin anlegen","operationId":"terminAnlegen","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TerminAnlegen"},"examples":{"einzel":{"summary":"Einzelbesichtigung","value":{"objekt_id":"obj_8f2c1a","art":"einzel","beginn":"2026-09-03T16:00:00+02:00","dauer_minuten":30,"treffpunkt":"Vor dem Hauseingang, Falkenried 42"}},"sammel":{"summary":"Sammelbesichtigung mit zwölf Plätzen","value":{"objekt_id":"obj_8f2c1a","art":"sammel","beginn":"2026-09-05T11:00:00+02:00","dauer_minuten":60,"plaetze":12}}}}}},"responses":{"201":{"description":"Angelegt","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Termin"}}}},"400":{"$ref":"#/components/responses/Validierungsfehler"},"409":{"description":"Zeitliche Überschneidung mit einem bestehenden Termin","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Fehler"},"example":{"code":"konflikt","nachricht":"Zu dieser Zeit besteht bereits ein Termin für das Objekt.","details":[{"feld":"beginn","grund":"ueberschneidung"}]}}}}}}},"/termine/{terminId}":{"parameters":[{"name":"terminId","in":"path","required":true,"schema":{"type":"string","example":"trm_9a44"}}],"get":{"tags":["Termine"],"summary":"Termin abrufen","operationId":"terminAbrufen","responses":{"200":{"description":"Termin","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Termin"}}}},"404":{"$ref":"#/components/responses/NichtGefunden"}}},"patch":{"tags":["Termine"],"summary":"Termin verschieben oder ändern","description":"Bei geändertem Beginn werden alle Zusagen automatisch benachrichtigt.","operationId":"terminAendern","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TerminAnlegen"},"example":{"beginn":"2026-09-03T17:30:00+02:00"}}}},"responses":{"200":{"description":"Geändert","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Termin"}}}},"404":{"$ref":"#/components/responses/NichtGefunden"}}},"delete":{"tags":["Termine"],"summary":"Termin absagen","operationId":"terminAbsagen","responses":{"204":{"description":"Abgesagt","Teilnehmer wurden benachrichtigt":null},"404":{"$ref":"#/components/responses/NichtGefunden"}}}},"/termine/{terminId}/zusagen":{"parameters":[{"name":"terminId","in":"path","required":true,"schema":{"type":"string","example":"trm_9a44"}}],"get":{"tags":["Termine"],"summary":"Zusagen zu einem Termin auflisten","operationId":"zusagenAuflisten","responses":{"200":{"description":"Teilnehmerliste","content":{"application/json":{"schema":{"type":"object","properties":{"daten":{"type":"array","items":{"$ref":"#/components/schemas/Zusage"}},"freie_plaetze":{"type":"integer","example":4}}}}}}}},"post":{"tags":["Termine"],"summary":"Interessent zusagen lassen","description":"Ist der Termin ausgebucht, wandert der Interessent auf die Warteliste.","operationId":"zusageAnlegen","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["interessent_id"],"properties":{"interessent_id":{"type":"string","example":"int_71ab"},"begleitpersonen":{"type":"integer","minimum":0,"maximum":3,"default":0}}}}}},"responses":{"201":{"description":"Zusage erfasst","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Zusage"}}}},"409":{"description":"Interessent hat bereits zugesagt","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Fehler"}}}}}}},"/verfuegbarkeiten":{"get":{"tags":["Verfügbarkeiten"],"summary":"Freie Zeitfenster abfragen","description":"Liefert buchbare Fenster für ein Objekt. Grundlage sind die hinterlegten\nArbeitszeiten des zuständigen Maklers abzüglich bereits belegter Termine.\n","operationId":"verfuegbarkeitenAbfragen","parameters":[{"name":"objekt_id","in":"query","required":true,"schema":{"type":"string","example":"obj_8f2c1a"}},{"name":"von","in":"query","required":true,"schema":{"type":"string","format":"date"}},{"name":"bis","in":"query","required":true,"schema":{"type":"string","format":"date"}}],"responses":{"200":{"description":"Zeitfenster","content":{"application/json":{"schema":{"type":"object","properties":{"daten":{"type":"array","items":{"$ref":"#/components/schemas/Zeitfenster"}}}},"example":{"daten":[{"beginn":"2026-09-03T16:00:00+02:00","ende":"2026-09-03T16:30:00+02:00","buchbar":true},{"beginn":"2026-09-03T16:30:00+02:00","ende":"2026-09-03T17:00:00+02:00","buchbar":false}]}}}}}}},"/termine/{terminId}/rueckmeldung":{"parameters":[{"name":"terminId","in":"path","required":true,"schema":{"type":"string","example":"trm_9a44"}}],"post":{"tags":["Rückmeldungen"],"summary":"Rückmeldung nach der Besichtigung erfassen","description":"Grundlage für die Rückmeldung an die Eigentümerseite.","operationId":"rueckmeldungErfassen","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["interessent_id","interesse"],"properties":{"interessent_id":{"type":"string","example":"int_71ab"},"interesse":{"type":"string","enum":["kaufabsicht","weiter_pruefen","kein_interesse"]},"preiseinschaetzung":{"type":"string","enum":["angemessen","zu_hoch","zu_niedrig"]},"bemerkung":{"type":"string","maxLength":1000}}}}}},"responses":{"201":{"description":"Erfasst","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Rueckmeldung"}}}}}}}},"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"}}}},"Terminstatus":{"type":"string","enum":["geplant","bestaetigt","durchgefuehrt","abgesagt"],"example":"bestaetigt"},"Terminart":{"type":"string","enum":["einzel","sammel","digital"],"example":"einzel"},"TerminAnlegen":{"type":"object","required":["objekt_id","art","beginn"],"properties":{"objekt_id":{"type":"string","example":"obj_8f2c1a"},"art":{"$ref":"#/components/schemas/Terminart"},"beginn":{"type":"string","format":"date-time","example":"2026-09-03T16:00:00+02:00"},"dauer_minuten":{"type":"integer","minimum":10,"maximum":240,"default":30},"plaetze":{"type":"integer","minimum":1,"description":"Nur bei `art: sammel` auszuwerten.","example":12},"treffpunkt":{"type":"string","maxLength":200,"example":"Vor dem Hauseingang, Falkenried 42"},"hinweis":{"type":"string","maxLength":500,"example":"Bitte Ausweis mitbringen, die Wohnung ist bewohnt."}}},"Termin":{"allOf":[{"$ref":"#/components/schemas/TerminAnlegen"},{"type":"object","properties":{"id":{"type":"string","example":"trm_9a44"},"status":{"$ref":"#/components/schemas/Terminstatus"},"zusagen_anzahl":{"type":"integer","example":8},"warteliste_anzahl":{"type":"integer","example":2},"angelegt_am":{"type":"string","format":"date-time","example":"2026-08-20T11:02:10Z"}}}]},"Zusage":{"type":"object","properties":{"id":{"type":"string","example":"zsg_1f7c"},"termin_id":{"type":"string","example":"trm_9a44"},"interessent_id":{"type":"string","example":"int_71ab"},"zustand":{"type":"string","enum":["zugesagt","warteliste","abgesagt","erschienen","nicht_erschienen"]},"begleitpersonen":{"type":"integer","example":1},"zugesagt_am":{"type":"string","format":"date-time","example":"2026-08-21T09:14:00Z"}}},"Zeitfenster":{"type":"object","properties":{"beginn":{"type":"string","format":"date-time","example":"2026-09-03T16:00:00+02:00"},"ende":{"type":"string","format":"date-time","example":"2026-09-03T16:30:00+02:00"},"buchbar":{"type":"boolean","example":true}}},"Rueckmeldung":{"type":"object","properties":{"id":{"type":"string","example":"rkm_60d2"},"termin_id":{"type":"string","example":"trm_9a44"},"interessent_id":{"type":"string","example":"int_71ab"},"interesse":{"type":"string","example":"weiter_pruefen"},"preiseinschaetzung":{"type":"string","example":"zu_hoch"},"bemerkung":{"type":"string","example":"Grundriss passt, Preis liegt oberhalb der eigenen Vorstellung."},"erfasst_am":{"type":"string","format":"date-time","example":"2026-09-03T17:12:00Z"}}}}}}
```