Geniefy API und MCP-Server: Dokumentation für Entwickler

Einführung

Geniefy ist die KI-Betriebsebene Ihrer Hausverwaltung. Die API gibt Ihnen Zugriff auf alles, was im Dashboard passiert: Anrufe und ihre Einordnung, WhatsApp- und E-Mail-Verläufe, das Wissen und die Einstellungen Ihres Agenten, Weiterleitungsregeln, Auswertungen und Abrechnung. Über die angebundenen Systeme erreichen Sie außerdem Vorgänge, Dokumente und Einheiten in casavi, Facilioo und DoNexus.

Es gibt zwei Wege hinein. Die REST-API ist für Ihre eigene Software gedacht, zum Beispiel ein Reporting, ein Intranet oder einen Abgleich mit Ihrem ERP. Der MCP-Server ist für KI-Agenten gedacht: Claude, ChatGPT, Cursor oder Ihr eigener Agent erhalten dieselben Fähigkeiten als Werkzeuge und beantworten Fragen wie „Welche Anrufe brauchen noch einen Rückruf?“ direkt aus Ihren Daten.

Schritt	Was passiert
1. Zugang anfragen	Wir stellen API-Schlüssel persönlich aus, gemeinsam mit dem Auftragsverarbeitungsvertrag. Sie nennen uns den Anwendungsfall, wir legen die passenden Berechtigungen fest.
2. Erste Anfrage senden	Rufen Sie die letzten Anrufe ab. Die Antwort enthält dieselben Karten, die Sie im Dashboard sehen.
3. Agenten verbinden	Tragen Sie den MCP-Server in Claude, ChatGPT oder Cursor ein. Ihr Agent kann danach Fragen zu Ihrer Verwaltung beantworten und Aufgaben anstoßen.

Erste Anfrage

curl "https://api.geniefy.de/v1/calls?limit=1" \
  -H "Authorization: Bearer $GENIEFY_API_KEY"

Antwort

{
  "calls": [
    {
      "callId": "AJ_7tQm2KxV9pLr4",
      "timestamp": 1789374510148,
      "timestampHuman": "2026-09-14T08:28:30.148Z",
      "name": "Anna Schneider",
      "fromPhone": "+4915199990123",
      "topic": "Heizung im Bad bleibt kalt",
      "category": "Repairs",
      "subcategory": "Heating",
      "duration": 142.6
    }
  ],
  "total": 1214,
  "nextCursor": "eyJvIjoxfQ"
}

Authentifizierung

Jede Anfrage trägt Ihren API-Schlüssel als Bearer-Token im Header Authorization. Ein Schlüssel gehört zu genau einer Verwaltung. Der Server bestimmt die Verwaltung immer aus dem Schlüssel und nie aus einem Parameter, deshalb gibt es in dieser API keine Kunden-ID.

Schlüssel beginnen mit gfy_live_. Jeder Schlüssel hat Berechtigungen (Scopes), die festlegen, welche Endpunkte er aufrufen darf. Fehlt eine Berechtigung, antwortet die API mit 403 INSUFFICIENT_SCOPE.

Scope	Erlaubt
`calls:read`	Anrufe, Transkripte und Kategorien lesen
`calls:write`	Ausgehende Anrufe starten
`conversations:read`	WhatsApp- und E-Mail-Verläufe lesen
`conversations:write`	Nachrichten senden, Gespräche übernehmen und zurückgeben
`knowledge:read`	FAQs und Abläufe lesen
`knowledge:write`	FAQs und Abläufe anlegen, ändern und löschen
`agent:read`	Agent-Einstellungen, Stimmen und gesperrte Nummern lesen
`agent:write`	Agent-Einstellungen ändern und Nummern sperren
`forwarding:read`	Öffnungszeiten, Feiertage und Weiterleitungsregeln lesen
`forwarding:write`	Weiterleitung konfigurieren
`integrations:read`	Status der Anbindungen lesen
`integrations:write`	Anbindungen konfigurieren und testen
`contacts:read`	Kontakte, Objekte und Einheiten lesen
`contacts:write`	Kontakte anlegen, ändern, importieren und löschen
`tasks:read`	Vorgeschlagene Aufgaben lesen
`tasks:write`	Aufgaben freigeben oder ablehnen
`insights:read`	Auswertungen lesen
`billing:read`	Verbrauch, Rechnungsdaten und Rechnungen lesen
`billing:write`	Rechnungsdaten ändern
`systems:read`	Vorgänge, Dokumente und Einheiten in angebundenen Systemen lesen
`systems:write`	Vorgänge in angebundenen Systemen anlegen und ändern
`webhooks:write`	Webhooks registrieren und entfernen

Verwenden Sie den Schlüssel nur auf Ihrem Server und nie im Browser oder in einer App. Pro Verwaltung können zwei Schlüssel gleichzeitig aktiv sein, damit Sie einen Schlüssel ohne Unterbrechung austauschen können.

KI-Clients, die sich per Browser anmelden (zum Beispiel claude.ai oder ChatGPT), verbinden sich mit dem MCP-Server über OAuth 2.1 mit PKCE. Die Person meldet sich mit ihrem Geniefy-Konto an und bestätigt die angefragten Berechtigungen.

Anfrage mit Schlüssel

GET /v1/calls?limit=20 HTTP/1.1
Host: api.geniefy.de
Authorization: Bearer gfy_live_4f9c2e1b7a0d4c8e9b3a
Accept: application/json

Abgelaufener Schlüssel

// 401 Unauthorized
{
  "code": "TOKEN_EXPIRED",
  "detail": "TOKEN_EXPIRED"
}

Versionierung

Die Hauptversion steht in der URL, aktuell https://api.geniefy.de/v1. Innerhalb einer Hauptversion ändern wir nur, was bestehende Integrationen weiter funktionieren lässt. Dazu zählen:

neue Endpunkte und neue MCP-Werkzeuge,
neue optionale Parameter,
neue Felder in Antworten,
neue Werte in Aufzählungsfeldern wie category, status oder callerRole.

Ignorieren Sie unbekannte Felder und behandeln Sie unbekannte Werte in Aufzählungen mit einem Standardfall. Dann bleibt Ihre Integration über die gesamte Hauptversion hinweg stabil.

Änderungen, die bestehenden Code brechen würden, erscheinen nur in einer neuen Hauptversion. Das betrifft entfernte oder umbenannte Felder, geänderte Typen und neue Pflichtparameter. Nach dem Start einer neuen Hauptversion bleibt die vorherige mindestens zwölf Monate verfügbar. Veraltete Endpunkte senden die Header Deprecation und Sunset mit dem Abschaltdatum, und wir informieren die technische Kontaktperson jedes Schlüssels per E-Mail.

Endpunkte mit dem Hinweis Beta sind für produktive Pilotprojekte gedacht. Sie können sich noch ändern, wir kündigen solche Änderungen aber mindestens 30 Tage vorher an.

Veralteter Endpunkt

HTTP/1.1 200 OK
Content-Type: application/json
Deprecation: @1822348800
Sunset: Mon, 30 Sep 2027 00:00:00 GMT
Link: <https://www.geniefy.de/developers#changelog>; rel="deprecation"

Anfragen und Antworten

Die API spricht JSON in UTF-8. Felder in Anfrage- und Antwortkörpern sind in camelCase geschrieben, Query-Parameter in snake_case. IDs sind undurchsichtige Zeichenketten: Speichern Sie sie so, wie Sie sie erhalten, und leiten Sie keine Bedeutung aus ihrem Aufbau ab.

Thema	Regel
Zeitstempel	`timestamp` ist Unix-Zeit in Millisekunden, Felder wie `timestampHuman` oder `createdAt` sind ISO 8601 in UTC.
Datumsfilter	`start_date` und `end_date` erwarten `YYYY-MM-DD`, schließen beide Tage ein und werden ohne Zeitzonenumrechnung angewendet.
Kategorien	Kategorie- und Unterkategorie-Schlüssel sind exakt und unterscheiden Groß- und Kleinschreibung. Die gültigen Werte liefert `GET /categories`.
Beträge	Geldbeträge sind Dezimalzahlen in Euro, netto, mit dem Feld `currency`.
Idempotenz	Anfragen, die etwas anlegen oder auslösen, akzeptieren den Header `Idempotency-Key`. Wiederholen Sie eine Anfrage mit demselben Schlüssel innerhalb von 24 Stunden, erhalten Sie die ursprüngliche Antwort, und nichts passiert doppelt.
Datenschutz	Daten werden in Deutschland gespeichert und auf EU-Infrastruktur verarbeitet. Links auf Aufnahmen und Transkripte sind signiert und 15 Minuten gültig.

Paginierung

Listen liefern höchstens limit Einträge (Standard 20, Maximum 100), dazu total und nextCursor. Übergeben Sie nextCursor als Parameter cursor, um die nächste Seite zu laden. Auf der letzten Seite ist nextCursor gleich null.

total zählt alle Treffer für Ihre Filter, unabhängig von limit. Wenn Sie nur eine Anzahl brauchen, etwa alle Reparaturanrufe dieser Woche, fragen Sie mit limit=1 an und lesen total.

Alle Seiten laden

const calls = [];
let cursor = null;

do {
  const url = new URL("https://api.geniefy.de/v1/calls");
  url.searchParams.set("start_date", "2026-09-01");
  url.searchParams.set("limit", "100");
  if (cursor) url.searchParams.set("cursor", cursor);

  const res = await fetch(url, {
    headers: { Authorization: `Bearer ${process.env.GENIEFY_API_KEY}` },
  });
  const page = await res.json();
  calls.push(...page.calls);
  cursor = page.nextCursor;
} while (cursor);

Fehler

Fehler kommen mit einem passenden HTTP-Status und einem JSON-Körper mit den Feldern code und detail. Werten Sie in Ihrem Code immer code aus, denn detail kann in Zukunft ausführlicher werden. Bei 422 enthält die Antwort zusätzlich errors mit dem betroffenen Feld.

Status	Code	Bedeutung
400	`INVALID_DATE_FORMAT`	Ein Datum hat nicht das Format `YYYY-MM-DD`.
400	`INVALID_DATE_RANGE`	`start_date` liegt nach `end_date`.
401	`INVALID_TOKEN_FORMAT`	Der Schlüssel hat kein gültiges Format.
401	`TOKEN_EXPIRED`	Der Schlüssel ist abgelaufen oder wurde widerrufen.
403	`MISSING_AUTHORIZATION`	Der Header `Authorization` fehlt oder enthält kein Bearer-Token.
403	`INSUFFICIENT_SCOPE`	Dem Schlüssel fehlt die Berechtigung für diesen Endpunkt.
404	`CALL_NOT_FOUND`	Es gibt keinen Anruf mit dieser ID in Ihrer Verwaltung.
404	`NOT_FOUND`	Das angefragte Objekt existiert nicht oder gehört nicht zu Ihrer Verwaltung.
409	`REVISION_CONFLICT`	Die Aufgabe wurde inzwischen von jemand anderem geändert.
409	`VERSION_CONFLICT`	Die Konfiguration wurde seit Ihrem letzten Lesen geändert.
409	`IDEMPOTENCY_CONFLICT`	Derselbe `Idempotency-Key` wurde mit einem anderen Anfragekörper verwendet.
409	`CONVERSATION_NOT_TAKEN_OVER`	Das Gespräch muss vor dem Senden übernommen werden.
409	`MANAGED_BY_CONNECTED_SYSTEM`	Kontakte werden im angebundenen System gepflegt und lassen sich hier nicht ändern.
422	`VALIDATION_ERROR`	Ein Parameter fehlt oder ist ungültig. `errors` nennt das Feld.
429	`RATE_LIMITED`	Zu viele Anfragen. Warten Sie die Sekunden aus `Retry-After` ab.
500	`SERVER_ERROR`	Ein unerwarteter Fehler bei uns. Wiederholen Sie die Anfrage später.
502	`SYSTEM_UNAVAILABLE`	Das angebundene System hat nicht oder fehlerhaft geantwortet.

Ungültiges Datum

// 400 Bad Request
{
  "code": "INVALID_DATE_FORMAT",
  "detail": "INVALID_DATE_FORMAT"
}

Validierungsfehler

// 422 Unprocessable Entity
{
  "code": "VALIDATION_ERROR",
  "detail": "Invalid request parameters",
  "errors": [
    { "field": "limit", "message": "must be between 1 and 100" }
  ]
}

Anfragelimits

Jeder Schlüssel darf 300 Anfragen pro Minute senden. Für POST /systems/query gelten 30 Anfragen pro Minute, weil dort mehrere Systeme abgefragt werden. Jede Antwort enthält die Header RateLimit-Limit, RateLimit-Remaining und RateLimit-Reset.

Wird das Limit überschritten, antwortet die API mit 429 RATE_LIMITED und dem Header Retry-After in Sekunden. Warten Sie mindestens so lange und erhöhen Sie die Wartezeit bei wiederholten Fehlern schrittweise. Wenn Sie dauerhaft mehr brauchen, sprechen Sie uns an.

Limit erreicht

HTTP/1.1 429 Too Many Requests
RateLimit-Limit: 300
RateLimit-Remaining: 0
RateLimit-Reset: 18
Retry-After: 18

Webhooks empfangen

Statt regelmäßig nachzufragen, kann Geniefy Ihren Server benachrichtigen, sobald etwas passiert: ein Anruf ist ausgewertet, eine WhatsApp-Nachricht ist eingegangen oder ein Vorgang wurde angelegt. Sie registrieren eine HTTPS-Adresse und die gewünschten Ereignisse über POST /webhooks.

Jede Zustellung ist ein POST mit JSON und dem Header Geniefy-Signature. Er enthält einen Zeitstempel t und eine HMAC-SHA256-Signatur v1 über t und den unveränderten Körper, berechnet mit dem Geheimnis Ihres Webhooks. Prüfen Sie die Signatur und verwerfen Sie Zustellungen, die älter als fünf Minuten sind.

Antworten Sie innerhalb von zehn Sekunden mit einem Status im Bereich 2xx. Andernfalls versuchen wir die Zustellung bis zu acht Mal über 24 Stunden erneut. Ereignisse können doppelt ankommen, deshalb trägt jedes eine eindeutige eventId.

Ereignis	Wird gesendet, wenn
`call.completed`	ein Anruf beendet und ausgewertet ist
`call.forwarded`	ein Anruf an eine Person oder den Notdienst durchgestellt wurde
`conversation.message.created`	eine WhatsApp-Nachricht oder E-Mail eingegangen ist
`conversation.mode.changed`	ein Gespräch übernommen oder an den Agenten zurückgegeben wurde
`task.created`	der Agent eine Aufgabe zur Freigabe vorschlägt
`task.executed`	eine freigegebene Aufgabe ausgeführt wurde
`ticket.created`	ein Vorgang in einem angebundenen System angelegt wurde

Zustellung

{
  "eventId": "evt_01J8Z3M4Q6W1",
  "type": "call.completed",
  "createdAt": "2026-09-14T08:31:02Z",
  "data": {
    "callId": "AJ_7tQm2KxV9pLr4",
    "category": "Repairs",
    "subcategory": "Heating",
    "ticketCreated": true
  }
}

Signatur prüfen (Node.js)

import crypto from "node:crypto";

export function verify(rawBody, header, secret) {
  const parts = Object.fromEntries(
    header.split(",").map((p) => p.split("="))
  );
  const age = Date.now() / 1000 - Number(parts.t);
  if (age > 300) return false;

  const expected = crypto
    .createHmac("sha256", secret)
    .update(`${parts.t}.${rawBody}`)
    .digest("hex");

  const given = Buffer.from(parts.v1 ?? "");
  const wanted = Buffer.from(expected);
  return given.length === wanted.length && crypto.timingSafeEqual(given, wanted);
}

MCP-Server

Der MCP-Server macht Geniefy zum Werkzeugkasten für jeden KI-Agenten, der das Model Context Protocol spricht. Ihr Agent sieht Anrufe, Gespräche, Wissen, Auswertungen und die angebundenen Systeme als Werkzeuge, entscheidet selbst, welche er braucht, und beantwortet so Fragen, für die sonst jemand drei Programme öffnen müsste.

MCP-Server
Transport: Streamable HTTP unter einer festen Adresse. Der Server ist zustandslos, jede Sitzung kann auf jedem Knoten landen.
Anmeldung: Clients mit eigener Konfiguration senden den API-Schlüssel im Header Authorization. Clients mit Browser-Anmeldung wie claude.ai oder ChatGPT nutzen OAuth 2.1. Der Agent sieht nur die Werkzeuge, für die der Schlüssel oder die Anmeldung Berechtigungen hat.

Beispiel

Sie

Welchen Anteil unserer Anrufe machen Reparaturen diesen Monat aus?

Agent ruft auf list_categories{"channel":"voice"}Kategorie Repairs gefunden
Agent ruft auf search_calls{"start_date":"2026-09-01","end_date":"2026-09-14","limit":1}total: 612
Agent ruft auf search_calls{"start_date":"2026-09-01","end_date":"2026-09-14","category":"Repairs","limit":1}total: 214

Agent

Vom 1. bis 14. September waren 214 von 612 Anrufen Reparaturen, also 35 Prozent. Am häufigsten ging es um Sanitär und Heizung.

Verbinden

Ein Befehl im Terminal, danach steht Geniefy in jeder Sitzung zur Verfügung.

Claude Code

claude mcp add --transport http geniefy https://mcp.geniefy.de/v1 \
  --header "Authorization: Bearer $GENIEFY_API_KEY"

Werkzeuge

LesenWerkzeuge, die nur Daten abrufen.

search_callsAnrufe auflisten
get_callAnruf abrufen
get_call_transcriptTranskript abrufen
list_categoriesKategorien auflisten
list_conversationsGespräche auflisten
get_conversationGespräch abrufen
search_knowledgeFAQs durchsuchen
list_proceduresAbläufe auflisten
get_agent_settingsAgent-Einstellungen abrufen
get_forwardingWeiterleitung abrufen
lookup_contactKontakt per Nummer finden
list_tasksAufgaben auflistenBeta
get_insights_summaryZusammenfassung abrufen
get_usageVerbrauch abrufen
list_invoicesRechnungen auflisten
query_systemsSysteme in Sprache abfragenBeta
list_ticketsVorgänge auflistenBeta
find_documentsDokumente suchenBeta

SchreibenWerkzeuge, die etwas verändern oder auslösen. Clients fragen vorher nach Bestätigung.

start_outbound_callAusgehenden Anruf starten
send_messageNachricht senden
set_conversation_modeGespräch übernehmen oder zurückgeben
send_emailE-Mail senden
create_faqFAQ anlegen
update_faqFAQ ändern
update_agent_settingsAgent-Einstellungen ändern
block_numberNummer sperren
decide_taskAufgabe freigeben oder ablehnenBeta
create_ticketVorgang anlegenBeta
update_ticketVorgang ändernBeta

Jedes Werkzeug ist als lesend oder schreibend gekennzeichnet. Clients wie Claude und ChatGPT fragen vor schreibenden Werkzeugen nach Ihrer Bestätigung.
Ein Schlüssel nur mit Leseberechtigungen ergibt einen Agenten, der nichts verändern kann. Das ist ein guter Start für Auswertungen.
Jeder Werkzeugaufruf erscheint im Protokoll Ihres Dashboards mit Client, Zeitpunkt und Parametern.

Ressourcen und Prompts

Ressourcen

geniefy://categories/{channel}Das Klassifizierungsvokabular eines Kanals, damit der Agent exakte Filterwerte kennt.
geniefy://agent/settingsDie aktuellen Agent-Einstellungen als Kontext.
geniefy://forwardingÖffnungszeiten und Weiterleitungsregeln.
geniefy://calls/{callId}Ein einzelner Anruf mit Zusammenfassung, zum Anhängen an eine Unterhaltung.

Prompts

weekly_reportErstellt einen Wochenbericht mit Volumen, Themen, Notfällen und offenen Rückrufen.Argumente: week
open_callbacksListet alle Anrufe, bei denen noch ein Rückruf aussteht, mit Anliegen und Nummer.Argumente: keine Argumente
building_briefFasst für ein Objekt zusammen, was in den letzten 30 Tagen gemeldet wurde und welche Vorgänge offen sind.Argumente: building

Anrufe

Jeder Anruf, den Ihr Agent annimmt oder führt, mit Zusammenfassung, Einordnung, Rolle der anrufenden Person und den daraus entstandenen Vorgängen. Die Liste entspricht der Anrufübersicht im Dashboard.

Das Call-Objekt20 Felder

Eine Anrufkarte in Listen. GET /calls/{callId} ergänzt die Felder darunter.

callIdstring: Eindeutige ID des Anrufs.
timestampinteger: Beginn als Unix-Zeit in Millisekunden.
timestampHumanstring: Beginn in ISO 8601, UTC.
namestringkann null sein: Name der anrufenden Person, soweit bekannt.
fromPhonestringkann null sein: Nummer der anrufenden Person im Format E.164.
topicstring: Anliegen in einem Satz.
categorystring: Hauptkategorie.
subcategorystring: Unterkategorie.
durationnumber: Dauer in Sekunden.
matchedOnobjectkann null sein: Nur vorhanden, wenn ein Filter auf eine Nebenkategorie zutraf.
summarystring: Zusammenfassung des Gesprächs.
callerRolestring: Erkannte Rolle: tenant, owner, advisoryBoard, serviceProvider, prospect oder unknown.
addressstringkann null sein: Genannte oder erkannte Adresse.
secondaryCategoriesobject[]: Weitere Einordnungen, wenn ein Anruf mehrere Anliegen hatte.
classificationConfidencenumber: Sicherheit der Einordnung zwischen 0 und 1.
ticketCreatedboolean: Ob ein Vorgang angelegt wurde.
ticketsobject[]: Angelegte Vorgänge mit Nummer, System und Link.
forwardingobjectkann null sein: Weiterleitung mit Ziel und Ergebnis, falls durchgestellt wurde.
callbackRequestedboolean: Ob die Person einen Rückruf wünscht.
recordingUrlstringkann null sein: Signierter Link auf die Aufnahme, 15 Minuten gültig.

Anrufe auflisten

GET/calls

Gibt die Anrufe Ihrer Verwaltung zurück, neueste zuerst. Alle Filter lassen sich kombinieren. Wenn Sie Kategorie und Unterkategorie gleichzeitig angeben, müssen beide zur selben Einordnung gehören. Trifft ein Filter nur auf eine Nebenkategorie zu, enthält die Karte das Feld matchedOn.

Scope calls:readMCP-Werkzeug search_calls

Query-Parameter

start_datestring: Erster Tag des Zeitraums im Format YYYY-MM-DD, inklusive.
end_datestring: Letzter Tag des Zeitraums im Format YYYY-MM-DD, inklusive.
categorystring: Eine oder mehrere Kategorien, durch Kommas getrennt. Mehrere Werte werden mit ODER verknüpft.
subcategorystring: Eine oder mehrere Unterkategorien, durch Kommas getrennt. Mehrere Werte werden mit ODER verknüpft.
searchstring: Sucht ohne Beachtung der Groß- und Kleinschreibung in Name, Thema und Anruf-ID. Enthält die Suche nur Ziffern, wird auch die Telefonnummer durchsucht.
limitinteger: Höchstzahl der zurückgegebenen Einträge, zwischen 1 und 100. Hat keinen Einfluss auf total.Standard: 20
cursorstring: Der Wert nextCursor der vorherigen Seite.

Antwort

200 OK Eine Seite mit Anrufkarten.

Mögliche Fehler

400INVALID_DATE_FORMATEin Datum hat nicht das Format YYYY-MM-DD.
400INVALID_DATE_RANGEstart_date liegt nach end_date.

curl "https://api.geniefy.de/v1/calls?start_date=2026-09-07&category=Repairs&limit=20" \
  -H "Authorization: Bearer $GENIEFY_API_KEY"

Antwort 200 OK

{
  "calls": [
    {
      "callId": "AJ_7tQm2KxV9pLr4",
      "timestamp": 1789374510148,
      "timestampHuman": "2026-09-14T08:28:30.148Z",
      "name": "Anna Schneider",
      "fromPhone": "+4915199990123",
      "topic": "Heizung im Bad bleibt seit gestern kalt",
      "category": "Repairs",
      "subcategory": "Heating",
      "duration": 142.6
    }
  ],
  "total": 268,
  "nextCursor": "eyJvIjoyMH0"
}

Anruf abrufen

GET/calls/{callId}

Gibt einen Anruf mit Zusammenfassung, Rolle der anrufenden Person, Adresse, angelegten Vorgängen und Weiterleitung zurück. Eine unbekannte ID und die ID einer anderen Verwaltung ergeben beide 404 CALL_NOT_FOUND. Das Abrufen markiert den Anruf nicht als gelesen.

Scope calls:readMCP-Werkzeug get_call

Pfad-Parameter

callIdstringerforderlich: ID aus einer Anrufkarte.

Antwort

200 OK Das vollständige Anruf-Objekt.

Mögliche Fehler

404CALL_NOT_FOUNDEs gibt keinen Anruf mit dieser ID in Ihrer Verwaltung.

curl "https://api.geniefy.de/v1/calls/AJ_7tQm2KxV9pLr4" \
  -H "Authorization: Bearer $GENIEFY_API_KEY"

Antwort 200 OK

{
  "callId": "AJ_7tQm2KxV9pLr4",
  "timestamp": 1789374510148,
  "timestampHuman": "2026-09-14T08:28:30.148Z",
  "name": "Anna Schneider",
  "fromPhone": "+4915199990123",
  "topic": "Heizung im Bad bleibt seit gestern kalt",
  "category": "Repairs",
  "subcategory": "Heating",
  "duration": 142.6,
  "summary": "Frau Schneider meldet, dass der Heizkörper im Bad seit gestern Abend kalt bleibt. Die übrigen Räume sind warm. Ein Vorgang wurde angelegt und dem Heizungsbauer zugewiesen.",
  "callerRole": "tenant",
  "isAnonymous": false,
  "address": "Lindenstraße 12, 80331 München",
  "locations": [
    {
      "buildingId": "bld_Linden12",
      "unitId": "unit_Linden12_WE04",
      "label": "WE 04"
    }
  ],
  "secondaryCategories": [],
  "classificationConfidence": 0.94,
  "classificationNeedsReview": false,
  "ticketCreated": true,
  "tickets": [
    {
      "ticketId": "casavi:TK-20931",
      "displayNumber": "TK-20931",
      "system": "casavi",
      "appLink": "https://app.casavi.com/tickets/20931"
    }
  ],
  "forwarding": null,
  "callbackRequested": false,
  "recordingUrl": "https://files.geniefy.de/rec/AJ_7tQm2KxV9pLr4.mp3?sig=…",
  "transcriptUrl": "https://files.geniefy.de/tr/AJ_7tQm2KxV9pLr4.json?sig=…",
  "taxonomyVersion": "2026-07"
}

Transkript abrufen

GET/calls/{callId}/transcript

Gibt das Gespräch als Folge von Redebeiträgen zurück. Jeder Beitrag nennt die Sprecherrolle und den Zeitpunkt in Millisekunden ab Gesprächsbeginn.

Scope calls:readMCP-Werkzeug get_call_transcript

Pfad-Parameter

callIdstringerforderlich: ID des Anrufs.

Antwort

200 OK Das Transkript des Anrufs.

Mögliche Fehler

404CALL_NOT_FOUNDEs gibt keinen Anruf mit dieser ID in Ihrer Verwaltung.

curl "https://api.geniefy.de/v1/calls/AJ_7tQm2KxV9pLr4/transcript" \
  -H "Authorization: Bearer $GENIEFY_API_KEY"

Antwort 200 OK

{
  "callId": "AJ_7tQm2KxV9pLr4",
  "language": "de",
  "turns": [
    {
      "speaker": "agent",
      "offsetMs": 0,
      "text": "Guten Tag, Sie sprechen mit Lena, der digitalen Assistentin der Hausverwaltung Muster."
    },
    {
      "speaker": "caller",
      "offsetMs": 6200,
      "text": "Hallo, bei mir im Bad wird die Heizung nicht mehr warm."
    },
    {
      "speaker": "agent",
      "offsetMs": 9800,
      "text": "Das tut mir leid. Seit wann ist das so, und sind die anderen Räume warm?"
    }
  ]
}

Ausgehenden Anruf starten

POST/calls/outbound

Der Agent ruft eine Person an, zum Beispiel für einen Rückruf oder um bei einem Dienstleister nachzufassen. Der Auftrag beschreibt, was der Agent erreichen soll. Ohne scheduledAt beginnt der Anruf innerhalb einer Minute. Das Ergebnis erscheint anschließend als normaler Anruf und über das Ereignis call.completed.

Scope calls:writeMCP-Werkzeug start_outbound_call

Anfragekörper

tostringerforderlich: Telefonnummer im Format E.164.
instructionstringerforderlich: Was der Agent im Gespräch klären soll, in ganzen Sätzen.
contactIdstring: Verknüpft den Anruf mit einem Kontakt.
relatedCallIdstring: Der Anruf, auf den sich dieser Rückruf bezieht.
languagestring: Gesprächssprache, Standard ist die Hauptsprache des Agenten.Werte: deen
scheduledAtstring: Zeitpunkt in ISO 8601, frühestens jetzt und höchstens sieben Tage im Voraus.

Antwort

202 Accepted Der Anruf ist eingeplant.

curl -X POST "https://api.geniefy.de/v1/calls/outbound" \
  -H "Authorization: Bearer $GENIEFY_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "+4915199990123",
    "instruction": "Frau Schneider mitteilen, dass der Heizungsbauer morgen zwischen 8 und 10 Uhr kommt, und fragen, ob jemand zu Hause ist.",
    "relatedCallId": "AJ_7tQm2KxV9pLr4",
    "language": "de"
  }'

Antwort 202 Accepted

{
  "outboundCallId": "ob_2Lq9Vt6",
  "status": "queued",
  "scheduledAt": "2026-09-14T09:02:00Z"
}

Kategorien auflisten

GET/categories

Gibt die Kategorien und Unterkategorien zurück, nach denen Ihre Anfragen eingeordnet werden. Rufen Sie diesen Endpunkt vor dem Filtern auf, denn die Werte sind exakt und hängen vom Kanal ab.

Scope calls:readMCP-Werkzeug list_categories

Query-Parameter

channelstring: Kanal, dessen Vokabular zurückgegeben wird.Werte: voicewhatsappemailStandard: voice

Antwort

200 OK Das Klassifizierungsvokabular.

curl "https://api.geniefy.de/v1/categories?channel=voice" \
  -H "Authorization: Bearer $GENIEFY_API_KEY"

Antwort 200 OK

{
  "taxonomyVersion": "2026-07",
  "categories": [
    {
      "category": "Emergency",
      "subcategories": [
        {
          "subcategory": "EmergencyWater"
        },
        {
          "subcategory": "EmergencyHeating"
        }
      ]
    },
    {
      "category": "Repairs",
      "subcategories": [
        {
          "subcategory": "Heating"
        },
        {
          "subcategory": "Plumbing"
        },
        {
          "subcategory": "WaterDamage"
        }
      ]
    },
    {
      "category": "Accounting",
      "subcategories": [
        {
          "subcategory": "OperatingCosts"
        },
        {
          "subcategory": "AnnualStatement"
        }
      ]
    }
  ]
}

WhatsApp und E-Mail

Gespräche aus WhatsApp und dem verbundenen Postfach. Sie können mitlesen, Gespräche übernehmen, im Namen Ihres Teams antworten und E-Mails senden oder als Entwurf ablegen.

Das Conversation-Objekt10 Felder

Ein Verlauf mit einer Person über einen Kanal.

conversationIdstring: Eindeutige ID des Gesprächs.
channelstring: whatsapp oder email.
statusstring: open oder closed.
modestring: ai, wenn der Agent antwortet, human, wenn Ihr Team übernommen hat.
contactobject: Name, Nummer oder Adresse und Rolle der Person.
subjectstring: Anliegen in einem Satz oder Betreff der E-Mail.
categorystring: Hauptkategorie.
unreadboolean: Ob es ungelesene Nachrichten gibt.
lastMessageAtstring: Zeitpunkt der letzten Nachricht, ISO 8601.
messagesobject[]: Nur in GET /conversations/{conversationId}: alle Nachrichten mit Richtung, Verfasser und Anhängen.

Gespräche auflisten

GET/conversations

Gibt WhatsApp- und E-Mail-Verläufe zurück, zuletzt aktive zuerst.

Scope conversations:readMCP-Werkzeug list_conversations

Query-Parameter

channelstring: Nur Gespräche dieses Kanals.Werte: whatsappemail
statusstring: Nur offene oder nur abgeschlossene Gespräche.Werte: openclosed
modestring: Nur Gespräche, die gerade der Agent oder eine Person führt.Werte: aihuman
start_datestring: Erster Tag des Zeitraums im Format YYYY-MM-DD, inklusive.
end_datestring: Letzter Tag des Zeitraums im Format YYYY-MM-DD, inklusive.
searchstring: Sucht in Name, Telefonnummer, E-Mail-Adresse und Betreff.
limitinteger: Höchstzahl der zurückgegebenen Einträge, zwischen 1 und 100. Hat keinen Einfluss auf total.Standard: 20
cursorstring: Der Wert nextCursor der vorherigen Seite.

Antwort

200 OK Eine Seite mit Gesprächen.

curl "https://api.geniefy.de/v1/conversations?channel=whatsapp" \
  -H "Authorization: Bearer $GENIEFY_API_KEY"

Antwort 200 OK

{
  "conversations": [
    {
      "conversationId": "wa_9KfR2mXq71",
      "channel": "whatsapp",
      "status": "open",
      "mode": "ai",
      "contact": {
        "name": "Jonas Weber",
        "phone": "+4915199990456",
        "role": "tenant"
      },
      "subject": "Wasserfleck an der Decke im Flur",
      "category": "Repairs",
      "subcategory": "WaterDamage",
      "unread": true,
      "lastMessageAt": "2026-09-14T17:42:10Z"
    }
  ],
  "total": 41,
  "nextCursor": null
}

Gespräch abrufen

GET/conversations/{conversationId}

Gibt ein Gespräch mit allen Nachrichten und Anhängen zurück. Anhänge wie Fotos oder Sprachnachrichten kommen als signierte Links.

Scope conversations:readMCP-Werkzeug get_conversation

Pfad-Parameter

conversationIdstringerforderlich: ID des Gesprächs.

Antwort

200 OK Das Gespräch mit Nachrichten.

Mögliche Fehler

404NOT_FOUNDDas angefragte Objekt existiert nicht oder gehört nicht zu Ihrer Verwaltung.

curl "https://api.geniefy.de/v1/conversations/wa_9KfR2mXq71" \
  -H "Authorization: Bearer $GENIEFY_API_KEY"

Antwort 200 OK

{
  "conversationId": "wa_9KfR2mXq71",
  "channel": "whatsapp",
  "status": "open",
  "mode": "ai",
  "contact": {
    "name": "Jonas Weber",
    "phone": "+4915199990456",
    "role": "tenant"
  },
  "subject": "Wasserfleck an der Decke im Flur",
  "category": "Repairs",
  "subcategory": "WaterDamage",
  "unread": true,
  "lastMessageAt": "2026-09-14T17:42:10Z",
  "messages": [
    {
      "messageId": "msg_1",
      "direction": "inbound",
      "author": "contact",
      "text": "Hallo, im Flur ist ein Wasserfleck an der Decke. Foto anbei.",
      "attachments": [
        {
          "type": "image",
          "url": "https://files.geniefy.de/wa/msg_1.jpg?sig=…"
        }
      ],
      "sentAt": "2026-09-14T17:40:55Z"
    },
    {
      "messageId": "msg_2",
      "direction": "outbound",
      "author": "agent",
      "text": "Danke für das Foto. Ist der Fleck feucht, und tropft es gerade?",
      "attachments": [],
      "sentAt": "2026-09-14T17:41:03Z",
      "status": "read"
    }
  ]
}

Laufende Gespräche abrufen

GET/conversations/live

Gibt die WhatsApp-Gespräche zurück, in denen in den letzten 15 Minuten geschrieben wurde. Das entspricht der Ansicht WhatsApp live im Dashboard und eignet sich für eigene Leitstände.

Scope conversations:read

Dieser Endpunkt erwartet keine Parameter.

Antwort

200 OK Die aktiven Gespräche.

curl "https://api.geniefy.de/v1/conversations/live" \
  -H "Authorization: Bearer $GENIEFY_API_KEY"

Antwort 200 OK

{
  "conversations": [
    {
      "conversationId": "wa_9KfR2mXq71",
      "channel": "whatsapp",
      "status": "open",
      "mode": "ai",
      "contact": {
        "name": "Jonas Weber",
        "phone": "+4915199990456",
        "role": "tenant"
      },
      "subject": "Wasserfleck an der Decke im Flur",
      "category": "Repairs",
      "subcategory": "WaterDamage",
      "unread": true,
      "lastMessageAt": "2026-09-14T17:42:10Z",
      "typing": "contact"
    }
  ]
}

Nachricht senden

POST/conversations/{conversationId}/messages

Sendet eine Nachricht im Namen Ihres Teams. Bei WhatsApp muss das Gespräch vorher übernommen sein (mode ist human), damit Agent und Mensch nicht gleichzeitig antworten. Außerhalb des 24-Stunden-Fensters von WhatsApp ist nur eine freigegebene Vorlage möglich.

Scope conversations:writeMCP-Werkzeug send_message

Pfad-Parameter

conversationIdstringerforderlich: ID des Gesprächs.

Anfragekörper

textstringerforderlich: Inhalt der Nachricht, höchstens 4.096 Zeichen.
attachmentsobject[]: Bis zu fünf Anhänge mit type und öffentlich erreichbarer url.

Antwort

201 Created Die gesendete Nachricht.

Mögliche Fehler

409CONVERSATION_NOT_TAKEN_OVERDas Gespräch muss vor dem Senden übernommen werden.

curl -X POST "https://api.geniefy.de/v1/conversations/wa_9KfR2mXq71/messages" \
  -H "Authorization: Bearer $GENIEFY_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "Guten Abend Herr Weber, unser Hausmeister schaut sich den Fleck morgen früh an. Bitte stellen Sie einen Eimer unter, falls es tropft."
  }'

Antwort 201 Created

{
  "messageId": "msg_3",
  "direction": "outbound",
  "author": "human",
  "text": "Guten Abend Herr Weber, unser Hausmeister schaut sich den Fleck morgen früh an. Bitte stellen Sie einen Eimer unter, falls es tropft.",
  "sentAt": "2026-09-14T17:45:12Z",
  "status": "sent"
}

Gespräch übernehmen oder zurückgeben

PUT/conversations/{conversationId}/mode

Mit human übernimmt Ihr Team das Gespräch und der Agent schweigt. Mit ai geben Sie es an den Agenten zurück, der den bisherigen Verlauf kennt und dort weitermacht.

Scope conversations:writeMCP-Werkzeug set_conversation_mode

Pfad-Parameter

conversationIdstringerforderlich: ID des Gesprächs.

Anfragekörper

modestringerforderlich: Wer das Gespräch führt.Werte: aihuman

Antwort

200 OK Das aktualisierte Gespräch.

curl -X PUT "https://api.geniefy.de/v1/conversations/wa_9KfR2mXq71/mode" \
  -H "Authorization: Bearer $GENIEFY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "mode": "human"
  }'

Antwort 200 OK

{
  "conversationId": "wa_9KfR2mXq71",
  "channel": "whatsapp",
  "status": "open",
  "mode": "human",
  "contact": {
    "name": "Jonas Weber",
    "phone": "+4915199990456",
    "role": "tenant"
  },
  "subject": "Wasserfleck an der Decke im Flur",
  "category": "Repairs",
  "subcategory": "WaterDamage",
  "unread": true,
  "lastMessageAt": "2026-09-14T17:42:10Z",
  "takenOverBy": "maria.hoffmann@hv-muster.de"
}

E-Mail senden

POST/emails

Sendet eine E-Mail über das verbundene Postfach oder legt sie als Entwurf zur Prüfung an. Mit conversationId wird die E-Mail als Antwort im bestehenden Verlauf abgelegt.

Scope conversations:writeMCP-Werkzeug send_email

Anfragekörper

tostring[]erforderlich: Empfängeradressen.
ccstring[]: Adressen in Kopie.
subjectstringerforderlich: Betreff der E-Mail.
textstringerforderlich: Inhalt als Text. Absätze trennen Sie mit einer Leerzeile.
conversationIdstring: Verlauf, in dem die E-Mail als Antwort erscheint.
sendModestring: Sofort senden oder als Entwurf ablegen.Werte: senddraftStandard: send

Antwort

201 Created Die E-Mail oder der Entwurf.

curl -X POST "https://api.geniefy.de/v1/emails" \
  -H "Authorization: Bearer $GENIEFY_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "to": [
      "heizung@huber-heizungsbau.de"
    ],
    "subject": "Auftrag TK-20931: Heizkörper Bad, Lindenstraße 12, WE 04",
    "text": "Guten Tag Herr Huber,\n\nbitte prüfen Sie den Heizkörper im Bad der WE 04. Die Mieterin ist morgen ab 8 Uhr zu Hause.\n\nViele Grüße\nHausverwaltung Muster",
    "sendMode": "draft"
  }'

Antwort 201 Created

{
  "emailId": "em_6Tq1Wd3",
  "status": "draft",
  "conversationId": "em_thread_44Kp",
  "createdAt": "2026-09-14T09:05:00Z"
}

Wissen

Die Fragen und Antworten, auf die sich Ihr Agent in allen Kanälen stützt. Ein neuer Eintrag gilt sofort, es gibt keine Trainingszeit.

Das FAQ-Objekt5 Felder

Ein Wissenseintrag.

faqIdstring: Eindeutige ID.
questionstring: Die Frage.
answerstring: Die Antwort.
createdAtstring: Erstellt am, ISO 8601.
updatedAtstring: Zuletzt geändert am, ISO 8601.

FAQs auflisten

GET/faqs

Gibt alle Fragen und Antworten zurück, die Ihr Agent kennt.

Scope knowledge:read

Query-Parameter

limitinteger: Höchstzahl der zurückgegebenen Einträge, zwischen 1 und 100. Hat keinen Einfluss auf total.Standard: 20
cursorstring: Der Wert nextCursor der vorherigen Seite.

Antwort

200 OK Eine Seite mit FAQs.

curl "https://api.geniefy.de/v1/faqs" \
  -H "Authorization: Bearer $GENIEFY_API_KEY"

Antwort 200 OK

{
  "faqs": [
    {
      "faqId": "faq_3Hc8wQ2p",
      "question": "Wann wird die Betriebskostenabrechnung verschickt?",
      "answer": "Die Abrechnung für 2025 versenden wir bis spätestens 30. November 2026 per Post und im Eigentümerportal.",
      "createdAt": "2026-06-02T09:14:00Z",
      "updatedAt": "2026-09-01T11:20:00Z"
    }
  ],
  "total": 87,
  "nextCursor": "eyJvIjoyMH0"
}

FAQs durchsuchen

GET/faqs/search

Findet Einträge nach Bedeutung und nicht nur nach Wortlaut. So findet die Suche nach Nebenkosten auch eine Antwort, in der Betriebskosten steht.

Scope knowledge:readMCP-Werkzeug search_knowledge

Query-Parameter

qstringerforderlich: Frage oder Stichwort.
limitinteger: Höchstzahl der zurückgegebenen Einträge, zwischen 1 und 100. Hat keinen Einfluss auf total.Standard: 5

Antwort

200 OK Treffer, beste Übereinstimmung zuerst.

curl "https://api.geniefy.de/v1/faqs/search?q=Nebenkostenabrechnung" \
  -H "Authorization: Bearer $GENIEFY_API_KEY"

Antwort 200 OK

{
  "results": [
    {
      "faqId": "faq_3Hc8wQ2p",
      "question": "Wann wird die Betriebskostenabrechnung verschickt?",
      "answer": "Die Abrechnung für 2025 versenden wir bis spätestens 30. November 2026 per Post und im Eigentümerportal.",
      "createdAt": "2026-06-02T09:14:00Z",
      "updatedAt": "2026-09-01T11:20:00Z",
      "score": 0.91
    }
  ]
}

FAQ anlegen

POST/faqs

Legt einen Eintrag an, den der Agent ab sofort in allen Kanälen nutzt. Ähnelt die Frage stark einem vorhandenen Eintrag, wird er trotzdem angelegt, und die Antwort enthält duplicateWarning mit dem ähnlichen Eintrag.

Scope knowledge:writeMCP-Werkzeug create_faq

Anfragekörper

questionstringerforderlich: Die Frage, so wie Anrufende sie stellen würden.
answerstringerforderlich: Die Antwort in ganzen Sätzen.

Antwort

201 Created Der neue Eintrag.

curl -X POST "https://api.geniefy.de/v1/faqs" \
  -H "Authorization: Bearer $GENIEFY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "question": "Wo finde ich das Protokoll der letzten Eigentümerversammlung?",
    "answer": "Das Protokoll steht im Eigentümerportal unter Dokumente. Auf Wunsch schicken wir es Ihnen per E-Mail."
  }'

Antwort 201 Created

{
  "faq": {
    "faqId": "faq_9Lm4Tz7",
    "question": "Wo finde ich das Protokoll der letzten Eigentümerversammlung?",
    "answer": "Das Protokoll steht im Eigentümerportal unter Dokumente. Auf Wunsch schicken wir es Ihnen per E-Mail.",
    "createdAt": "2026-09-14T10:00:00Z",
    "updatedAt": "2026-09-14T10:00:00Z"
  },
  "duplicateWarning": null
}

FAQ abrufen

GET/faqs/{faqId}

Gibt einen einzelnen Eintrag zurück.

Scope knowledge:read

Pfad-Parameter

faqIdstringerforderlich: ID des Eintrags.

Antwort

200 OK Der Eintrag.

Mögliche Fehler

404NOT_FOUNDDas angefragte Objekt existiert nicht oder gehört nicht zu Ihrer Verwaltung.

curl "https://api.geniefy.de/v1/faqs/faq_3Hc8wQ2p" \
  -H "Authorization: Bearer $GENIEFY_API_KEY"

Antwort 200 OK

{
  "faqId": "faq_3Hc8wQ2p",
  "question": "Wann wird die Betriebskostenabrechnung verschickt?",
  "answer": "Die Abrechnung für 2025 versenden wir bis spätestens 30. November 2026 per Post und im Eigentümerportal.",
  "createdAt": "2026-06-02T09:14:00Z",
  "updatedAt": "2026-09-01T11:20:00Z"
}

FAQ ändern

PUT/faqs/{faqId}

Ersetzt Frage und Antwort eines Eintrags.

Scope knowledge:writeMCP-Werkzeug update_faq

Pfad-Parameter

faqIdstringerforderlich: ID des Eintrags.

Anfragekörper

questionstringerforderlich: Die neue Frage.
answerstringerforderlich: Die neue Antwort.

Antwort

200 OK Der geänderte Eintrag.

Mögliche Fehler

404NOT_FOUNDDas angefragte Objekt existiert nicht oder gehört nicht zu Ihrer Verwaltung.

curl -X PUT "https://api.geniefy.de/v1/faqs/faq_3Hc8wQ2p" \
  -H "Authorization: Bearer $GENIEFY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "question": "Wann wird die Betriebskostenabrechnung verschickt?",
    "answer": "Die Abrechnung für 2025 versenden wir bis spätestens 30. November 2026 per Post und im Eigentümerportal."
  }'

Antwort 200 OK

{
  "faq": {
    "faqId": "faq_3Hc8wQ2p",
    "question": "Wann wird die Betriebskostenabrechnung verschickt?",
    "answer": "Die Abrechnung für 2025 versenden wir bis spätestens 30. November 2026 per Post und im Eigentümerportal.",
    "createdAt": "2026-06-02T09:14:00Z",
    "updatedAt": "2026-09-01T11:20:00Z"
  },
  "duplicateWarning": null
}

FAQ löschen

DELETE/faqs/{faqId}

Löscht einen Eintrag. Der Agent nutzt ihn ab sofort nicht mehr.

Scope knowledge:write

Pfad-Parameter

faqIdstringerforderlich: ID des Eintrags.

Antwort

204 No Content Keine Antwort im Körper.

Mögliche Fehler

404NOT_FOUNDDas angefragte Objekt existiert nicht oder gehört nicht zu Ihrer Verwaltung.

curl -X DELETE "https://api.geniefy.de/v1/faqs/faq_3Hc8wQ2p" \
  -H "Authorization: Bearer $GENIEFY_API_KEY"

Abläufe

Abläufe sagen dem Agenten, wie er in einer bestimmten Situation vorgeht, etwa bei einem verlorenen Schlüssel oder einer Kündigung. Im Dashboard heißen sie Persona und Abläufe.

Abläufe auflisten

GET/procedures

Gibt alle Abläufe zurück, die der Agent in bestimmten Situationen befolgt.

Scope knowledge:readMCP-Werkzeug list_procedures

Dieser Endpunkt erwartet keine Parameter.

Antwort

200 OK Alle Abläufe.

curl "https://api.geniefy.de/v1/procedures" \
  -H "Authorization: Bearer $GENIEFY_API_KEY"

Antwort 200 OK

{
  "procedures": [
    {
      "procedureId": "prc_W4n7Lx1",
      "name": "Schlüsselverlust",
      "trigger": "Eine Person meldet, dass ein Haus- oder Wohnungsschlüssel verloren gegangen ist.",
      "steps": [
        "Objekt, Einheit und Art des Schlüssels erfragen.",
        "Darauf hinweisen, dass ein Ersatzschlüssel kostenpflichtig ist.",
        "Vorgang mit Kategorie Zugang anlegen und dem Objektbetreuer zuweisen."
      ],
      "channels": [
        "voice",
        "whatsapp",
        "email"
      ],
      "enabled": true,
      "updatedAt": "2026-08-21T15:03:00Z"
    }
  ]
}

Ablauf anlegen

POST/procedures

Legt einen Ablauf an. trigger beschreibt in einem Satz, wann er gilt, steps sagt dem Agenten Schritt für Schritt, was zu tun ist.

Scope knowledge:write

Anfragekörper

namestringerforderlich: Kurzer Name, der im Dashboard erscheint.
triggerstringerforderlich: Situation, in der der Ablauf gilt.
stepsstring[]erforderlich: Die Schritte in der richtigen Reihenfolge.
channelsstring[]: Kanäle, in denen der Ablauf gilt. Standard sind alle.Werte: voicewhatsappemail
enabledboolean: Ob der Ablauf aktiv ist.Standard: true

Antwort

201 Created Der neue Ablauf.

curl -X POST "https://api.geniefy.de/v1/procedures" \
  -H "Authorization: Bearer $GENIEFY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Schlüsselverlust",
    "trigger": "Eine Person meldet, dass ein Haus- oder Wohnungsschlüssel verloren gegangen ist.",
    "steps": [
      "Objekt, Einheit und Art des Schlüssels erfragen.",
      "Darauf hinweisen, dass ein Ersatzschlüssel kostenpflichtig ist.",
      "Vorgang mit Kategorie Zugang anlegen und dem Objektbetreuer zuweisen."
    ],
    "channels": [
      "voice",
      "whatsapp",
      "email"
    ]
  }'

Antwort 201 Created

{
  "procedureId": "prc_W4n7Lx1",
  "name": "Schlüsselverlust",
  "trigger": "Eine Person meldet, dass ein Haus- oder Wohnungsschlüssel verloren gegangen ist.",
  "steps": [
    "Objekt, Einheit und Art des Schlüssels erfragen.",
    "Darauf hinweisen, dass ein Ersatzschlüssel kostenpflichtig ist.",
    "Vorgang mit Kategorie Zugang anlegen und dem Objektbetreuer zuweisen."
  ],
  "channels": [
    "voice",
    "whatsapp",
    "email"
  ],
  "enabled": true,
  "updatedAt": "2026-08-21T15:03:00Z"
}

Ablauf ändern

PUT/procedures/{procedureId}

Ersetzt einen Ablauf vollständig.

Scope knowledge:write

Pfad-Parameter

procedureIdstringerforderlich: ID des Ablaufs.

Antwort

200 OK Der geänderte Ablauf.

Mögliche Fehler

404NOT_FOUNDDas angefragte Objekt existiert nicht oder gehört nicht zu Ihrer Verwaltung.

curl -X PUT "https://api.geniefy.de/v1/procedures/prc_W4n7Lx1" \
  -H "Authorization: Bearer $GENIEFY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Schlüsselverlust",
    "trigger": "Eine Person meldet, dass ein Haus- oder Wohnungsschlüssel verloren gegangen ist.",
    "steps": [
      "Objekt, Einheit und Art des Schlüssels erfragen.",
      "Darauf hinweisen, dass ein Ersatzschlüssel kostenpflichtig ist.",
      "Vorgang mit Kategorie Zugang anlegen und dem Objektbetreuer zuweisen."
    ],
    "channels": [
      "voice",
      "whatsapp"
    ],
    "enabled": true
  }'

Antwort 200 OK

{
  "procedureId": "prc_W4n7Lx1",
  "name": "Schlüsselverlust",
  "trigger": "Eine Person meldet, dass ein Haus- oder Wohnungsschlüssel verloren gegangen ist.",
  "steps": [
    "Objekt, Einheit und Art des Schlüssels erfragen.",
    "Darauf hinweisen, dass ein Ersatzschlüssel kostenpflichtig ist.",
    "Vorgang mit Kategorie Zugang anlegen und dem Objektbetreuer zuweisen."
  ],
  "channels": [
    "voice",
    "whatsapp"
  ],
  "enabled": true,
  "updatedAt": "2026-08-21T15:03:00Z"
}

Ablauf löschen

DELETE/procedures/{procedureId}

Löscht einen Ablauf.

Scope knowledge:write

Pfad-Parameter

procedureIdstringerforderlich: ID des Ablaufs.

Antwort

204 No Content Keine Antwort im Körper.

Mögliche Fehler

404NOT_FOUNDDas angefragte Objekt existiert nicht oder gehört nicht zu Ihrer Verwaltung.

curl -X DELETE "https://api.geniefy.de/v1/procedures/prc_W4n7Lx1" \
  -H "Authorization: Bearer $GENIEFY_API_KEY"

Agent

Name, Stimme, Begrüßung, Sprache und Verhalten Ihres Agenten sowie gesperrte Nummern. Das entspricht den Agent-Einstellungen im Dashboard.

Agent-Einstellungen abrufen

GET/agent/settings

Gibt Name, Stimme, Begrüßung und Verhalten Ihres Agenten zurück.

Scope agent:readMCP-Werkzeug get_agent_settings

Dieser Endpunkt erwartet keine Parameter.

Antwort

200 OK Die aktuellen Einstellungen.

curl "https://api.geniefy.de/v1/agent/settings" \
  -H "Authorization: Bearer $GENIEFY_API_KEY"

Antwort 200 OK

{
  "agentName": "Lena",
  "voiceId": "de-female-warm-2",
  "primaryLanguage": "de",
  "greeting": {
    "de": "Guten Tag, Sie sprechen mit Lena, der digitalen Assistentin der Hausverwaltung Muster.",
    "en": "Hello, you are speaking with Lena, the digital assistant of Hausverwaltung Muster."
  },
  "callRecordingConsent": true,
  "notificationEmail": "service@hv-muster.de",
  "fallbackPhone": "+498912345670",
  "voiceSpeed": 1,
  "voiceEmotion": "calm",
  "ambientNoise": {
    "enabled": false,
    "volume": 0.2
  },
  "transcriptionWords": [
    "WEG",
    "Hausgeld",
    "Sondereigentum"
  ],
  "pronunciations": [
    {
      "word": "WEG",
      "spokenAs": "W E G"
    }
  ],
  "updatedAt": "2026-09-10T08:00:00Z"
}

Agent-Einstellungen ändern

PATCH/agent/settings

Ändert nur die Felder, die Sie mitsenden. Änderungen gelten ab dem nächsten Anruf oder der nächsten Nachricht.

Scope agent:writeMCP-Werkzeug update_agent_settings

Anfragekörper

agentNamestring: Name, mit dem sich der Agent vorstellt.
voiceIdstring: Stimme aus GET /agent/voices.
greetingobject: Begrüßung je Sprache mit den Schlüsseln de und en.
primaryLanguagestring: Sprache, in der Gespräche beginnen.Werte: deen
callRecordingConsentboolean: Ob der Agent zu Beginn die Einwilligung zur Aufnahme einholt.
notificationEmailstring: Adresse für Zusammenfassungen und Hinweise.
fallbackPhonestring: Nummer, an die bei einer Störung durchgestellt wird.
voiceSpeednumber: Sprechtempo zwischen 0,8 und 1,2.
pronunciationsobject[]: Wörter mit Aussprache, jeweils word und spokenAs.

Antwort

200 OK Die vollständigen, aktualisierten Einstellungen.

curl -X PATCH "https://api.geniefy.de/v1/agent/settings" \
  -H "Authorization: Bearer $GENIEFY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "voiceSpeed": 0.95,
    "greeting": {
      "de": "Guten Tag, Sie sprechen mit Lena von der Hausverwaltung Muster. Wie kann ich helfen?"
    }
  }'

Antwort 200 OK

{
  "agentName": "Lena",
  "voiceId": "de-female-warm-2",
  "primaryLanguage": "de",
  "greeting": {
    "de": "Guten Tag, Sie sprechen mit Lena, der digitalen Assistentin der Hausverwaltung Muster.",
    "en": "Hello, you are speaking with Lena, the digital assistant of Hausverwaltung Muster."
  },
  "callRecordingConsent": true,
  "notificationEmail": "service@hv-muster.de",
  "fallbackPhone": "+498912345670",
  "voiceSpeed": 0.95,
  "voiceEmotion": "calm",
  "ambientNoise": {
    "enabled": false,
    "volume": 0.2
  },
  "transcriptionWords": [
    "WEG",
    "Hausgeld",
    "Sondereigentum"
  ],
  "pronunciations": [
    {
      "word": "WEG",
      "spokenAs": "W E G"
    }
  ],
  "updatedAt": "2026-09-10T08:00:00Z"
}

Stimmen auflisten

GET/agent/voices

Gibt die verfügbaren Stimmen mit einer kurzen Hörprobe zurück.

Scope agent:read

Query-Parameter

languagestring: Nur Stimmen dieser Sprache.Werte: deen

Antwort

200 OK Die Stimmen.

curl "https://api.geniefy.de/v1/agent/voices?language=de" \
  -H "Authorization: Bearer $GENIEFY_API_KEY"

Antwort 200 OK

{
  "voices": [
    {
      "voiceId": "de-female-warm-2",
      "name": "Lena",
      "language": "de",
      "style": "warm",
      "sampleUrl": "https://files.geniefy.de/voices/de-female-warm-2.mp3"
    }
  ]
}

Stimme probehören

POST/agent/voices/preview

Erzeugt eine Hörprobe mit Ihrem eigenen Text, etwa um eine neue Begrüßung zu prüfen.

Scope agent:read

Anfragekörper

textstringerforderlich: Text, höchstens 500 Zeichen.
voiceIdstringerforderlich: Die Stimme.
voiceSpeednumber: Sprechtempo zwischen 0,8 und 1,2.

Antwort

200 OK Ein Link auf die Audiodatei.

curl -X POST "https://api.geniefy.de/v1/agent/voices/preview" \
  -H "Authorization: Bearer $GENIEFY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "Guten Tag, Sie sprechen mit Lena von der Hausverwaltung Muster.",
    "voiceId": "de-female-warm-2"
  }'

Antwort 200 OK

{
  "audioUrl": "https://files.geniefy.de/tts/pv_81Kd.mp3?sig=…",
  "expiresAt": "2026-09-14T10:15:00Z"
}

Gesperrte Nummern auflisten

GET/agent/blocked-numbers

Gibt die Nummern zurück, deren Anrufe und Nachrichten der Agent nicht annimmt.

Scope agent:read

Dieser Endpunkt erwartet keine Parameter.

Antwort

200 OK Die gesperrten Nummern.

curl "https://api.geniefy.de/v1/agent/blocked-numbers" \
  -H "Authorization: Bearer $GENIEFY_API_KEY"

Antwort 200 OK

{
  "blockedNumbers": [
    {
      "phone": "+4930555000111",
      "reason": "Werbeanrufe",
      "createdAt": "2026-07-03T13:00:00Z"
    }
  ]
}

Nummer sperren

POST/agent/blocked-numbers

Sperrt eine Nummer für Anrufe und WhatsApp.

Scope agent:writeMCP-Werkzeug block_number

Anfragekörper

phonestringerforderlich: Nummer im Format E.164.
reasonstring: Interner Grund, sichtbar im Dashboard.

Antwort

201 Created Der Eintrag.

curl -X POST "https://api.geniefy.de/v1/agent/blocked-numbers" \
  -H "Authorization: Bearer $GENIEFY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "phone": "+4930555000111",
    "reason": "Werbeanrufe"
  }'

Antwort 201 Created

{
  "phone": "+4930555000111",
  "reason": "Werbeanrufe",
  "createdAt": "2026-09-14T10:20:00Z"
}

Nummer entsperren

DELETE/agent/blocked-numbers/{phone}

Hebt die Sperre einer Nummer auf.

Scope agent:write

Pfad-Parameter

phonestringerforderlich: Nummer im Format E.164.

Antwort

204 No Content Keine Antwort im Körper.

Mögliche Fehler

404NOT_FOUNDDas angefragte Objekt existiert nicht oder gehört nicht zu Ihrer Verwaltung.

curl -X DELETE "https://api.geniefy.de/v1/agent/blocked-numbers/%2B4930555000111" \
  -H "Authorization: Bearer $GENIEFY_API_KEY"

Weiterleitung

Öffnungszeiten, Feiertage und die Regeln, nach denen Anrufe an Ihr Team, den Beirat oder den Notdienst durchgestellt werden.

Weiterleitung abrufen

GET/forwarding

Gibt Öffnungszeiten, Feiertagsregelung und alle Weiterleitungsregeln zurück.

Scope forwarding:readMCP-Werkzeug get_forwarding

Dieser Endpunkt erwartet keine Parameter.

Antwort

200 OK Die Konfiguration.

curl "https://api.geniefy.de/v1/forwarding" \
  -H "Authorization: Bearer $GENIEFY_API_KEY"

Antwort 200 OK

{
  "version": 7,
  "openingHours": {
    "timezone": "Europe/Berlin",
    "monday": {
      "open": true,
      "from": "08:00",
      "to": "17:00"
    },
    "tuesday": {
      "open": true,
      "from": "08:00",
      "to": "17:00"
    },
    "wednesday": {
      "open": true,
      "from": "08:00",
      "to": "17:00"
    },
    "thursday": {
      "open": true,
      "from": "08:00",
      "to": "17:00"
    },
    "friday": {
      "open": true,
      "from": "08:00",
      "to": "13:00"
    },
    "saturday": {
      "open": false
    },
    "sunday": {
      "open": false
    }
  },
  "holidays": {
    "region": "BY",
    "closedOnHolidays": true,
    "openOn": []
  },
  "rules": [
    {
      "ruleId": "rl_Emergency1",
      "kind": "role",
      "enabled": true,
      "roles": [
        "tenant",
        "owner"
      ],
      "trigger": "emergency",
      "target": "+498912345699",
      "window": "always"
    },
    {
      "ruleId": "rl_Board2",
      "kind": "role",
      "enabled": true,
      "roles": [
        "advisoryBoard"
      ],
      "trigger": "any",
      "target": "+498912345677",
      "window": "openingHours"
    },
    {
      "ruleId": "rl_Vip3",
      "kind": "vip",
      "enabled": true,
      "callers": [
        "+4915199990789"
      ],
      "target": "+498912345671",
      "window": "openingHours"
    }
  ],
  "updatedAt": "2026-09-02T07:45:00Z"
}

Weiterleitung ersetzen

PUT/forwarding

Ersetzt die gesamte Konfiguration. Senden Sie die version, die Sie zuletzt gelesen haben. Hat sich die Konfiguration inzwischen geändert, antwortet die API mit 409 VERSION_CONFLICT, und nichts wird überschrieben.

Scope forwarding:write

Anfragekörper

versionintegererforderlich: Zuletzt gelesene Version.
openingHoursobjecterforderlich: Öffnungszeiten je Wochentag mit open, from und to.
holidaysobjecterforderlich: Bundesland als region und ob an Feiertagen geschlossen ist.
rulesobject[]erforderlich: Höchstens 40 Regeln. Regeln werden von oben nach unten geprüft.

Antwort

200 OK Die gespeicherte Konfiguration.

Mögliche Fehler

409VERSION_CONFLICTDie Konfiguration wurde seit Ihrem letzten Lesen geändert.

curl -X PUT "https://api.geniefy.de/v1/forwarding" \
  -H "Authorization: Bearer $GENIEFY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "version": 7,
    "openingHours": {
      "timezone": "Europe/Berlin",
      "monday": {
        "open": true,
        "from": "08:00",
        "to": "17:00"
      },
      "tuesday": {
        "open": true,
        "from": "08:00",
        "to": "17:00"
      },
      "wednesday": {
        "open": true,
        "from": "08:00",
        "to": "17:00"
      },
      "thursday": {
        "open": true,
        "from": "08:00",
        "to": "17:00"
      },
      "friday": {
        "open": true,
        "from": "08:00",
        "to": "13:00"
      },
      "saturday": {
        "open": false
      },
      "sunday": {
        "open": false
      }
    },
    "holidays": {
      "region": "BY",
      "closedOnHolidays": true,
      "openOn": []
    },
    "rules": [
      {
        "ruleId": "rl_Emergency1",
        "kind": "role",
        "enabled": true,
        "roles": [
          "tenant",
          "owner"
        ],
        "trigger": "emergency",
        "target": "+498912345699",
        "window": "always"
      }
    ]
  }'

Antwort 200 OK

{
  "version": 8,
  "openingHours": {
    "timezone": "Europe/Berlin",
    "monday": {
      "open": true,
      "from": "08:00",
      "to": "17:00"
    },
    "tuesday": {
      "open": true,
      "from": "08:00",
      "to": "17:00"
    },
    "wednesday": {
      "open": true,
      "from": "08:00",
      "to": "17:00"
    },
    "thursday": {
      "open": true,
      "from": "08:00",
      "to": "17:00"
    },
    "friday": {
      "open": true,
      "from": "08:00",
      "to": "13:00"
    },
    "saturday": {
      "open": false
    },
    "sunday": {
      "open": false
    }
  },
  "holidays": {
    "region": "BY",
    "closedOnHolidays": true,
    "openOn": []
  },
  "rules": [
    {
      "ruleId": "rl_Emergency1",
      "kind": "role",
      "enabled": true,
      "roles": [
        "tenant",
        "owner"
      ],
      "trigger": "emergency",
      "target": "+498912345699",
      "window": "always"
    }
  ],
  "updatedAt": "2026-09-02T07:45:00Z"
}

Weiterleitungsregel anlegen

POST/forwarding/rules

Fügt eine Regel am Ende der Liste hinzu. kind bestimmt die Art: role leitet nach Rolle und Anliegen weiter, vip leitet bestimmte Nummern immer durch, pin stellt nach Eingabe einer PIN durch.

Scope forwarding:write

Anfragekörper

kindstringerforderlich: Art der Regel.Werte: rolevippin
targetstringerforderlich: Zielnummer im Format E.164.
windowstring: Wann die Regel gilt.Werte: alwaysopeningHoursoutsideOpeningHoursStandard: always
rolesstring[]: Bei role: Rollen, für die die Regel gilt.
triggerstring: Bei role: any oder emergency.
callersstring[]: Bei vip: bis zu 50 Nummern.

Antwort

201 Created Die neue Regel.

curl -X POST "https://api.geniefy.de/v1/forwarding/rules" \
  -H "Authorization: Bearer $GENIEFY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "kind": "role",
    "roles": [
      "serviceProvider"
    ],
    "trigger": "any",
    "target": "+498912345672",
    "window": "openingHours"
  }'

Antwort 201 Created

{
  "ruleId": "rl_Svc4",
  "kind": "role",
  "enabled": true,
  "roles": [
    "serviceProvider"
  ],
  "trigger": "any",
  "target": "+498912345672",
  "window": "openingHours"
}

Weiterleitungsregel löschen

DELETE/forwarding/rules/{ruleId}

Entfernt eine Regel.

Scope forwarding:write

Pfad-Parameter

ruleIdstringerforderlich: ID der Regel.

Antwort

204 No Content Keine Antwort im Körper.

Mögliche Fehler

404NOT_FOUNDDas angefragte Objekt existiert nicht oder gehört nicht zu Ihrer Verwaltung.

curl -X DELETE "https://api.geniefy.de/v1/forwarding/rules/rl_Svc4" \
  -H "Authorization: Bearer $GENIEFY_API_KEY"

Integrationen

Die Verbindung zu casavi, Facilioo oder DoNexus und welche Funktionen darüber laufen.

Anbindung abrufen

GET/integrations

Gibt zurück, mit welchem System Geniefy verbunden ist und welche Funktionen aktiv sind.

Scope integrations:read

Dieser Endpunkt erwartet keine Parameter.

Antwort

200 OK Die Anbindung.

curl "https://api.geniefy.de/v1/integrations" \
  -H "Authorization: Bearer $GENIEFY_API_KEY"

Antwort 200 OK

{
  "integrationType": "casavi",
  "status": "connected",
  "features": {
    "createTickets": true,
    "assignTickets": true,
    "lookupDocuments": true,
    "identifyCallers": true,
    "readOwnersMeetings": true
  },
  "connectedAt": "2026-05-12T09:00:00Z",
  "lastSyncAt": "2026-09-14T08:00:00Z"
}

Anbindung konfigurieren

PUT/integrations

Legt das System und die aktiven Funktionen fest. Zugangsdaten werden verschlüsselt gespeichert und nie wieder ausgegeben. Mit geniefy verwaltet Geniefy Kontakte und Vorgänge selbst.

Scope integrations:write

Anfragekörper

integrationTypestringerforderlich: Das angebundene System.Werte: geniefycasavifacilioodonexus
featuresobject: Funktionen, die ein- oder ausgeschaltet werden.
credentialsobject: Zugangsdaten des Systems, zum Beispiel ein API-Token.

Antwort

200 OK Die gespeicherte Anbindung.

curl -X PUT "https://api.geniefy.de/v1/integrations" \
  -H "Authorization: Bearer $GENIEFY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "integrationType": "casavi",
    "features": {
      "createTickets": true,
      "lookupDocuments": true
    },
    "credentials": {
      "apiToken": "cas_…"
    }
  }'

Antwort 200 OK

{
  "integrationType": "casavi",
  "status": "pending",
  "features": {
    "createTickets": true,
    "assignTickets": true,
    "lookupDocuments": true,
    "identifyCallers": true,
    "readOwnersMeetings": true
  },
  "connectedAt": "2026-05-12T09:00:00Z",
  "lastSyncAt": "2026-09-14T08:00:00Z"
}

Anbindung testen

POST/integrations/test

Prüft Verbindung und Berechtigungen, ohne Daten zu verändern.

Scope integrations:write

Dieser Endpunkt erwartet keine Parameter.

Antwort

200 OK Das Ergebnis jeder Prüfung.

curl -X POST "https://api.geniefy.de/v1/integrations/test" \
  -H "Authorization: Bearer $GENIEFY_API_KEY"

Antwort 200 OK

{
  "ok": true,
  "latencyMs": 212,
  "checks": [
    {
      "check": "authentication",
      "ok": true
    },
    {
      "check": "tickets.write",
      "ok": true
    },
    {
      "check": "documents.read",
      "ok": true
    }
  ]
}

Kontakte und Objekte

Die Personen, Objekte und Einheiten, mit denen der Agent Anrufende erkennt und Anliegen zuordnet.

Das Contact-Objekt8 Felder

Eine Person, die mit Ihrer Verwaltung in Kontakt steht.

contactIdstring: Eindeutige ID.
namestring: Vollständiger Name.
rolestring: tenant, owner, advisoryBoard, serviceProvider oder prospect.
phonesstring[]: Telefonnummern im Format E.164.
emailsstring[]: E-Mail-Adressen.
buildingIdstringkann null sein: Objekt.
unitIdsstring[]: Einheiten.
sourcestring: Herkunft des Datensatzes: geniefy oder das angebundene System.

Kontakte auflisten

GET/contacts

Gibt Mieter, Eigentümer, Beiräte und Dienstleister zurück. Ist casavi, Facilioo oder DoNexus angebunden, kommen die Kontakte aus diesem System, und source nennt es.

Scope contacts:read

Query-Parameter

rolestring: Nur Kontakte mit dieser Rolle.Werte: tenantowneradvisoryBoardserviceProviderprospect
building_idstring: Nur Kontakte in diesem Objekt.
querystring: Sucht in Name, Telefonnummer und E-Mail-Adresse.
sortstring: Sortierung der Liste.Werte: nameupdatedStandard: name
limitinteger: Höchstzahl der zurückgegebenen Einträge, zwischen 1 und 100. Hat keinen Einfluss auf total.Standard: 20
cursorstring: Der Wert nextCursor der vorherigen Seite.

Antwort

200 OK Eine Seite mit Kontakten.

curl "https://api.geniefy.de/v1/contacts?role=owner" \
  -H "Authorization: Bearer $GENIEFY_API_KEY"

Antwort 200 OK

{
  "contacts": [
    {
      "contactId": "ct_5Pz1rQ8",
      "name": "Jonas Weber",
      "role": "tenant",
      "phones": [
        "+4915199990456"
      ],
      "emails": [
        "jonas.weber@example.de"
      ],
      "buildingId": "bld_Linden12",
      "unitIds": [
        "unit_Linden12_WE04"
      ],
      "notes": "Bevorzugt WhatsApp.",
      "source": "geniefy",
      "updatedAt": "2026-08-30T12:00:00Z"
    }
  ],
  "total": 1308,
  "nextCursor": "eyJvIjoyMH0"
}

Kontakt per Nummer finden

GET/contacts/lookup

Findet Kontakte zu einer Telefonnummer, unabhängig von Schreibweise und Leerzeichen.

Scope contacts:readMCP-Werkzeug lookup_contact

Query-Parameter

phonestringerforderlich: Die Telefonnummer.

Antwort

200 OK Passende Kontakte, oft genau einer.

curl "https://api.geniefy.de/v1/contacts/lookup?phone=%2B4915199990456" \
  -H "Authorization: Bearer $GENIEFY_API_KEY"

Antwort 200 OK

{
  "contacts": [
    {
      "contactId": "ct_5Pz1rQ8",
      "name": "Jonas Weber",
      "role": "tenant",
      "phones": [
        "+4915199990456"
      ],
      "emails": [
        "jonas.weber@example.de"
      ],
      "buildingId": "bld_Linden12",
      "unitIds": [
        "unit_Linden12_WE04"
      ],
      "notes": "Bevorzugt WhatsApp.",
      "source": "geniefy",
      "updatedAt": "2026-08-30T12:00:00Z"
    }
  ]
}

Kontakt anlegen

POST/contacts

Legt einen Kontakt an. Nur verfügbar, wenn Geniefy die Kontakte selbst verwaltet.

Scope contacts:write

Anfragekörper

namestringerforderlich: Vollständiger Name.
rolestringerforderlich: Rolle des Kontakts.Werte: tenantowneradvisoryBoardserviceProviderprospect
phonesstring[]: Telefonnummern im Format E.164.
emailsstring[]: E-Mail-Adressen.
buildingIdstring: Objekt des Kontakts.
unitIdsstring[]: Einheiten des Kontakts.
notesstring: Interne Notiz, die der Agent kennt.

Antwort

201 Created Der neue Kontakt.

Mögliche Fehler

409MANAGED_BY_CONNECTED_SYSTEMKontakte werden im angebundenen System gepflegt und lassen sich hier nicht ändern.

curl -X POST "https://api.geniefy.de/v1/contacts" \
  -H "Authorization: Bearer $GENIEFY_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Jonas Weber",
    "role": "tenant",
    "phones": [
      "+4915199990456"
    ],
    "emails": [
      "jonas.weber@example.de"
    ],
    "buildingId": "bld_Linden12",
    "unitIds": [
      "unit_Linden12_WE04"
    ],
    "notes": "Bevorzugt WhatsApp."
  }'

Antwort 201 Created

{
  "contactId": "ct_5Pz1rQ8",
  "name": "Jonas Weber",
  "role": "tenant",
  "phones": [
    "+4915199990456"
  ],
  "emails": [
    "jonas.weber@example.de"
  ],
  "buildingId": "bld_Linden12",
  "unitIds": [
    "unit_Linden12_WE04"
  ],
  "notes": "Bevorzugt WhatsApp.",
  "source": "geniefy",
  "updatedAt": "2026-08-30T12:00:00Z"
}

Kontakt ändern

PUT/contacts/{contactId}

Ersetzt einen Kontakt vollständig.

Scope contacts:write

Pfad-Parameter

contactIdstringerforderlich: ID des Kontakts.

Antwort

200 OK Der geänderte Kontakt.

Mögliche Fehler

404NOT_FOUNDDas angefragte Objekt existiert nicht oder gehört nicht zu Ihrer Verwaltung.
409MANAGED_BY_CONNECTED_SYSTEMKontakte werden im angebundenen System gepflegt und lassen sich hier nicht ändern.

curl -X PUT "https://api.geniefy.de/v1/contacts/ct_5Pz1rQ8" \
  -H "Authorization: Bearer $GENIEFY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Jonas Weber",
    "role": "tenant",
    "phones": [
      "+4915199990456"
    ],
    "emails": [
      "jonas.weber@example.de"
    ],
    "buildingId": "bld_Linden12",
    "unitIds": [
      "unit_Linden12_WE04"
    ],
    "notes": "Bevorzugt WhatsApp, tagsüber nicht erreichbar."
  }'

Antwort 200 OK

{
  "contactId": "ct_5Pz1rQ8",
  "name": "Jonas Weber",
  "role": "tenant",
  "phones": [
    "+4915199990456"
  ],
  "emails": [
    "jonas.weber@example.de"
  ],
  "buildingId": "bld_Linden12",
  "unitIds": [
    "unit_Linden12_WE04"
  ],
  "notes": "Bevorzugt WhatsApp, tagsüber nicht erreichbar.",
  "source": "geniefy",
  "updatedAt": "2026-08-30T12:00:00Z"
}

Kontakt löschen

DELETE/contacts/{contactId}

Löscht einen Kontakt. Vergangene Anrufe bleiben erhalten.

Scope contacts:write

Pfad-Parameter

contactIdstringerforderlich: ID des Kontakts.

Antwort

204 No Content Keine Antwort im Körper.

Mögliche Fehler

404NOT_FOUNDDas angefragte Objekt existiert nicht oder gehört nicht zu Ihrer Verwaltung.
409MANAGED_BY_CONNECTED_SYSTEMKontakte werden im angebundenen System gepflegt und lassen sich hier nicht ändern.

curl -X DELETE "https://api.geniefy.de/v1/contacts/ct_5Pz1rQ8" \
  -H "Authorization: Bearer $GENIEFY_API_KEY"

Kontakte importieren

POST/contacts/import

Legt bis zu 1.000 Kontakte in einer Anfrage an oder aktualisiert sie. Ungültige Einträge werden übersprungen und in errors mit ihrer Position gemeldet.

Scope contacts:write

Anfragekörper

contactsobject[]erforderlich: Die Kontakte im Format von POST /contacts.

Antwort

200 OK Zusammenfassung des Imports.

curl -X POST "https://api.geniefy.de/v1/contacts/import" \
  -H "Authorization: Bearer $GENIEFY_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "contacts": [
      {
        "name": "Jonas Weber",
        "role": "tenant",
        "phones": [
          "+4915199990456"
        ]
      },
      {
        "name": "Petra Lang",
        "role": "owner",
        "phones": [
          "01519999"
        ]
      }
    ]
  }'

Antwort 200 OK

{
  "imported": 1,
  "errors": [
    {
      "index": 1,
      "code": "INVALID_PHONE",
      "field": "phones[0]",
      "message": "Phone number must be in E.164 format."
    }
  ]
}

Objekte auflisten

GET/buildings

Gibt die verwalteten Objekte zurück.

Scope contacts:read

Query-Parameter

limitinteger: Höchstzahl der zurückgegebenen Einträge, zwischen 1 und 100. Hat keinen Einfluss auf total.Standard: 20
cursorstring: Der Wert nextCursor der vorherigen Seite.

Antwort

200 OK Eine Seite mit Objekten.

curl "https://api.geniefy.de/v1/buildings" \
  -H "Authorization: Bearer $GENIEFY_API_KEY"

Antwort 200 OK

{
  "buildings": [
    {
      "buildingId": "bld_Linden12",
      "label": "Lindenstraße 12",
      "address": "Lindenstraße 12, 80331 München",
      "type": "weg",
      "unitCount": 24
    }
  ],
  "total": 63,
  "nextCursor": "eyJvIjoyMH0"
}

Einheiten eines Objekts

GET/buildings/{buildingId}/units

Gibt Wohnungen, Gewerbeeinheiten und Stellplätze eines Objekts zurück.

Scope contacts:read

Pfad-Parameter

buildingIdstringerforderlich: ID des Objekts.

Antwort

200 OK Die Einheiten.

Mögliche Fehler

404NOT_FOUNDDas angefragte Objekt existiert nicht oder gehört nicht zu Ihrer Verwaltung.

curl "https://api.geniefy.de/v1/buildings/bld_Linden12/units" \
  -H "Authorization: Bearer $GENIEFY_API_KEY"

Antwort 200 OK

{
  "units": [
    {
      "unitId": "unit_Linden12_WE04",
      "label": "WE 04",
      "type": "apartment",
      "floor": "1. OG",
      "areaSqm": 68.5
    }
  ]
}

AufgabenBeta

Wenn eine Aktion eine menschliche Freigabe braucht, schlägt der Agent sie als Aufgabe vor. Sie prüfen den Vorschlag, korrigieren ihn bei Bedarf und geben ihn frei.

Aufgaben auflisten

GET/tasks

Gibt Aufgaben zurück, die der Agent vorgeschlagen hat, etwa einen Vorgang anzulegen oder eine E-Mail an einen Dienstleister zu senden. Aufgaben mit pending_review warten auf Ihre Freigabe.

Scope tasks:readMCP-Werkzeug list_tasks

Query-Parameter

statusstring: Nur Aufgaben mit diesem Status.Werte: pending_reviewapprovedrejectedexecutedfailedexpired
typestring: Nur Aufgaben dieses Typs.Werte: ticket.createemail.outboundcall.outbound
limitinteger: Höchstzahl der zurückgegebenen Einträge, zwischen 1 und 100. Hat keinen Einfluss auf total.Standard: 20
cursorstring: Der Wert nextCursor der vorherigen Seite.

Antwort

200 OK Eine Seite mit Aufgaben.

curl "https://api.geniefy.de/v1/tasks?status=pending_review" \
  -H "Authorization: Bearer $GENIEFY_API_KEY"

Antwort 200 OK

{
  "tasks": [
    {
      "taskId": "tsk_8Rv2Kq4",
      "type": "ticket.create",
      "status": "pending_review",
      "revision": 1,
      "payload": {
        "system": "casavi",
        "title": "Heizung im Bad ohne Funktion",
        "description": "Mieterin meldet seit gestern kalten Heizkörper im Bad, übrige Räume warm.",
        "category": "Repairs",
        "priority": "normal",
        "contractor": "Heizungsbau Huber"
      },
      "evidence": {
        "callId": "AJ_7tQm2KxV9pLr4",
        "building": "Lindenstraße 12",
        "unit": "WE 04"
      },
      "expiresAt": "2026-09-17T08:28:30Z",
      "createdAt": "2026-09-14T08:29:05Z"
    }
  ],
  "total": 6,
  "nextCursor": null
}

Aufgabe abrufen

GET/tasks/{taskId}

Gibt eine Aufgabe mit Vorschlag, Belegen und Verlauf zurück.

Scope tasks:read

Pfad-Parameter

taskIdstringerforderlich: ID der Aufgabe.

Antwort

200 OK Die Aufgabe.

Mögliche Fehler

404NOT_FOUNDDas angefragte Objekt existiert nicht oder gehört nicht zu Ihrer Verwaltung.

curl "https://api.geniefy.de/v1/tasks/tsk_8Rv2Kq4" \
  -H "Authorization: Bearer $GENIEFY_API_KEY"

Antwort 200 OK

{
  "taskId": "tsk_8Rv2Kq4",
  "type": "ticket.create",
  "status": "pending_review",
  "revision": 1,
  "payload": {
    "system": "casavi",
    "title": "Heizung im Bad ohne Funktion",
    "description": "Mieterin meldet seit gestern kalten Heizkörper im Bad, übrige Räume warm.",
    "category": "Repairs",
    "priority": "normal",
    "contractor": "Heizungsbau Huber"
  },
  "evidence": {
    "callId": "AJ_7tQm2KxV9pLr4",
    "building": "Lindenstraße 12",
    "unit": "WE 04"
  },
  "expiresAt": "2026-09-17T08:28:30Z",
  "createdAt": "2026-09-14T08:29:05Z",
  "events": [
    {
      "type": "proposed",
      "actor": "agent",
      "createdAt": "2026-09-14T08:29:05Z"
    }
  ]
}

Aufgabe freigeben oder ablehnen

POST/tasks/{taskId}/decision

Gibt eine Aufgabe frei oder lehnt sie ab. Beim Freigeben können Sie einzelne Felder in fields korrigieren. Senden Sie expectedRevision, damit nicht zwei Personen dieselbe Aufgabe gleichzeitig entscheiden. Freigegebene Aufgaben werden sofort ausgeführt.

Scope tasks:writeMCP-Werkzeug decide_task

Pfad-Parameter

taskIdstringerforderlich: ID der Aufgabe.

Anfragekörper

decisionstringerforderlich: Die Entscheidung.Werte: approvereject
expectedRevisionintegererforderlich: Die revision, die Sie zuletzt gesehen haben.
fieldsobject: Korrigierte Felder des Vorschlags.
reasonstring: Begründung bei einer Ablehnung.

Antwort

200 OK Die entschiedene Aufgabe.

Mögliche Fehler

404NOT_FOUNDDas angefragte Objekt existiert nicht oder gehört nicht zu Ihrer Verwaltung.
409REVISION_CONFLICTDie Aufgabe wurde inzwischen von jemand anderem geändert.

curl -X POST "https://api.geniefy.de/v1/tasks/tsk_8Rv2Kq4/decision" \
  -H "Authorization: Bearer $GENIEFY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "decision": "approve",
    "expectedRevision": 1,
    "fields": {
      "priority": "high"
    }
  }'

Antwort 200 OK

{
  "taskId": "tsk_8Rv2Kq4",
  "type": "ticket.create",
  "status": "executed",
  "revision": 2,
  "payload": {
    "system": "casavi",
    "title": "Heizung im Bad ohne Funktion",
    "description": "Mieterin meldet seit gestern kalten Heizkörper im Bad, übrige Räume warm.",
    "category": "Repairs",
    "priority": "high",
    "contractor": "Heizungsbau Huber"
  },
  "evidence": {
    "callId": "AJ_7tQm2KxV9pLr4",
    "building": "Lindenstraße 12",
    "unit": "WE 04"
  },
  "expiresAt": "2026-09-17T08:28:30Z",
  "createdAt": "2026-09-14T08:29:05Z",
  "execution": {
    "result": {
      "ticketId": "casavi:TK-20931"
    }
  }
}

Auswertungen

Die Kennzahlen aus dem Bereich Auswertungen im Dashboard: Volumen, Themen, Objekte und Entwicklung über die Zeit.

Zusammenfassung abrufen

GET/insights/summary

Gibt die Kennzahlen eines Zeitraums zurück: Volumen je Kanal, Verteilung nach Kategorien und Wochentagen, Anteil außerhalb der Öffnungszeiten, angelegte Vorgänge und weitergeleitete Notfälle. Ohne Zeitraum gelten die letzten 30 Tage.

Scope insights:readMCP-Werkzeug get_insights_summary

Query-Parameter

start_datestring: Erster Tag des Zeitraums im Format YYYY-MM-DD, inklusive.
end_datestring: Letzter Tag des Zeitraums im Format YYYY-MM-DD, inklusive.
channelstring: Nur diesen Kanal auswerten.Werte: voicewhatsappemail

Antwort

200 OK Die Kennzahlen.

Mögliche Fehler

400INVALID_DATE_FORMATEin Datum hat nicht das Format YYYY-MM-DD.
400INVALID_DATE_RANGEstart_date liegt nach end_date.

curl "https://api.geniefy.de/v1/insights/summary?start_date=2026-09-01&end_date=2026-09-14" \
  -H "Authorization: Bearer $GENIEFY_API_KEY"

Antwort 200 OK

{
  "period": {
    "startDate": "2026-09-01",
    "endDate": "2026-09-14"
  },
  "totals": {
    "calls": 612,
    "whatsappConversations": 188,
    "emails": 243,
    "callMinutes": 1486.5
  },
  "byCategory": [
    {
      "category": "Repairs",
      "count": 214,
      "share": 0.35
    },
    {
      "category": "Accounting",
      "count": 97,
      "share": 0.158
    },
    {
      "category": "Emergency",
      "count": 12,
      "share": 0.02
    }
  ],
  "byWeekday": {
    "monday": 138,
    "tuesday": 121,
    "wednesday": 104,
    "thursday": 99,
    "friday": 96,
    "saturday": 31,
    "sunday": 23
  },
  "outsideOpeningHoursShare": 0.27,
  "ticketsCreated": 301,
  "emergenciesForwarded": {
    "total": 12,
    "connected": 11
  },
  "callbacksOpen": 9
}

Auswertung nach Objekten

GET/insights/buildings

Zeigt, aus welchen Objekten und Einheiten die meisten Anfragen kommen und worum es geht.

Scope insights:read

Query-Parameter

start_datestring: Erster Tag des Zeitraums im Format YYYY-MM-DD, inklusive.
end_datestring: Letzter Tag des Zeitraums im Format YYYY-MM-DD, inklusive.
limitinteger: Höchstzahl der zurückgegebenen Einträge, zwischen 1 und 100. Hat keinen Einfluss auf total.Standard: 10

Antwort

200 OK Objekte, meiste Anfragen zuerst.

curl "https://api.geniefy.de/v1/insights/buildings" \
  -H "Authorization: Bearer $GENIEFY_API_KEY"

Antwort 200 OK

{
  "buildings": [
    {
      "buildingId": "bld_Linden12",
      "label": "Lindenstraße 12",
      "requests": 48,
      "topCategory": "Repairs",
      "topUnits": [
        {
          "unitId": "unit_Linden12_WE04",
          "label": "WE 04",
          "requests": 9
        }
      ]
    }
  ]
}

Verlauf einer Kategorie

GET/insights/categories/{category}

Gibt die monatliche Entwicklung einer Kategorie und ihrer Unterkategorien zurück, etwa um steigende Reparaturthemen zu erkennen.

Scope insights:read

Pfad-Parameter

categorystringerforderlich: Kategorie-Schlüssel aus GET /categories.

Query-Parameter

monthsinteger: Anzahl der Monate bis heute, höchstens 24.Standard: 6

Antwort

200 OK Der Verlauf je Monat.

curl "https://api.geniefy.de/v1/insights/categories/Repairs?months=6" \
  -H "Authorization: Bearer $GENIEFY_API_KEY"

Antwort 200 OK

{
  "category": "Repairs",
  "months": [
    {
      "month": "2026-08",
      "count": 402,
      "subcategories": {
        "Heating": 31,
        "Plumbing": 88,
        "WaterDamage": 40
      }
    },
    {
      "month": "2026-09",
      "count": 214,
      "subcategories": {
        "Heating": 44,
        "Plumbing": 39,
        "WaterDamage": 21
      }
    }
  ]
}

Abrechnung

Verbrauch des laufenden Monats, Rechnungsdaten und Rechnungen als PDF.

Verbrauch abrufen

GET/billing/usage

Gibt Gesprächsminuten und WhatsApp-Sitzungen eines Monats zurück, dazu die voraussichtliche Summe netto.

Scope billing:readMCP-Werkzeug get_usage

Query-Parameter

monthstring: Monat im Format YYYY-MM, Standard ist der laufende Monat.

Antwort

200 OK Der Verbrauch.

curl "https://api.geniefy.de/v1/billing/usage?month=2026-09" \
  -H "Authorization: Bearer $GENIEFY_API_KEY"

Antwort 200 OK

{
  "month": "2026-09",
  "plan": "plus",
  "voice": {
    "minutesIncluded": 200,
    "minutesUsed": 1486.5,
    "pricePerMinute": 0.5,
    "currency": "EUR"
  },
  "whatsapp": {
    "sessionsIncluded": 150,
    "sessionsUsed": 188,
    "pricePerExtraSession": 0.4,
    "currency": "EUR"
  },
  "estimatedTotal": {
    "net": 818.45,
    "currency": "EUR"
  }
}

Rechnungsdaten abrufen

GET/billing/details

Gibt Rechnungsanschrift, Rechnungs-E-Mail, Umsatzsteuer-ID und Zahlungsart zurück.

Scope billing:read

Dieser Endpunkt erwartet keine Parameter.

Antwort

200 OK Die Rechnungsdaten.

curl "https://api.geniefy.de/v1/billing/details" \
  -H "Authorization: Bearer $GENIEFY_API_KEY"

Antwort 200 OK

{
  "companyName": "Hausverwaltung Muster GmbH",
  "billingEmail": "buchhaltung@hv-muster.de",
  "address": {
    "street": "Musterweg 3",
    "postalCode": "80331",
    "city": "München",
    "country": "DE"
  },
  "vatId": "DE123456789",
  "purchaseOrder": null,
  "paymentMethod": "sepa_debit"
}

Rechnungsdaten ändern

PATCH/billing/details

Ändert nur die Felder, die Sie mitsenden. Die Änderung gilt ab der nächsten Rechnung.

Scope billing:write

Anfragekörper

companyNamestring: Firmenname auf der Rechnung.
billingEmailstring: Adresse, an die Rechnungen gehen.
addressobject: Anschrift mit street, postalCode, city und country.
vatIdstring: Umsatzsteuer-Identifikationsnummer.
purchaseOrderstring: Bestellnummer, die auf jeder Rechnung erscheint.

Antwort

200 OK Die vollständigen Rechnungsdaten.

curl -X PATCH "https://api.geniefy.de/v1/billing/details" \
  -H "Authorization: Bearer $GENIEFY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "billingEmail": "rechnungen@hv-muster.de",
    "purchaseOrder": "PO-2026-118"
  }'

Antwort 200 OK

{
  "companyName": "Hausverwaltung Muster GmbH",
  "billingEmail": "rechnungen@hv-muster.de",
  "address": {
    "street": "Musterweg 3",
    "postalCode": "80331",
    "city": "München",
    "country": "DE"
  },
  "vatId": "DE123456789",
  "purchaseOrder": "PO-2026-118",
  "paymentMethod": "sepa_debit"
}

Rechnungen auflisten

GET/billing/invoices

Gibt Ihre Rechnungen mit Link auf das PDF zurück, neueste zuerst.

Scope billing:readMCP-Werkzeug list_invoices

Query-Parameter

limitinteger: Höchstzahl der zurückgegebenen Einträge, zwischen 1 und 100. Hat keinen Einfluss auf total.Standard: 20
cursorstring: Der Wert nextCursor der vorherigen Seite.

Antwort

200 OK Eine Seite mit Rechnungen.

curl "https://api.geniefy.de/v1/billing/invoices" \
  -H "Authorization: Bearer $GENIEFY_API_KEY"

Antwort 200 OK

{
  "invoices": [
    {
      "invoiceId": "inv_2026_08",
      "number": "GF-2026-0812",
      "periodStart": "2026-08-01",
      "periodEnd": "2026-08-31",
      "total": {
        "net": 874.2,
        "gross": 1040.3,
        "currency": "EUR"
      },
      "status": "paid",
      "issuedAt": "2026-09-01T06:00:00Z",
      "pdfUrl": "https://files.geniefy.de/inv/GF-2026-0812.pdf?sig=…"
    }
  ],
  "total": 5,
  "nextCursor": null
}

Verbundene SystemeBeta

Geniefy liegt als Betriebsebene über CRM, ERP und DMS Ihrer Verwaltung. Diese Endpunkte greifen über Geniefy auf die angebundenen Systeme zu: in einem einheitlichen Format, egal ob die Daten aus casavi, Facilioo oder DoNexus kommen.

Verbundene Systeme auflisten

GET/systems

Gibt die angebundenen CRM-, ERP- und DMS-Systeme mit ihren verfügbaren Fähigkeiten zurück.

Scope systems:read

Dieser Endpunkt erwartet keine Parameter.

Antwort

200 OK Die Systeme.

curl "https://api.geniefy.de/v1/systems" \
  -H "Authorization: Bearer $GENIEFY_API_KEY"

Antwort 200 OK

{
  "systems": [
    {
      "systemId": "casavi",
      "kind": [
        "crm",
        "dms"
      ],
      "status": "connected",
      "capabilities": [
        "tickets.read",
        "tickets.write",
        "documents.read",
        "units.read",
        "owners.read"
      ]
    },
    {
      "systemId": "donexus",
      "kind": [
        "erp"
      ],
      "status": "connected",
      "capabilities": [
        "units.read",
        "tenants.read",
        "balances.read"
      ]
    }
  ]
}

Systeme in Sprache abfragen

POST/systems/query

Stellt eine Frage in natürlicher Sprache an alle angebundenen Systeme. Geniefy entscheidet, welche Systeme abgefragt werden, führt die Abfragen aus und gibt eine Antwort mit den gefundenen Datensätzen zurück. Jeder Datensatz nennt seine Quelle, damit Sie die Antwort prüfen können.

Scope systems:readMCP-Werkzeug query_systems

Anfragekörper

questionstringerforderlich: Die Frage in ganzen Sätzen.
systemsstring[]: Nur diese Systeme abfragen.
maxRecordsinteger: Höchstzahl der zurückgegebenen Datensätze, Standard 20.

Antwort

200 OK Antwort mit Belegen.

Mögliche Fehler

502SYSTEM_UNAVAILABLEDas angebundene System hat nicht oder fehlerhaft geantwortet.

curl -X POST "https://api.geniefy.de/v1/systems/query" \
  -H "Authorization: Bearer $GENIEFY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "question": "Welche offenen Vorgänge gibt es für die Lindenstraße 12, und wer ist jeweils zuständig?"
  }'

Antwort 200 OK

{
  "answer": "Für die Lindenstraße 12 sind zwei Vorgänge offen: TK-20931 (Heizung im Bad der WE 04, zuständig Maria Hoffmann) und TK-20874 (Aufzug bleibt zwischen den Etagen stehen, zuständig Tobias Brandt).",
  "records": [
    {
      "type": "ticket",
      "id": "casavi:TK-20931",
      "title": "Heizung im Bad ohne Funktion",
      "status": "open",
      "assignee": "Maria Hoffmann",
      "source": "casavi",
      "appLink": "https://app.casavi.com/tickets/20931"
    },
    {
      "type": "ticket",
      "id": "casavi:TK-20874",
      "title": "Aufzug bleibt zwischen den Etagen stehen",
      "status": "in_progress",
      "assignee": "Tobias Brandt",
      "source": "casavi",
      "appLink": "https://app.casavi.com/tickets/20874"
    }
  ],
  "systemsQueried": [
    "casavi"
  ]
}

Vorgänge auflisten

GET/systems/tickets

Gibt Vorgänge aus allen angebundenen Systemen in einem einheitlichen Format zurück.

Scope systems:readMCP-Werkzeug list_tickets

Query-Parameter

statusstring: Nur Vorgänge mit diesem Status.Werte: openin_progressdone
building_idstring: Nur Vorgänge in diesem Objekt.
unit_idstring: Nur Vorgänge in dieser Einheit.
searchstring: Sucht in Titel und Beschreibung.
limitinteger: Höchstzahl der zurückgegebenen Einträge, zwischen 1 und 100. Hat keinen Einfluss auf total.Standard: 20
cursorstring: Der Wert nextCursor der vorherigen Seite.

Antwort

200 OK Eine Seite mit Vorgängen.

Mögliche Fehler

502SYSTEM_UNAVAILABLEDas angebundene System hat nicht oder fehlerhaft geantwortet.

curl "https://api.geniefy.de/v1/systems/tickets?status=open&building_id=bld_Linden12" \
  -H "Authorization: Bearer $GENIEFY_API_KEY"

Antwort 200 OK

{
  "tickets": [
    {
      "ticketId": "casavi:TK-20931",
      "system": "casavi",
      "displayNumber": "TK-20931",
      "title": "Heizung im Bad ohne Funktion",
      "status": "open",
      "category": "Repairs",
      "priority": "normal",
      "buildingId": "bld_Linden12",
      "unitId": "unit_Linden12_WE04",
      "assignee": "Maria Hoffmann",
      "createdAt": "2026-09-14T08:29:40Z",
      "appLink": "https://app.casavi.com/tickets/20931"
    }
  ],
  "total": 2,
  "nextCursor": null
}

Vorgang anlegen

POST/systems/tickets

Legt einen Vorgang im angebundenen System an und weist ihn optional zu. Ohne system wird das Hauptsystem Ihrer Verwaltung verwendet.

Scope systems:writeMCP-Werkzeug create_ticket

Anfragekörper

titlestringerforderlich: Kurzer Titel.
descriptionstringerforderlich: Beschreibung des Anliegens.
categorystring: Kategorie-Schlüssel aus GET /categories.
buildingIdstring: Objekt.
unitIdstring: Einheit.
contactIdstring: Meldende Person.
prioritystring: Dringlichkeit.Werte: lownormalhighemergencyStandard: normal
assigneestring: Zuständige Person im System.
systemstring: Zielsystem, falls mehrere angebunden sind.

Antwort

201 Created Der angelegte Vorgang.

Mögliche Fehler

502SYSTEM_UNAVAILABLEDas angebundene System hat nicht oder fehlerhaft geantwortet.

curl -X POST "https://api.geniefy.de/v1/systems/tickets" \
  -H "Authorization: Bearer $GENIEFY_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Heizung im Bad ohne Funktion",
    "description": "Heizkörper im Bad seit gestern kalt, übrige Räume warm.",
    "category": "Repairs",
    "buildingId": "bld_Linden12",
    "unitId": "unit_Linden12_WE04",
    "contactId": "ct_5Pz1rQ8",
    "priority": "normal",
    "assignee": "Maria Hoffmann"
  }'

Antwort 201 Created

{
  "ticketId": "casavi:TK-20931",
  "system": "casavi",
  "displayNumber": "TK-20931",
  "title": "Heizung im Bad ohne Funktion",
  "status": "open",
  "category": "Repairs",
  "priority": "normal",
  "buildingId": "bld_Linden12",
  "unitId": "unit_Linden12_WE04",
  "assignee": "Maria Hoffmann",
  "createdAt": "2026-09-14T08:29:40Z",
  "appLink": "https://app.casavi.com/tickets/20931"
}

Vorgang ändern

PATCH/systems/tickets/{ticketId}

Ändert Status oder Zuständigkeit eines Vorgangs und fügt optional einen Kommentar hinzu.

Scope systems:writeMCP-Werkzeug update_ticket

Pfad-Parameter

ticketIdstringerforderlich: ID des Vorgangs.

Anfragekörper

statusstring: Neuer Status.Werte: openin_progressdone
assigneestring: Neue zuständige Person.
commentstring: Kommentar, der im System erscheint.

Antwort

200 OK Der geänderte Vorgang.

Mögliche Fehler

404NOT_FOUNDDas angefragte Objekt existiert nicht oder gehört nicht zu Ihrer Verwaltung.
502SYSTEM_UNAVAILABLEDas angebundene System hat nicht oder fehlerhaft geantwortet.

curl -X PATCH "https://api.geniefy.de/v1/systems/tickets/casavi%3ATK-20931" \
  -H "Authorization: Bearer $GENIEFY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "in_progress",
    "comment": "Heizungsbauer Huber kommt am 15.09. zwischen 8 und 10 Uhr."
  }'

Antwort 200 OK

{
  "ticketId": "casavi:TK-20931",
  "system": "casavi",
  "displayNumber": "TK-20931",
  "title": "Heizung im Bad ohne Funktion",
  "status": "in_progress",
  "category": "Repairs",
  "priority": "normal",
  "buildingId": "bld_Linden12",
  "unitId": "unit_Linden12_WE04",
  "assignee": "Maria Hoffmann",
  "createdAt": "2026-09-14T08:29:40Z",
  "appLink": "https://app.casavi.com/tickets/20931"
}

Dokumente suchen

GET/systems/documents

Findet Dokumente im angebundenen DMS, zum Beispiel Protokolle, Abrechnungen, Hausordnungen oder Beschlüsse. Der Download-Link ist 15 Minuten gültig.

Scope systems:readMCP-Werkzeug find_documents

Query-Parameter

building_idstring: Nur Dokumente dieses Objekts.
typestring: Art des Dokuments.Werte: meeting_minutesannual_statementoperating_costshouse_rulesresolutioncontractother
searchstring: Sucht in Titel und Inhalt.
limitinteger: Höchstzahl der zurückgegebenen Einträge, zwischen 1 und 100. Hat keinen Einfluss auf total.Standard: 20

Antwort

200 OK Gefundene Dokumente.

Mögliche Fehler

502SYSTEM_UNAVAILABLEDas angebundene System hat nicht oder fehlerhaft geantwortet.

curl "https://api.geniefy.de/v1/systems/documents?building_id=bld_Linden12&type=meeting_minutes" \
  -H "Authorization: Bearer $GENIEFY_API_KEY"

Antwort 200 OK

{
  "documents": [
    {
      "documentId": "casavi:doc_77120",
      "title": "Protokoll Eigentümerversammlung 2026",
      "type": "meeting_minutes",
      "date": "2026-06-18",
      "buildingId": "bld_Linden12",
      "source": "casavi",
      "downloadUrl": "https://files.geniefy.de/dms/doc_77120.pdf?sig=…"
    }
  ]
}

Einheit mit Beteiligten abrufen

GET/systems/units/{unitId}

Gibt eine Einheit mit Eigentümern, Mietern und, falls das ERP es liefert, dem aktuellen Hausgeldsaldo zurück.

Scope systems:read

Pfad-Parameter

unitIdstringerforderlich: ID der Einheit.

Antwort

200 OK Die Einheit.

Mögliche Fehler

404NOT_FOUNDDas angefragte Objekt existiert nicht oder gehört nicht zu Ihrer Verwaltung.
502SYSTEM_UNAVAILABLEDas angebundene System hat nicht oder fehlerhaft geantwortet.

curl "https://api.geniefy.de/v1/systems/units/unit_Linden12_WE04" \
  -H "Authorization: Bearer $GENIEFY_API_KEY"

Antwort 200 OK

{
  "unitId": "unit_Linden12_WE04",
  "label": "WE 04",
  "buildingId": "bld_Linden12",
  "owners": [
    {
      "contactId": "ct_2Ow9",
      "name": "Petra Lang",
      "source": "donexus"
    }
  ],
  "tenants": [
    {
      "contactId": "ct_5Pz1rQ8",
      "name": "Jonas Weber",
      "since": "2023-04-01",
      "source": "donexus"
    }
  ],
  "balance": {
    "amount": -412,
    "currency": "EUR",
    "asOf": "2026-09-13",
    "source": "donexus"
  }
}

WebhooksBeta

Registrieren Sie Adressen, an die Geniefy Ereignisse sendet. Wie Sie Zustellungen prüfen, steht unter Webhooks empfangen.

Webhook registrieren

POST/webhooks

Registriert eine HTTPS-Adresse für die gewählten Ereignisse. Das Geheimnis zur Signaturprüfung erhalten Sie nur in dieser Antwort, speichern Sie es sicher.

Scope webhooks:write

Anfragekörper

urlstringerforderlich: HTTPS-Adresse Ihres Servers.
eventsstring[]erforderlich: Ereignisse, die zugestellt werden.
descriptionstring: Interne Beschreibung.

Antwort

201 Created Der Webhook mit Geheimnis.

curl -X POST "https://api.geniefy.de/v1/webhooks" \
  -H "Authorization: Bearer $GENIEFY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://intranet.hv-muster.de/hooks/geniefy",
    "events": [
      "call.completed",
      "ticket.created"
    ],
    "description": "Intranet Tagesübersicht"
  }'

Antwort 201 Created

{
  "webhookId": "wh_3Nf8Pz",
  "url": "https://intranet.hv-muster.de/hooks/geniefy",
  "events": [
    "call.completed",
    "ticket.created"
  ],
  "secret": "whsec_9c1f4b7e2a6d",
  "createdAt": "2026-09-14T11:00:00Z"
}

Webhooks auflisten

GET/webhooks

Gibt Ihre Webhooks mit dem Ergebnis der letzten Zustellung zurück.

Scope webhooks:write

Dieser Endpunkt erwartet keine Parameter.

Antwort

200 OK Die Webhooks.

curl "https://api.geniefy.de/v1/webhooks" \
  -H "Authorization: Bearer $GENIEFY_API_KEY"

Antwort 200 OK

{
  "webhooks": [
    {
      "webhookId": "wh_3Nf8Pz",
      "url": "https://intranet.hv-muster.de/hooks/geniefy",
      "events": [
        "call.completed",
        "ticket.created"
      ],
      "lastDelivery": {
        "status": 200,
        "at": "2026-09-14T11:04:12Z"
      }
    }
  ]
}

Webhook entfernen

DELETE/webhooks/{webhookId}

Entfernt einen Webhook. Laufende Zustellversuche werden abgebrochen.

Scope webhooks:write

Pfad-Parameter

webhookIdstringerforderlich: ID des Webhooks.

Antwort

204 No Content Keine Antwort im Körper.

Mögliche Fehler

404NOT_FOUNDDas angefragte Objekt existiert nicht oder gehört nicht zu Ihrer Verwaltung.

curl -X DELETE "https://api.geniefy.de/v1/webhooks/wh_3Nf8Pz" \
  -H "Authorization: Bearer $GENIEFY_API_KEY"

Änderungsprotokoll

15. September 2026
- Verbundene Systeme (Beta): Vorgänge, Dokumente und Einheiten aus casavi, Facilioo und DoNexus in einem Format, dazu Abfragen in natürlicher Sprache.
- Aufgaben und Webhooks sind als Beta verfügbar.
- Der MCP-Server bietet Ressourcen und Prompts für Wochenbericht, offene Rückrufe und Objektübersicht.
1. September 2026
- Version v1 mit Anrufen, WhatsApp und E-Mail, Wissen, Agent, Weiterleitung, Integrationen, Kontakten, Auswertungen und Abrechnung.
- Paginierung mit cursor und nextCursor für alle Listen.

Sie möchten die API nutzen?

Schreiben Sie uns, was Sie bauen möchten. Wir stellen Ihnen einen Schlüssel mit den passenden Berechtigungen aus und begleiten die ersten Anfragen persönlich.

API-Zugang anfragen