🚀 Jetzt neu: FlowAI! Ein revolutionärer Chat mit personalisierten AI-Agenten. 🌟

FlowCall API - für Telefonie-Projekte, Leads und Gesprächsergebnisse

Eine vollständige REST API für die Telefonakquise. Sie deckt die Telefonie-Projekte mit ihren Einstellungen, dem Gesprächsleitfaden und dem Gesprächsformular ab, den Weg der Leads über Import und Export, die Arbeit am einzelnen Lead mit Ergebnis, Kommentaren, Wiedervorlagen, Anrufen und E-Mails, die Rollen des Teams sowie das Telefonprotokoll und drei Auswertungen.

🚀 Schnellstart

Basis-URL: https://creativeskyline.de/api/flowcall/context https://creativeskyline.de/api/flowcall/projects https://creativeskyline.de/api/flowcall/leads https://creativeskyline.de/api/flowcall/roles https://creativeskyline.de/api/flowcall/reports
FlowCall-Berechtigung erforderlich
Der Benutzer benötigt eine aktive FlowCall-Berechtigung. Ist das Modul in den Teameinstellungen abgeschaltet, antwortet jede Route mit HTTP 403.
Zwei Ebenen von Rechten
Die Modulberechtigung entscheidet nur, ob der Schlüssel FlowCall überhaupt benutzen darf. Welche Telefonie-Projekte er erreicht und was er darin tun darf, entscheidet die Rolle des Benutzers in genau diesem Projekt, getragen von zehn Berechtigungen. Ein Projekt ohne Berechtigung verhält sich wie eines, das es nicht gibt, und antwortet mit HTTP 404. Fehlt auf einem erreichbaren Projekt nur eine einzelne Berechtigung, antwortet der Aufruf mit HTTP 403 und nennt die fehlende Berechtigung beim Namen.
Der Teaminhaber und der FlowCall-Vollzugriff sehen alles
Der Inhaber des Teams und ein Mitglied mit FlowCall-Vollzugriff halten jede der zehn Berechtigungen auf jedem Projekt des Teams, auch ohne eine eigene Berechtigungszeile.
Alles wird über UUIDs adressiert
Projekt, Lead, Kommentar, Wiedervorlage, Anruf, E-Mail, Import, Export, Rolle und Teammitglied werden ausschließlich über ihre UUID angesprochen. Ein Projekt wird dabei über die UUID des Kundenprojekts angesprochen, also über genau die Kennung, die auch die Webadresse verwendet. Numerische Felder wie project_id oder lead_id werden nicht entgegengenommen und führen zu einem Validierungsfehler, der das Ersatzfeld benennt.
Zugangsdaten sind bewusst nicht erreichbar
Der eigene Mailserver eines Projekts und die Schlüssel der Telefonanlagen CloudTalk, Ringover und Sipgate lassen sich über diese API weder lesen noch schreiben. Diese Angaben gehören auf die Einstellungsseite und nicht in eine Schnittstelle mit Schlüssel.

1. API-Zugangsdaten abrufen

Melden Sie sich an, öffnen Sie Profil → API-Zugang und kopieren Sie Ihren persönlichen API-Key (pk_...).

2. Authentifizierung

Alle Anfragen benötigen diese HTTP-Header:

Authorization: Bearer pk_dein_api_key
Accept: application/json

3. Einstieg

Beginnen Sie mit GET /api/flowcall/context. Die Antwort nennt alle erreichbaren Telefonie-Projekte samt Ihren eigenen Rechten darin, die zehn Berechtigungsnamen und die üblichen Gesprächsergebnisse. So muss ein Programm die Begriffe dieser API nicht fest einbauen.

4. Ein Ergebnis ist kein Verlauf

Ein Lead trägt genau ein aktuelles Gesprächsergebnis. PUT /api/flowcall/leads/{uuid}/status überschreibt dieses eine Ergebnis. Der Gesprächsverlauf ist eine davon getrennte Liste, die nur wächst und über GET /api/flowcall/leads/{uuid}/calls gelesen wird. Wer aus dem Ergebnis eine Historie ableiten will, baut am Datenmodell vorbei.

5. Seitenweise Listen

Jede Liste versteht per_page (1 bis 200, Standard 25) und page. Die Antwort trägt die Form {success, data, meta: {current_page, per_page, total, last_page}}.

6. Fehler

Fehler antworten als {"success": false, "error": "...", "message": "..."}. Validierungsfehler kommen in der gewohnten Laravel-Form mit HTTP 422 und einem errors-Objekt je Feld.

🧭 Überblick

Die zehn Berechtigungen
team_verwalten und team_rollen_verwalten gelten teamweit, callhistory_all entscheidet über die Reichweite im Telefonprotokoll. Die übrigen sieben gelten je Projekt: projekte_verwalten für Einstellungen, Import, Export-Vorbereitung und Löschen, projekt_bearbeiten für den gemeinsamen Gesprächsleitfaden, projekt_alle_leads für die vollständige Leadliste, projekt_leads_export für Exporte, projekt_telefonie für das Arbeiten am Lead, projekt_lead_hinzufuegen für neue Leads und projekt_unstimmigkeiten für die Klärfälle.

Projekte, Rechte und Begriffe abrufen

GET /api/flowcall/context

Liefert alle erreichbaren Telefonie-Projekte mit den eigenen Rechten darin, die zehn Berechtigungsnamen, die üblichen Gesprächsergebnisse und die Angabe, ob dieser Schlüssel als Inhaber handelt. Ein Aufruf, damit ein Programm die Begriffe dieser API nicht fest einbauen muss.

🗂️ Projekte

Ein Telefonie-Projekt hängt an einem Kundenprojekt
Angesprochen wird es über die UUID des Kundenprojekts, also über dieselbe Kennung wie in der Webadresse. Ein Link, den jemand aus der Oberfläche kopiert, benennt hier denselben Datensatz.
Der Status wirkt über FlowCall hinaus
Der Status liegt auf dem Kundenprojekt. Wird er auf inactive gesetzt, verschwindet das Projekt aus jedem Modul und nicht nur aus FlowCall.
Kein eigener Mailserver über diese API
Die Felder smtp_password und smtpserver werden ausdrücklich zurückgewiesen. Der eigene Mailserver eines Projekts bedeutet ein Kennwort im Klartext und eine Verbindungsprobe, und das gehört auf die Einstellungsseite.

Telefonie-Projekte auflisten

GET /api/flowcall/projects

Alle Telefonie-Projekte, die dieser Schlüssel erreicht, neueste zuerst.

Query-Parameter:

per_page integer Einträge pro Seite, 1 bis 200, Standard 25.
page integer Seitenzahl, Standard 1.

Ein Telefonie-Projekt anlegen

POST /api/flowcall/projects

Macht aus einem bestehenden Kundenprojekt ein Telefonie-Projekt, oder legt beides in einem Zug an. Genau eines von project_uuid und client_uuid wird benötigt. Trägt das Kundenprojekt bereits eine Telefonie-Konfiguration, antwortet der Aufruf mit HTTP 422 und dem Fehler already_exists. Diese Berechtigung wird teamweit geprüft, weil ein Projekt, das es noch nicht gibt, keine eigene Berechtigungszeile haben kann.

Request Body:

project_uuid string Ein bestehendes Kundenprojekt des Teams. Pflicht, wenn client_uuid fehlt.
client_uuid string Ein Kunde des Teams, unter dem ein neues Projekt entsteht. Pflicht, wenn project_uuid fehlt.
name string Name des neuen Projekts, höchstens 255 Zeichen. Pflicht zusammen mit client_uuid.
appointment_link string Adresse der Terminbuchung, http oder https, höchstens 2048 Zeichen.
call_again_after_attempts string Nach wie vielen erfolglosen Versuchen erneut angerufen wird. Freitext, höchstens 10 Zeichen, Standard 3.
email_service boolean Schaltet den E-Mail-Versand des Projekts ein.
sender_name string Absendername, wird nur bei eingeschaltetem E-Mail-Versand gespeichert.
sender_email string Absenderadresse, wird nur bei eingeschaltetem E-Mail-Versand gespeichert.

Ein Telefonie-Projekt abrufen

GET /api/flowcall/projects/{uuid}

Ein Projekt mit den eigenen Rechten darin, dem Zeitraum, dem vereinbarten Umfang, der Beschreibung und den Zahlen der Übersicht. Unbearbeitet meint dabei einen Lead ganz ohne Ergebniszeile, was etwas anderes ist als ein Lead mit dem Ergebnis Offen.

Die Einstellungen eines Projekts ändern

PUT /api/flowcall/projects/{uuid}/settings

Ändert die Telefonie-Einstellungen, die keine Zugangsdaten sind. Ein weggelassenes Feld bleibt unverändert. Wird der E-Mail-Versand abgeschaltet, verliert das Projekt seine Absenderangaben, damit es nie unter einem Absender weiterschreibt, an den sich niemand erinnert. Benötigt projekte_verwalten.

Request Body:

appointment_link string Adresse der Terminbuchung, http oder https, höchstens 2048 Zeichen, oder null.
call_again_after_attempts string Freitext, höchstens 10 Zeichen, oder null.
email_service boolean Schaltet den E-Mail-Versand des Projekts ein oder aus.
sender_name string Absendername, höchstens 255 Zeichen, oder null.
sender_email string Absenderadresse, höchstens 255 Zeichen, oder null.

Zeitraum, Umfang und Beschreibung ändern

PUT /api/flowcall/projects/{uuid}/dates

Setzt den Zeitraum, den vereinbarten Umfang und die Projektbeschreibung. Der Umfang ist Freitext, weil dort Angaben wie 40 pro Monat stehen, die eine reine Zahl zurückweisen würde. Benötigt projekte_verwalten.

Request Body:

start_date string Beginn im Format JJJJ-MM-TT, oder null.
end_date string Ende im Format JJJJ-MM-TT, nicht vor dem Beginn, oder null.
hours string Vereinbarter Umfang als Freitext, höchstens 255 Zeichen, oder null.
information string Beschreibung des Projekts, höchstens 200000 Zeichen, oder null.

Ein Projekt ein- oder ausschalten

PUT /api/flowcall/projects/{uuid}/status

Setzt den Status des Kundenprojekts auf active oder inactive. Der Status wirkt über FlowCall hinaus, weil er auf dem Kundenprojekt liegt. Benötigt projekte_verwalten.

Request Body:

status string * active oder inactive. Ein anderer Wert wird zurückgewiesen.

Unbearbeitete Leads eines Projekts löschen

DELETE /api/flowcall/projects/{uuid}/leads/unworked

Entfernt jeden Lead des Projekts, den niemand angefasst hat. Unbearbeitet heißt: weder ein Ergebnis noch ein Kommentar. Ein Lead, der einmal angerufen wurde, wird davon nie erfasst. Benötigt projekte_verwalten.

📝 Leitfaden und Formular

Zwei Arten von Leitfaden
original ist der gemeinsame Leitfaden des Projekts, den jede Person am Telefon vorliest. user ist die persönliche Fassung eines einzelnen Mitglieds. Lesen darf beide, wer das Projekt bearbeitet oder wer darin telefoniert. Schreiben verlangt zwei verschiedene Berechtigungen: projekt_bearbeiten für die gemeinsame Fassung, projekt_telefonie für die eigene.
Das Formular wird immer vollständig ersetzt
Die Felder sind eine geordnete Liste, ein teilweises Schreiben hat darauf keine sinnvolle Bedeutung. Der Schlüssel, unter dem eine Antwort gespeichert wird, leitet sich aus der Beschriftung ab und lässt sich nicht selbst wählen, sonst würden zwei Felder auf demselben Schlüssel landen.

Den Gesprächsleitfaden abrufen

GET /api/flowcall/projects/{uuid}/guideline

Liefert den gemeinsamen Leitfaden des Projekts oder die eigene Fassung. Benötigt projekt_bearbeiten oder projekt_telefonie.

Query-Parameter:

type string original oder user. Standard ist original.

Den Gesprächsleitfaden schreiben

PUT /api/flowcall/projects/{uuid}/guideline

Schreibt den Leitfaden. Die gemeinsame Fassung benötigt projekt_bearbeiten, die eigene Fassung projekt_telefonie.

Request Body:

content string * Der Text, höchstens 200000 Zeichen.
type string original oder user. Standard ist original.

Das Gesprächsformular abrufen

GET /api/flowcall/projects/{uuid}/form

Die Felder, die während eines Gesprächs ausgefüllt werden. Benötigt projekt_bearbeiten oder projekt_telefonie.

Das Gesprächsformular ersetzen

PUT /api/flowcall/projects/{uuid}/form

Ersetzt die Felderliste vollständig. Eine leere Liste entfernt das Formular. Benötigt projekte_verwalten.

Request Body:

fields array * Die vollständige Felderliste. Das Feld muss vorhanden sein, darf aber leer sein.
fields.*.label string * Beschriftung des Feldes, höchstens 255 Zeichen.
fields.*.typ string * text, textarea, select, checkbox, radio, date oder number.
fields.*.placeholder string Platzhaltertext, höchstens 255 Zeichen.
fields.*.optionen array Auswahlmöglichkeiten für select, checkbox und radio, je höchstens 255 Zeichen.

📥 Importe

Nur Datei-Upload, nie eine Adresse
Die Liste wird als multipart/form-data hochgeladen. Ein Feld url wird ausdrücklich zurückgewiesen, denn eine Adresse, die der Aufrufer wählt, dürfte der Server niemals von sich aus abrufen.
Eine Spalte ohne Ziel gehört trotzdem in die Zuordnung
Der Import läuft die Datei Spalte für Spalte ab. Eine Spaltenüberschrift, die auf nichts abgebildet wird, muss deshalb mit dem Wert null in der Zuordnung stehen. Wird sie ganz weggelassen, verschiebt sich jede folgende Spalte um eins.
Zwei Schritte, wenn die Spalten unbekannt sind
Ohne Zuordnung antwortet der Upload mit den Spaltenüberschriften der Datei und den möglichen Zielfeldern. Die Zuordnung wird danach nachgereicht. Wird sie gleich mitgeschickt, startet der Import sofort.

Importe eines Projekts auflisten

GET /api/flowcall/projects/{uuid}/imports

Die hochgeladenen Leadlisten eines Projekts, neueste zuerst. Der Zustand ist eine kleine Kette: uploaded heißt, die Datei liegt vor und nichts ist geschehen, queued heißt, die Zuordnung steht und die Arbeit wartet, processing heißt, sie läuft, danach finished oder failed. Benötigt projekte_verwalten.

Query-Parameter:

per_page integer Einträge pro Seite, 1 bis 200, Standard 25.
page integer Seitenzahl, Standard 1.

Eine Leadliste hochladen

POST /api/flowcall/projects/{uuid}/imports

Nimmt eine Leadliste als multipart/form-data entgegen und antwortet mit HTTP 201. Ohne mapping trägt die Antwort die Spaltenüberschriften der Datei und die möglichen Zielfelder, und der Import wartet. Mit mapping startet er sofort; eine unbrauchbare Zuordnung antwortet mit HTTP 422 und dem Fehler invalid_mapping. Benötigt projekte_verwalten.

Request Body:

file file * Die Leadliste als txt, csv, xls oder xlsx, höchstens 50 MB.
mapping object Zuordnung Spaltenüberschrift zu Zielfeld. Ein Wert darf hinter einem Doppelpunkt die Bezeichnung einer Wertesammlung tragen, etwa emails:Allgemein. null bedeutet, die Spalte wird übergangen.
url string Wird ausdrücklich zurückgewiesen. Eine Datei wird hochgeladen, nicht von einer Adresse geholt.

Die Spaltenzuordnung eines Imports setzen

PUT /api/flowcall/projects/{uuid}/imports/{importUuid}/mapping

Vereinbart die Spaltenzuordnung einer hochgeladenen Liste und übergibt den Import an die Warteschlange. Jede Spaltenüberschrift der Datei gehört in die Zuordnung, auch die, die auf nichts abgebildet wird; sie trägt dann den Wert null. Eine unbrauchbare Zuordnung antwortet mit HTTP 422 und dem Fehler invalid_mapping. Benötigt projekte_verwalten.

Request Body:

mapping object * Zuordnung Spaltenüberschrift zu Zielfeld, mindestens ein Eintrag. Ein Wert darf hinter einem Doppelpunkt die Bezeichnung einer Wertesammlung tragen, etwa emails:Allgemein. null bedeutet, die Spalte wird übergangen.

Einen Import erneut starten

POST /api/flowcall/projects/{uuid}/imports/{importUuid}/retry

Startet einen fehlgeschlagenen Import mit der Zuordnung, die er bereits trägt. Ein Import in einem anderen Zustand antwortet mit HTTP 409 und dem Fehler not_retryable. Benötigt projekte_verwalten.

📤 Exporte

Ein Export läuft im Hintergrund
Der Aufruf antwortet mit HTTP 202 und einer Zeile, deren Zustand abgefragt werden kann. Die fertige Datei wird zusätzlich per E-Mail angekündigt. Sie steht 24 Stunden bereit und ist danach abgelaufen.
Die Kennung aus der Ankündigungsmail wird hier nicht gebraucht
Der Abruf über diese API weist den Aufrufer bereits über seinen Schlüssel aus. Die Kennung, mit der die Ankündigungsmail die Datei erreichbar macht, wird deshalb nicht herausgegeben.

Exporte eines Projekts auflisten

GET /api/flowcall/projects/{uuid}/exports

Die Exporte eines Projekts mit ihrem Zustand und ihrer Ablauffrist. Benötigt projekt_leads_export.

Query-Parameter:

per_page integer Einträge pro Seite, 1 bis 200, Standard 25.
page integer Seitenzahl, Standard 1.

Einen Export starten

POST /api/flowcall/projects/{uuid}/exports

Stellt einen Export der Leads in die Warteschlange und antwortet mit HTTP 202. Ohne recipient_email geht die Ankündigung an die eigene Adresse. Benötigt projekt_leads_export.

Request Body:

recipient_email string Empfänger der Ankündigung. Standard ist die eigene Adresse.
status string Schränkt auf ein Gesprächsergebnis ein. Der Wert all umfasst alle Leads und ist der Standard.
include_call_results boolean Nimmt den Gesprächsverlauf mit in die Datei.
max_call_results integer Wie viele Einträge des Verlaufs je Lead, 1 bis 100, Standard 5.
include_comments boolean Nimmt die Kommentare mit in die Datei.
max_comments integer Wie viele Kommentare je Lead, 1 bis 100, Standard 5.
highlight_rows boolean Hebt die Zeilen nach ihrem Gesprächsergebnis farblich hervor.

Eine fertige Exportdatei abrufen

GET /api/flowcall/projects/{uuid}/exports/{exportUuid}/download BINARY

Liefert die fertige Datei als Download. Ein Export, der noch läuft, fehlgeschlagen oder abgelaufen ist, antwortet mit HTTP 409 und dem Fehler not_ready. Ist die Datei nicht mehr vorhanden, antwortet der Abruf mit HTTP 410 und dem Fehler file_missing. Benötigt projekt_leads_export.

🎯 Leads

Ein Lead trägt genau ein Ergebnis, keinen Ergebnisverlauf
Das Gesprächsergebnis eines Leads ist ein einziger Wert, den das Festhalten eines Ergebnisses überschreibt. Der Gesprächsverlauf ist eine getrennte Liste, die nur wächst und unter Anrufe gelesen wird. Wer aus dem Ergebnis eine Historie erwartet, baut das Falsche.
Zwei Sichten auf die Leadliste
projekt_alle_leads zeigt die vollständige Liste eines Projekts. Wer nur projekt_telefonie hält, sieht seine eigene Arbeitsliste, also die Leads, die ihm zugeordnet sind. Wer keines von beidem hält, sieht die Leads des Projekts gar nicht.
Die üblichen Gesprächsergebnisse
Offen, Übersprungen, Kein Interesse, Keinen erreicht, Falsche Rufnummer, AP nicht im hause, Wiedervorlage, E-Mail senden und Termin vereinbart. Das Feld ist Freitext, ein Projekt darf also eigene Begriffe verwenden. Wer auswerten will, sollte sich auf die neun Begriffe stützen.
Ein Lead wechselt nie das Projekt
Beim Ändern werden project_uuid, project_id und team_id zurückgewiesen. Ein Lead an einem anderen Projekt läge hinter anderen Berechtigungen, und auch in der Oberfläche gibt es diesen Weg nicht.

Leads auflisten

GET /api/flowcall/leads

Die Leads aller erreichbaren Projekte, neueste zuerst, gefiltert und seitenweise. Ohne project_uuid umfasst die Liste jedes Projekt, das dieser Schlüssel sieht.

Query-Parameter:

project_uuid string Auf ein Telefonie-Projekt einschränken.
status string Nur Leads mit diesem Gesprächsergebnis, etwa Termin vereinbart.
assigned_user_uuid string Nur Leads, die diesem Teammitglied zugeordnet sind.
search string Sucht in Firma, Ansprechpartner, Vorname, Nachname und Stadt.
follow_up_due boolean Nur Leads, deren Wiedervorlage heute fällig oder überfällig ist.
locked boolean Nur Leads, die gerade in Bearbeitung sind, oder nur die freien.
untouched boolean Nur Leads ganz ohne Ergebniszeile.
per_page integer Einträge pro Seite, 1 bis 200, Standard 25.
page integer Seitenzahl, Standard 1.

Einen Lead anlegen

POST /api/flowcall/leads

Legt einen Lead in einem Telefonie-Projekt an und antwortet mit HTTP 201. Die Kennung vergibt die Plattform; eine eigene Referenz gehört in extra. Benötigt projekt_lead_hinzufuegen.

Request Body:

project_uuid string * Das Telefonie-Projekt, angesprochen über die UUID des Kundenprojekts.
company string Firma, höchstens 255 Zeichen.
contact_person string Ansprechpartner, höchstens 255 Zeichen.
first_name string Vorname, höchstens 255 Zeichen.
last_name string Nachname, höchstens 255 Zeichen.
address string Vollständige Anschrift als ein Feld, höchstens 1000 Zeichen.
street string Straße, höchstens 255 Zeichen.
house_number string Hausnummer, höchstens 50 Zeichen.
postcode string Postleitzahl, höchstens 20 Zeichen.
city string Stadt, höchstens 255 Zeichen.
state string Bundesland, höchstens 255 Zeichen.
country string Land, höchstens 255 Zeichen.
phone_numbers array Liste aus Paaren mit label und value. Ein bloßer Text ohne Bezeichnung wird nicht entgegengenommen.
emails array Liste aus Paaren mit label und value.
websites array Liste aus Paaren mit label und value.
extra array Weitere Angaben, frei strukturiert. Der richtige Ort für eine eigene Referenz.
form_data array Antworten des Gesprächsformulars, abgelegt unter den Schlüsseln der Felder.
project_id integer Wird zurückgewiesen. Stattdessen project_uuid verwenden.
team_id integer Wird zurückgewiesen. Das Team folgt aus dem API-Schlüssel.

Einen Lead abrufen

GET /api/flowcall/leads/{uuid}

Ein Lead mit seinem aktuellen Gesprächsergebnis, der zuständigen Person und allem, was daran hängt. Die Teillisten sind begrenzt: bis zu 50 Anrufe, 50 Kommentare und 50 E-Mails sowie die Wiedervorlage. Wer den vollen Verlauf braucht, nimmt die eigenen Listen. Benötigt projekt_alle_leads oder projekt_telefonie.

Einen Lead ändern

PUT /api/flowcall/leads/{uuid}

Ändert die Stammdaten eines Leads. Ein weggelassenes Feld bleibt unverändert. Die Änderung wird als Kommentar festgehalten, genau wie in der Oberfläche; solche Kommentare tragen in der Kommentarliste die Angabe system. Die Felder sind dieselben wie beim Anlegen. project_uuid, project_id und team_id werden zurückgewiesen. Benötigt projekt_bearbeiten oder projekt_telefonie.

Request Body:

company string Firma, höchstens 255 Zeichen.
contact_person string Ansprechpartner, höchstens 255 Zeichen.
first_name string Vorname, höchstens 255 Zeichen.
last_name string Nachname, höchstens 255 Zeichen.
address string Vollständige Anschrift als ein Feld, höchstens 1000 Zeichen.
street string Straße, höchstens 255 Zeichen.
house_number string Hausnummer, höchstens 50 Zeichen.
postcode string Postleitzahl, höchstens 20 Zeichen.
city string Stadt, höchstens 255 Zeichen.
state string Bundesland, höchstens 255 Zeichen.
country string Land, höchstens 255 Zeichen.
phone_numbers array Liste aus Paaren mit label und value.
emails array Liste aus Paaren mit label und value.
websites array Liste aus Paaren mit label und value.
extra array Weitere Angaben, frei strukturiert.
form_data array Antworten des Gesprächsformulars.

Einen Lead löschen

DELETE /api/flowcall/leads/{uuid}

Entfernt den Lead samt seinen Anrufen, Kommentaren, Wiedervorlagen und E-Mails. Benötigt projekte_verwalten.

Das Ergebnis eines Gesprächs festhalten

PUT /api/flowcall/leads/{uuid}/status

Schreibt das aktuelle Gesprächsergebnis des Leads und überschreibt dabei das bisherige. In einem Zug entstehen wahlweise ein Kommentar, ein Eintrag im Gesprächsverlauf und eine neue Wiedervorlage. Jedes festgehaltene Ergebnis schließt die offene Wiedervorlage, sofern nicht zugleich ein neues Datum mitgegeben wird. Benötigt projekt_telefonie.

Request Body:

status string * Das Gesprächsergebnis, höchstens 255 Zeichen. Üblich sind Offen, Übersprungen, Kein Interesse, Keinen erreicht, Falsche Rufnummer, AP nicht im hause, Wiedervorlage, E-Mail senden und Termin vereinbart; das Feld ist Freitext.
comment string Wird als Kommentar am Lead festgehalten, höchstens 60000 Zeichen.
follow_up_date string Neue Wiedervorlage im Format JJJJ-MM-TT. Ohne Angabe wird die offene Wiedervorlage geschlossen.
follow_up_time string Uhrzeit der Wiedervorlage im Format HH:MM, Standard 08:00.
log_call boolean Ob zusätzlich ein Eintrag im Gesprächsverlauf entsteht. Standard ist true; false passt zu einem übersprungenen Lead, der nie als Anruf gezählt hat.

Einen Lead in Bearbeitung nehmen

POST /api/flowcall/leads/{uuid}/lock

Nimmt den Lead für die eigene Bearbeitung, damit zwei Personen ihn nicht gleichzeitig anrufen. Ein Lead, den bereits jemand bearbeitet, antwortet mit HTTP 409, statt stillschweigend übernommen zu werden. Benötigt projekt_telefonie.

Einen Lead wieder freigeben

DELETE /api/flowcall/leads/{uuid}/lock

Gibt den Lead zurück in die gemeinsame Liste. Benötigt projekt_telefonie.

💬 Kommentare

Ändern und Löschen nur beim eigenen Kommentar
Ein fremder Kommentar wird mit HTTP 403 abgelehnt. Er ist nicht verborgen, er steht in der Liste, er lässt sich nur nicht umschreiben oder entfernen. Ein Gesprächsverlauf, den eine Person für eine andere umschreiben kann, ist kein Verlauf.
Kommentare, die niemand getippt hat
Ändert sich ein Lead, hält die Plattform das selbst als Kommentar fest. Solche Einträge tragen die Angabe system, damit ein Programm sie von einer Notiz unterscheiden kann.

Kommentare eines Leads auflisten

GET /api/flowcall/leads/{uuid}/comments

Die Kommentare eines Leads, neueste zuerst. Benötigt projekt_telefonie.

Query-Parameter:

per_page integer Einträge pro Seite, 1 bis 200, Standard 25.
page integer Seitenzahl, Standard 1.

Einen Kommentar schreiben

POST /api/flowcall/leads/{uuid}/comments

Hält eine Notiz am Lead fest und antwortet mit HTTP 201. Benötigt projekt_telefonie.

Request Body:

text string * Der Text, höchstens 60000 Zeichen.

Einen Kommentar ändern

PUT /api/flowcall/leads/{uuid}/comments/{commentUuid}

Schreibt einen Kommentar um. Nur die Person, die ihn verfasst hat, darf das; jede andere erhält HTTP 403. Benötigt projekt_telefonie.

Request Body:

text string * Der neue Text, höchstens 60000 Zeichen.

Einen Kommentar löschen

DELETE /api/flowcall/leads/{uuid}/comments/{commentUuid}

Entfernt einen Kommentar. Nur die Person, die ihn verfasst hat, darf das; jede andere erhält HTTP 403. Benötigt projekt_telefonie.

📅 Wiedervorlagen

Ein Lead trägt höchstens eine Wiedervorlage
Eine neue Wiedervorlage ersetzt die bestehende, statt eine zweite anzulegen. Der Aufruf antwortet dabei immer mit HTTP 201, weil ein Ersetzen kein anderer Vorgang ist.
Ein Gesprächsergebnis schließt die Wiedervorlage
Wird ein Ergebnis festgehalten, verschwindet die offene Wiedervorlage, sofern in derselben Anfrage kein neues Datum mitgegeben wird.

Wiedervorlagen eines Leads auflisten

GET /api/flowcall/leads/{uuid}/follow-ups

Die Wiedervorlage des Leads, nach Datum und Uhrzeit geordnet. Da ein Lead höchstens eine trägt, ist die Liste leer oder einelementig. Benötigt projekt_telefonie.

Eine Wiedervorlage setzen

POST /api/flowcall/leads/{uuid}/follow-ups

Legt den Lead für einen Tag zurück auf die Liste und antwortet mit HTTP 201. Eine bestehende Wiedervorlage wird dabei ersetzt. Benötigt projekt_telefonie.

Request Body:

date string * Datum im Format JJJJ-MM-TT.
time string Uhrzeit im Format HH:MM, Standard 08:00.

Eine Wiedervorlage verschieben

PUT /api/flowcall/leads/{uuid}/follow-ups/{followUpUuid}

Verschiebt eine bestehende Wiedervorlage. Datum und Uhrzeit lassen sich einzeln ändern. Benötigt projekt_telefonie.

Request Body:

date string Neues Datum im Format JJJJ-MM-TT.
time string Neue Uhrzeit im Format HH:MM.

Eine Wiedervorlage löschen

DELETE /api/flowcall/leads/{uuid}/follow-ups/{followUpUuid}

Entfernt die Wiedervorlage, ohne ein Gesprächsergebnis zu schreiben. Benötigt projekt_telefonie.

📇 Anrufe

Dies ist der Verlauf, nicht das Ergebnis
Der Gesprächsverlauf wächst nur, jeder Eintrag bleibt stehen. Das aktuelle Gesprächsergebnis des Leads bleibt davon unberührt; es wird ausschließlich über das Festhalten eines Ergebnisses überschrieben.

Den Gesprächsverlauf eines Leads abrufen

GET /api/flowcall/leads/{uuid}/calls

Die Einträge des Gesprächsverlaufs, neueste zuerst. Benötigt projekt_telefonie.

Query-Parameter:

per_page integer Einträge pro Seite, 1 bis 200, Standard 25.
page integer Seitenzahl, Standard 1.

Einen Anruf nachtragen

POST /api/flowcall/leads/{uuid}/calls

Trägt einen Anruf nach, der anderswo stattgefunden hat, und antwortet mit HTTP 201. Geschrieben wird allein der Eintrag im Verlauf; das aktuelle Gesprächsergebnis des Leads bleibt, wo es ist. Benötigt projekt_telefonie.

Request Body:

status string * Das Ergebnis dieses Anrufs, höchstens 255 Zeichen. Üblich sind dieselben neun Begriffe wie beim Gesprächsergebnis; das Feld ist Freitext.

✉️ E-Mails

Eine E-Mail wird eingereiht, nicht zugestellt
Der Aufruf antwortet mit HTTP 202. Die E-Mail wartet, bis die Empfängeradresse die Prüfung bestanden hat, und geht erst danach hinaus. Ein Telefonie-Projekt schreibt an kalte Kontakte, und ein Versand vor dieser Prüfung beschädigt den Ruf der Absenderdomain.
Betreff und Text kommen aus der Projektvorlage
Werden sie weggelassen, setzt die Plattform die Vorlage des Projekts ein. Gibt es weder eine Angabe noch eine Vorlage, antwortet der Aufruf mit HTTP 422 und dem Fehler missing_template.
Die Adresse landet auch am Lead
Eine korrigierte Adresse wird zusätzlich am Lead als allgemeine E-Mail-Adresse hinterlegt, damit beim nächsten Anruf nicht wieder die falsche angeboten wird. Außerdem entsteht ein Kommentar, der den Versand festhält.

E-Mails eines Leads auflisten

GET /api/flowcall/leads/{uuid}/emails

Die an den Lead geschriebenen E-Mails, neueste zuerst. Die Zeitstempel für Zustellung, Öffnung, Klick und Unzustellbarkeit füllt der Versanddienst später; bis dahin bleiben sie leer. Benötigt projekt_telefonie.

Query-Parameter:

per_page integer Einträge pro Seite, 1 bis 200, Standard 25.
page integer Seitenzahl, Standard 1.

Eine E-Mail an den Lead einreihen

POST /api/flowcall/leads/{uuid}/emails

Reiht eine E-Mail aus der Projektvorlage ein und antwortet mit HTTP 202. Wird ein Wiedervorlagedatum mitgegeben, kommt der Lead an diesem Tag zurück auf die Liste; ohne Datum wird die offene Wiedervorlage geschlossen. Benötigt projekt_telefonie.

Request Body:

address string * Empfängeradresse, höchstens 255 Zeichen.
subject string Betreff, höchstens 255 Zeichen. Ohne Angabe gilt die Projektvorlage.
body string Text, höchstens 200000 Zeichen. Ohne Angabe gilt die Projektvorlage.
skip_verification boolean Markiert die Adresse ohne Prüfung als gültig, wie es das Kästchen in der Oberfläche tut. Der Vorgang wird am Lead als Kommentar festgehalten.
follow_up_date string Wiedervorlage im Format JJJJ-MM-TT.
follow_up_time string Uhrzeit der Wiedervorlage im Format HH:MM, Standard 08:00.

👥 Team und Rollen

Der Name einer Rolle ist ihr Bindeglied
Zugewiesene Rollen und Projektberechtigungen merken sich den Namen der Rolle, nicht eine verborgene Kennung. Wird eine Rolle umbenannt, trägt die Plattform den neuen Namen im selben Schritt in beide Stellen nach. Ohne diesen Schritt verlöre jedes Mitglied stillschweigend sämtliche Rechte.
Eine Rolle, die noch jemand trägt, wird nicht gelöscht
Der Versuch antwortet mit HTTP 409 und dem Fehler role_in_use. Andernfalls behielte diese Person einen Rollennamen, hinter dem nichts mehr steht, und jede Berechtigung läse sich als abgelehnt.
Eine Rollenzuweisung wirkt sofort in allen Projekten
Bekommt ein Mitglied eine neue Rolle, wird sie in jede seiner Projektberechtigungen übernommen. Sonst hätte dieselbe Person je nach Blickwinkel zwei verschiedene Rechtestände.

Rollen auflisten

GET /api/flowcall/roles

Alle FlowCall-Rollen des Teams mit ihren zehn Berechtigungen, alphabetisch. Benötigt team_rollen_verwalten.

Eine Rolle anlegen

POST /api/flowcall/roles

Legt eine Rolle an und antwortet mit HTTP 201. Der Name wird in Kleinbuchstaben gespeichert und muss im Team eindeutig sein; ein bereits vergebener Name antwortet mit HTTP 422 und dem Fehler already_exists. Nicht genannte Berechtigungen werden abgelehnt gesetzt. Benötigt team_rollen_verwalten.

Request Body:

name string * Der Name der Rolle, höchstens 255 Zeichen. Er wird in Kleinbuchstaben gespeichert.
flags object Die Berechtigungen als Wahrheitswerte, benannt nach den zehn Namen aus dem Überblick. Ein unbekannter Name wird zurückgewiesen, statt stillschweigend übergangen zu werden.

Eine Rolle ändern

PUT /api/flowcall/roles/{uuid}

Ändert Name und Berechtigungen. Eine nicht genannte Berechtigung bleibt unverändert. Ein Umbenennen trägt den neuen Namen im selben Schritt in die Zuweisungen und in die Projektberechtigungen nach. Ein bereits vergebener Name antwortet mit HTTP 422 und dem Fehler already_exists. Benötigt team_rollen_verwalten.

Request Body:

name string Der neue Name, höchstens 255 Zeichen. Er wird in Kleinbuchstaben gespeichert.
flags object Die zu ändernden Berechtigungen als Wahrheitswerte. Nicht genannte bleiben, wie sie sind.

Eine Rolle löschen

DELETE /api/flowcall/roles/{uuid}

Löscht eine Rolle, die niemand mehr trägt. Trägt sie noch jemand, antwortet der Aufruf mit HTTP 409 und dem Fehler role_in_use. Benötigt team_rollen_verwalten.

Teammitglieder auflisten

GET /api/flowcall/members

Alle Mitglieder des FlowCall-Teams mit der Rolle, die sie tragen. Die UUID des Eintrags benennt die Mitgliedschaft, user_uuid die Person. Benötigt team_verwalten.

Einem Mitglied eine Rolle geben

PUT /api/flowcall/members/{userUuid}/role

Weist einem Mitglied des Teams eine FlowCall-Rolle zu. Die Rolle wird über ihre UUID benannt, damit ein Umbenennen nicht mit einer Neuzuweisung verwechselt wird. Die Zuweisung wirkt sofort in allen Projektberechtigungen dieser Person. Eine Person außerhalb des Teams antwortet mit HTTP 404. Benötigt team_verwalten.

Request Body:

role_uuid string * UUID der FlowCall-Rolle.

📟 Telefonprotokoll

Diese Zeilen kommen von der Telefonanlage
Sie tragen kein Projekt und lassen sich deshalb nicht nach Projektrechten einschränken. callhistory_all entscheidet stattdessen zwischen allen Gesprächen des Teams und den eigenen; die eigenen werden über die mit der Person verknüpften Anlagenkonten gefunden.
Die Zugangsdaten der Telefonanlage sind nicht erreichbar
Die Schlüssel für CloudTalk, Ringover und Sipgate lassen sich über diese API weder lesen noch setzen. Sie gehören einem fremden Dienst, und ein Abruf würde jeden API-Schlüssel zu einem Zugang zur Telefonanlage des Kunden machen.

Das Telefonprotokoll abrufen

GET /api/flowcall/call-history

Die Gespräche aus der angebundenen Telefonanlage, neueste zuerst. Mit callhistory_all umfasst die Liste das ganze Team, sonst nur die eigenen Gespräche. Ist eine Zeile einem Lead zugeordnet, trägt sie dessen UUID.

Query-Parameter:

direction string Richtung des Gesprächs, wie die Telefonanlage sie meldet, etwa inbound oder outbound.
since string Nur Gespräche ab diesem Zeitpunkt, als Datum oder Zeitstempel.
per_page integer Einträge pro Seite, 1 bis 200, Standard 25.
page integer Seitenzahl, Standard 1.

📊 Auswertungen

Jede Auswertung zählt nur Erreichbares
Ein Projekt, das dieser Schlüssel nicht sieht, taucht in keiner Zahl auf. Der Filter project_uuid schränkt diesen Rahmen weiter ein; ein Projekt außerhalb davon antwortet mit HTTP 404. Wer kein einziges Projekt erreicht, bekommt Nullen und keinen Fehler.

Leadbestand

GET /api/flowcall/reports/leads

Wie es um die Leads der erreichbaren Projekte steht: die Gesamtzahl, wie viele gerade in Bearbeitung sind, wie viele noch niemand angefasst hat und die Verteilung über die Gesprächsergebnisse.

Query-Parameter:

project_uuid string Auf ein Telefonie-Projekt einschränken.

Anrufaufkommen

GET /api/flowcall/reports/calls

Wie viel telefoniert wurde, von wem und mit welchem Ergebnis. Das Fenster wird in Tagen zurückgerechnet und liegt bei höchstens einem Jahr, weil die Auswertung auf dem vollständigen Gesprächsverlauf arbeitet.

Query-Parameter:

project_uuid string Auf ein Telefonie-Projekt einschränken.
days integer Zeitfenster in Tagen, 1 bis 365, Standard 14.

Wiedervorlagen

GET /api/flowcall/reports/follow-ups

Was überfällig ist, was heute ansteht und was als Nächstes kommt. Die Vorschau umfasst die zwanzig nächsten Wiedervorlagen.

Query-Parameter:

project_uuid string Auf ein Telefonie-Projekt einschränken.