Mit der ImmoScout24 API veröffentlichen Sie Angebote automatisch, indem Ihre Software das Objekt per REST-Aufruf anlegt, Bilder als eigene Anhänge hochlädt und das Objekt anschließend im Kanal 10000 veröffentlicht. Voraussetzung sind ein Geschäftskonto bei ImmobilienScout24, ein API-Schlüssel und die Freigabe per OAuth 1.0a. Ein Dateiimport per FTP ist dafür nicht vorgesehen: ImmobilienScout24 nimmt Objektdaten laut eigener FAQ ausschließlich über die REST-API an.
Was die ImmoScout24 API für Anbieter ist
ImmobilienScout24 bietet mehrere Schnittstellen an, etwa für die Suche, für Geodaten oder für die Baufinanzierung. Für Anbieter zählt vor allem die Import/Export API. Mit ihr legen Sie Objekte an, ändern und löschen sie, veröffentlichen sie und rufen Auswertungen zu veröffentlichten Objekten ab. In den Nutzungsbedingungen heißt dieser Teil Real Estate Listing API.
Wichtig für das Verständnis: Das Objekt selbst enthält nur die Objektdaten. Kontaktperson, Bilder und Dokumente sowie die Veröffentlichung sind eigene Ressourcen mit eigenen Endpunkten. Ein Angebot entsteht also nicht in einem einzigen Aufruf, sondern in einer kleinen Abfolge von Schritten. Wer das einmal verstanden hat, versteht auch die meisten Fehlermeldungen.
Wenn Sie zusätzlich andere Portale per OpenImmo beliefern, lohnt der Blick auf unseren Vergleich OpenImmo-Schnittstelle und ImmoScout24-API. Dieser Beitrag geht einen Schritt weiter und zeigt den Ablauf bei ImmobilienScout24 selbst.
Voraussetzungen vor dem ersten Aufruf
Bevor ein einziges Angebot automatisch erscheint, sind ein paar organisatorische Dinge zu klären. Die folgende Übersicht fasst zusammen, was die Entwicklerdokumentation von ImmobilienScout24 verlangt (Stand der Prüfung: 27. Oktober 2026).
| Voraussetzung | Was die Dokumentation sagt |
|---|---|
| Konto | Ein privates Konto reicht nicht. Für den API-Zugang ist ein Geschäftskonto nötig (Client Credentials). |
| API-Schlüssel | Schlüssel und Secret gibt es für Sandbox, Produktion oder beides. Sie werden nur einmal angezeigt. Mit dem Anwendungsfall Kundenwebsite / Immobilienverwaltungssoftware erhält der Schlüssel die Rechte, eigene Objekte zu senden und abzurufen. |
| Anmeldung | OAuth 1.0a. Für Objekte eines Nutzers ist der dreibeinige Ablauf nötig, und jedes Access Token gehört zu genau einem Nutzer (Three Legged OAuth). |
| Testumgebung | Die Sandbox ist ein Klon der Produktion mit eigener, anonymer Datenbank. Es finden keine Buchungen statt und es werden keine E-Mails verschickt. |
| Kosten | Die Nutzung der Live-API ist kostenpflichtig. Die monatliche Vergütung richtet sich nach dem Durchschnitt der API-Aufrufe der letzten drei Monate laut Preisliste, zuzüglich Mehrwertsteuer (Nutzungsbedingungen, Punkt 3). |
| Kontingent | Für die automatische Veröffentlichung braucht das Kundenkonto ein Kontingent. Fehlt es, meldet die API No contingent available (FAQ für CRM-Nutzer). |
Ein Hinweis zur Sandbox: ImmobilienScout24 spielt dort jede Woche den neuesten Stand ein und weist darauf hin, dass Testdaten und sogar der Sandbox-Schlüssel dabei verloren gehen können. Planen Sie Ihre Tests so, dass sie sich jederzeit neu aufsetzen lassen.
Der Ablauf: vom Objekt zum Live-Angebot
Das Tutorial zur Objekteinstellung beschreibt die Reihenfolge. Sinngemäß sind es vier Schritte:
- Objekt anlegen. Ein POST auf /offer/v1.0/user/me/realestate mit Objektart (zum Beispiel apartmentRent oder apartmentBuy), Titel, Adresse, Preis und Fläche. Die Antwort enthält die Scout-Objekt-ID. Über das Feld externalId (bis 50 Zeichen) hinterlegen Sie Ihre eigene Objektnummer und können das Objekt später mit dem Präfix ext- ansprechen.
- Bilder und Dokumente hochladen. Jeder Anhang ist ein eigener Multipart-Aufruf auf das bereits angelegte Objekt. Objekt und Anhang lassen sich nicht in einem Aufruf anlegen (Insert an attachment).
- Kontakt zuordnen. Optional verweisen Sie auf eine Kontaktperson, die Sie über die Kontakt-Ressource anlegen. Ohne Angabe verwendet ImmobilienScout24 die Standardkontaktadresse des Anbieters.
- Veröffentlichen. Ein POST auf /offer/v1.0/publish mit der Objekt-ID und dem Kanal. 10000 steht für ImmobilienScout24.de, 10001 für die eigene Homepage des Kunden (Publish).
Zwei Regeln aus der Dokumentation sparen viel Fehlersuche. Erstens sollen Veröffentlichungen nacheinander und nicht parallel gesendet werden, weil ImmobilienScout24 bei jeder Anfrage das Kontingent prüft. Zweitens nimmt die API Datumsfelder mit GMT-Angabe nicht an und ignoriert das ganze Feld.
Ändern, Bilder pflegen und zurücknehmen
Ein automatisches Angebot ist erst dann wirklich automatisch, wenn auch Änderungen und das Zurücknehmen ohne Handarbeit laufen. Hier unterscheiden sich die Aufrufe deutlich vom Anlegen:
| Vorgang | Aufruf | Worauf es ankommt |
|---|---|---|
| Objekt ändern | PUT auf das Objekt | Sie senden immer alle Felder, auch wenn sich nur eines geändert hat. Die Objektart lässt sich nicht ändern; dafür legen Sie das Objekt neu an. |
| Bilder | Anhänge je Objekt | Bis zu 150 Bilder oder PDFs und bis zu 150 Links je Objekt, Dateien bis 50 MB, Videos bis 1 GB. Dokumente werden auf Schadsoftware geprüft und dürfen nicht passwortgeschützt sein. |
| Zurücknehmen | DELETE auf die Veröffentlichung | Jede Veröffentlichung wird mit einem eigenen Aufruf gelöscht, etwa die ID 58850320_10000. Eine gebuchte OnTop-Platzierung wird dabei ebenfalls deaktiviert. |
| Objekt löschen | DELETE auf das Objekt | ImmobilienScout24 empfiehlt, Objekte zu deaktivieren statt zu löschen. |
Die Regel mit den vollständigen Feldern beim PUT ist der häufigste Stolperstein. Wer nur den geänderten Preis schickt, riskiert, dass andere Angaben leer werden. Eine Software, die das Objekt aus einem Datensatz heraus jedes Mal komplett sendet, hat dieses Problem nicht.
Typische Fehler bei der Übertragung
Die FAQ für CRM-Nutzer listet die Meldungen, die in der Praxis am häufigsten auftauchen. Einige Beispiele:
- MANDATORY_FIELD_EMPTY: ein Pflichtfeld fehlt, zum Beispiel die Wohnfläche. Sie darf weder leer sein noch den Wert 0 haben.
- Energieausweis: Die API prüft die Energieangaben gegen eine Matrix aus Ausstellungsdatum, Ausweisart und Objektart. Meldungen auf _NOT_VALID_FOR_THIS_CERTIFICATE bedeuten, dass ein Feld zu diesem Ausweis nicht passt. Über energyCertificateAvailability (AVAILABLE, NOT_AVAILABLE_YET, NOT_REQUIRED) steuern Sie, ob geprüft wird (Energy Certificates).
- No contingent available: Im Kundenkonto ist kein Kontingent für die automatische Veröffentlichung frei.
- 429 Too Many Requests: Das Rate-Limit liegt bei 2.000 Anfragen pro Minute und API-Schlüssel. Der Header Retry-After nennt die Wartezeit.
Interessentenanfragen laufen übrigens nicht über die Import-Schnittstelle zurück. Laut Entwickler-FAQ schickt ImmobilienScout24 die Kontaktanfrage per E-Mail an den Anbieter und weist die Zahl der Anfragen im ScoutReport aus.
Selbst bauen oder eine Software nutzen, die das kann
Technisch ist die Schnittstelle gut dokumentiert. Der Aufwand steckt woanders: OAuth-Tokens je Nutzer verwalten, Anhänge einzeln übertragen, Veröffentlichungen in Reihe schicken, fehlgeschlagene Aufrufe wiederholen und jede Änderung vollständig nachsenden. Dazu kommen die Energieangaben und die Frage, wo die Objektdaten eigentlich führend gepflegt werden. Wenn das Angebot in einem Tool entsteht, die Mietfläche aber in einem anderen gepflegt wird, schreiben Sie dieselben Angaben weiterhin doppelt.
REPM spricht über die offizielle IS24-REST-API mit ImmobilienScout24, wahlweise gegen den Sandbox- oder den Produktionsendpunkt. Ein Klick auf Veröffentlichen im ListingCockpit erzeugt die Publikation und einen Sync-Job. Eine persistente Outbox stellt ihn zu, mit den Status Queued, Processing, Succeeded oder Failed. Ein fehlgeschlagener Job zeigt den Fehlertext des Portals und läuft mit einem Klick erneut. Nach erfolgreicher Veröffentlichung kommt der Exposé-Link zurück an das Angebot. Die Verbindung richten Sie im Portal Hub ein: Verbindungstest, OAuth-Zertifizierung und ein Aktiv-Schalter je Portal. Die Zugangsdaten liegen in Azure Key Vault. Details stehen auf der Seite zur ImmobilienScout24-Integration.
Fazit
Die ImmoScout24 API macht automatische Veröffentlichung gut möglich, verlangt aber ein Geschäftskonto, OAuth 1.0a, ein Kontingent und eine saubere Reihenfolge der Aufrufe. Am wenigsten Arbeit macht sie, wenn die Objektdaten an einer Stelle gepflegt und von dort vollständig übertragen werden. Wenn Sie sehen möchten, wie ein Angebot aus einem Objektdatensatz in der Sandbox live geht, fordern Sie eine Demo an.