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 lesencontacts:write– Kontakte anlegen und bearbeitensearch_profiles:read– Suchprofile lesensearch_profiles:write– Suchprofile anlegen und ändernproperties:read– Objekte lesendeals:read– Deals lesendeals:write– Deals anlegen und Phase änderninquiries:read– Anfragen leseninquiries:write– Anfragen anlegen (z. B. Website-Formular)acquisitions:read– Akquise lesenacquisitions:write– Eigentümer-Leads anlegen (z. B. Bewertungsrechner)activities:read– Aufgaben, Termine und Notizen lesenactivities:write– Aufgaben, Termine und Notizen anlegen und ändernphone: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 (Filtercontact_id,active,updated_since); PATCH ändert nur die genannten FelderGET /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 VorkommenGET /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=500Ressourcen: 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.
