REAL4STATE · RODRIGUEZ-WEB

real4state API

Mit der API verbinden Maklerbüros ihre Website, Zapier, Make oder eigene Software mit real4state. Die maschinenlesbare Spezifikation steht unter /api/v1/openapi.json (OpenAPI 3.1) und lässt sich direkt in Postman, Insomnia oder Codegeneratoren importieren.

Authentifizierung

Inhaber und Admins erstellen Schlüssel in real4state unter „API & Webhooks“ und wählen dabei die Berechtigungen. Der Schlüssel handelt im Namen der erstellenden Person im aktiven Büro und wird bei jedem Aufruf im Header X-API-Key gesendet. Schlüssel gehören auf den Server – nie in Browser-Code oder Apps. Limit: 300 Anfragen pro Minute und Schlüssel; jede Antwort nennt den Stand in den Headern RateLimit-Limit, RateLimit-Remaining und RateLimit-Reset(Sekunden bis zum nächsten Fenster). Gezählt wird je Server-Instanz – bitte bei 429 die Angabe Retry-After beachten.

curl https://real4state.de/api/v1/contacts?q=Müller \
  -H "X-API-Key: r4s_live_…"
  • contacts:read – Kontakte lesen
  • contacts:write – Kontakte anlegen und bearbeiten
  • search_profiles:read – Suchprofile lesen
  • search_profiles:write – Suchprofile anlegen und ändern
  • properties:read – Objekte lesen
  • deals:read – Deals lesen
  • deals:write – Deals anlegen und Phase ändern
  • inquiries:read – Anfragen lesen
  • inquiries:write – Anfragen anlegen (z. B. Website-Formular)
  • acquisitions:read – Akquise lesen
  • acquisitions:write – Eigentümer-Leads anlegen (z. B. Bewertungsrechner)
  • activities:read – Aufgaben, Termine und Notizen lesen
  • activities:write – Aufgaben, Termine und Notizen anlegen und ändern
  • phone:lookup – Telefonanlage: Name und Firma zur Rufnummer (Contact Lookup)
  • webhooks:manage – Webhooks verwalten

Website-Kontaktformular anbinden

Das Formular schickt die Daten an Ihren Server, der sie mit einem Schlüssel mit inquiries:write weiterleitet. Ein Kontakt mit derselben E-Mail wird automatisch verknüpft.

curl -X POST https://real4state.de/api/v1/inquiries \
  -H "X-API-Key: r4s_live_…" -H "Content-Type: application/json" \
  -H "Idempotency-Key: 6f1c2a1e-6c2b-4d6a-9a3e-2b0c4f9d8e71" \
  -d '{"name":"Erika Muster","email":"erika@example.de",
       "message":"Ist die Wohnung noch frei?","property_code":"R4S-04201",
       "source":"website"}'

Version 1 – Lesen und Schreiben

  • GET/POST /api/v1/contacts, GET/PATCH /api/v1/contacts/{id} – POST aktualisiert bei bekannter E-Mail (Upsert)
  • GET/POST /api/v1/search-profiles, GET/PATCH /api/v1/search-profiles/{id} – Suchprofile der Kontakte (Filter contact_id, active, updated_since); PATCH ändert nur die genannten Felder
  • GET /api/v1/properties, GET /api/v1/properties/{id|objektnummer}
  • GET/POST /api/v1/deals, GET/PATCH /api/v1/deals/{id}
  • GET/POST /api/v1/inquiries, GET /api/v1/inquiries/{id}
  • GET/POST /api/v1/activities, GET/PATCH /api/v1/activities/{id} – Aufgaben, Termine, Notizen (E-Mails nur lesend); PATCH ändert Titel, Text, Fälligkeit, Status (auch „erledigt“), Beginn/Ende und Zuständigkeit von Aufgaben und Terminen – bei Serien nur das Vorkommen
  • GET /api/v1/brokers, GET /api/v1/me

Listen: page, per_page (max. 100), sort_by, order sowie Filter wie updated_at_from. Werbeeinwilligungen (DSGVO) werden bewusst nicht über die API gesetzt.

Version 2 – Synchronisation

Für Spiegelungen und große Datenmengen: Datensätze aufsteigend nach Änderung, mit Cursor statt Seiten. Ohne Lücken und Duplikate, auch bei gleichzeitigen Änderungen.

GET /api/v2/contacts?updated_since=2026-10-01T00:00:00Z&limit=500
→ { "data": [...], "has_more": true, "next_cursor": "eyJ0Ijoi…" }
GET /api/v2/contacts?cursor=eyJ0Ijoi…&limit=500

Ressourcen: contacts, properties, deals, inquiries, activities, search_profiles.

Webhooks

real4state sendet Ereignisse per HTTPS-POST an Ihre Adresse – angelegt in der Oberfläche oder per POST /api/v1/webhooks (REST-Hooks, z. B. für Zapier). Antworten Sie mit einem 2xx-Status; sonst wiederholt real4state nach 1 min, 5 min, 30 min, 2 h, 6 h, 12 h und 24 h.

  • contact.created – Kontakt angelegt: Ein Kontakt wurde angelegt – in der Oberfläche, über die API, aus einer Portal-Anfrage oder der App.
  • contact.updated – Kontakt geändert: Ein Kontakt wurde geändert. Enthält nur die geänderten Bereiche, z. B. Status, Merkmale (tags), eigene Felder oder Einwilligung.
  • contact.deleted – Kontakt gelöscht (DSGVO): Ein Kontakt wurde nach DSGVO gelöscht. Nur die ID – bitte die Person auch im Zielsystem löschen.
  • contact.merged – Dublette zusammengeführt: Zwei Kontakte wurden als Dublette zusammengeführt: id bleibt, merged_id ist aufgelöst.
  • inquiry.created – Anfrage eingegangen: Eine Anfrage ist eingegangen (Portal-Mail, Website/API, Terminbuchung, WhatsApp oder manuell).
  • inquiry.updated – Anfrage geändert: Eine Anfrage wurde geändert, z. B. Status, Zuordnung oder erledigt.
  • inquiry.deleted – Anfrage gelöscht (Papierkorb): Eine Anfrage wurde gelöscht (Papierkorb, 30 Tage wiederherstellbar – dann erneut inquiry.created mit restored: true).
  • deal.created – Deal angelegt: Ein Deal (Interessent ↔ Objekt) wurde angelegt.
  • deal.updated – Deal geändert (z. B. Phase): Ein Deal wurde geändert, z. B. Phase (stage = Grundphase, stage_label = Name im Büro) oder Priorität.
  • property.created – Objekt angelegt: Ein Objekt wurde angelegt (bei Kopie/Variante mit copied_from).
  • property.updated – Objekt geändert: Ein Objekt wurde geändert, z. B. Status, Merkmale oder eigene Felder (nach Wiederherstellen mit restored: true).
  • property.deleted – Objekt gelöscht (Papierkorb): Ein Objekt wurde in den Papierkorb gelegt oder mit einem anderen zusammengeführt.
  • task.created – Aufgabe angelegt: Eine Aufgabe wurde angelegt.
  • task.updated – Aufgabe geändert: Eine Aufgabe wurde geändert (Titel, Text, Fälligkeit, Status, Zuständigkeit). previous_status nennt den Status davor.
  • task.completed – Aufgabe erledigt: Eine Aufgabe wurde erledigt (Status „Erledigt“). Zusätzlich zu task.updated.
  • appointment.created – Termin angelegt: Ein Termin wurde angelegt – bei Serien je Termin mit eigener ID und gemeinsamer series_id (Automatisierungen laufen je Serie nur einmal). Private Termine lösen keine Ereignisse aus.
  • appointment.updated – Termin geändert (z. B. verschoben): Ein Termin wurde geändert, z. B. verschoben, abgesagt oder durchgeführt. previous_starts_at/previous_ends_at/previous_status nennen die Werte davor.
  • appointment.completed – Termin hat stattgefunden: Ein Termin hat stattgefunden (Status „Durchgeführt“).
  • appointment.deleted – Termin gelöscht (Papierkorb): Ein Termin wurde gelöscht (Papierkorb, 30 Tage wiederherstellbar – dann erneut appointment.created mit restored: true). Private Termine lösen kein Ereignis aus.
  • feedback.received – Feedback zur Besichtigung erhalten: Ein Interessent hat das Feedback nach der Besichtigung ausgefüllt.
  • documents.received – Unterlagen hochgeladen: Über einen Unterlagen-Link wurden Dokumente hochgeladen.
  • note.created – Notiz dokumentiert: Eine Notiz oder Kontaktaufnahme (z. B. Anruf aus der App) wurde dokumentiert. Anrufe der Telefonanlage zusätzlich mit source „telefonanlage“, provider, direction, outcome und duration_seconds.
  • whatsapp.received – WhatsApp-Nachricht eingegangen: Eine WhatsApp-Nachricht ist eingegangen.
  • whatsapp.sent – WhatsApp-Nachricht gesendet: Eine WhatsApp-Nachricht wurde aus real4state gesendet.
  • search_profile.created – Suchprofil angelegt: Ein Suchprofil wurde angelegt (Oberfläche, API oder automatisch aus einer Anfrage).
  • search_profile.updated – Suchprofil geändert: Ein Suchprofil wurde geändert.
  • property.offered – Objekt angeboten (Entwurf): Ein Objekt wurde einem passenden Kontakt angeboten – als E-Mail-Entwurf (nicht gesendet).
  • expose.sent – Exposé-Link vorbereitet: Ein Exposé-Link wurde vorbereitet (mit oder ohne E-Mail-Entwurf).
  • expose.accepted – Exposé freigegeben (Widerruf/Provision bestätigt): Der Interessent hat das Exposé freigeschaltet (Widerrufsbelehrung/Provision bestätigt).
  • expose.revoked – Exposé widerrufen: Ein Exposé-Link wurde widerrufen.
  • owner.message – Nachricht aus dem Eigentümer-Portal: Der Eigentümer hat im Eigentümer-Portal eine Nachricht geschrieben.
  • acquisition.created – Akquise angelegt (Eigentümer-Lead): Eine Akquise (Eigentümer-Lead) wurde angelegt, z. B. aus dem Bewertungsrechner.
  • acquisition.updated – Akquise geändert (z. B. Phase): Eine Akquise wurde geändert, z. B. Phase.
  • acquisition.won – Maklerauftrag erhalten: Maklerauftrag erhalten; das Objekt wurde angelegt.
  • acquisition.lost – Akquise verloren: Eine Akquise ist verloren gegangen (mit Grund).
  • report.shared – Lage- und Bewertungsbericht geteilt: Ein Lage- und Bewertungsbericht wurde geteilt.
  • invoice.issued – Provisionsrechnung gestellt: Eine Provisionsrechnung wurde gestellt (Nummer vergeben, Beträge fest). Betrag brutto in Euro.
  • invoice.paid – Provisionsrechnung bezahlt: Eine Provisionsrechnung ist vollständig bezahlt (Zahlungseingang erfasst).
  • project.created – Projekt angelegt: Ein Projekt (Bauprojekt mit Einheiten) wurde angelegt.
  • project.updated – Projekt geändert: Ein Projekt wurde geändert oder gelöscht (status „geloescht“). Einheiten melden ihre Zuordnung über property.updated (project_id).
  • offer.created – Kaufangebot erfasst: Am Deal wurde ein Kaufangebot erfasst (Betrag in Euro). Ein früher Deal wechselt dabei auf „Verhandlung“ (zusätzlich deal.updated).
  • offer.updated – Kaufangebot geändert (z. B. angenommen): Ein Kaufangebot wurde geändert, z. B. angenommen oder abgelehnt.
  • offer.deleted – Kaufangebot gelöscht: Ein Kaufangebot wurde gelöscht.
  • buyer.feedback – Rückmeldung aus dem Käuferportal: Ein Interessent hat im Käuferportal auf ein passendes Objekt reagiert: status „interessiert“ (zusätzlich Aufgabe für den Makler), „abgelehnt“ oder null (zurückgenommen).
  • notary.submitted – Angaben für den Notar abgesendet: Verkäufer oder Käufer hat auf der Notar-Seite die Angaben für den Kaufvertrag abgesendet (zusätzlich Aufgabe für den Makler). Die Angaben selbst stehen nicht im Ereignis – nur im CRM (Notardatenblatt am Deal).
  • mandate.signed – Maklerauftrag online unterschrieben: Der Eigentümer hat den Maklerauftrag online unterschrieben (Nachweis gespeichert).
  • mandate.revoked – Maklerauftrag widerrufen: Ein online erteilter Maklerauftrag wurde widerrufen.
  • website_listing.published – Objekt für die Website veröffentlicht: Eine Website-Fassung wurde veröffentlicht (neu oder als Ersatz der bisherigen). Für angebundene Websites das Signal, Objektliste und Objektseite neu zu laden – abrufbar über die Website-Schnittstelle mit property_id oder reference. Statuswechsel und Löschen kommen als property.updated bzw. property.deleted.
  • website_listing.withdrawn – Objekt von der Website genommen: Eine veröffentlichte Website-Fassung wurde zurückgezogen; das Objekt ist über die Website-Schnittstelle nicht mehr abrufbar.

Der Katalog mit Beispiel-Nutzlast je Ereignis steht unter GET /api/v1/webhook-events (z. B. als Testdaten für Zapier oder Make). Fehlgeschlagene oder bereits zugestellte Ereignisse lassen sich im Zustellprotokoll unter „API & Webhooks“ oder per POST /api/v1/webhooks/{id}/deliveries/{deliveryId}/redeliver erneut senden – mit neuer X-Real4state-Delivery, aber gleicher Ereignis-ID (id bzw. X-Real4state-Event-Id), damit Sie Wiederholungen erkennen.

Signatur prüfen (Node.js):

import { createHmac, timingSafeEqual } from "node:crypto";
const ts = req.headers["x-real4state-timestamp"];
const expected = "sha256=" + createHmac("sha256", process.env.R4S_WEBHOOK_SECRET)
  .update(`${ts}.${rawBody}`).digest("hex");
const valid = timingSafeEqual(Buffer.from(expected), Buffer.from(req.headers["x-real4state-signature"]))
  && Math.abs(Date.now() / 1000 - Number(ts)) < 300;

Fehler

Fehler haben die Form {"error":{"code":"…","message":"…"}} mit den Statuscodes 400, 401, 403, 404, 409, 413, 415, 429 und 500. Fragen: support@real4state.de.