// stack · schnittstelle
Pipedrive ist ein CRM, das nicht um die Datenbank gebaut ist, sondern um die Vertriebs-Pipeline: Ein Deal wandert durch Stufen, bis er gewonnen oder verloren ist. Für siteway heißt das: Eine Anfrage von der Website ist selten nur ein Kontakt — sie wird zu Person, Organisation und Deal in der richtigen Stufe. Diese Seite beschreibt, wie wir das über die dokumentierte REST-API bauen.
// definition
Pipedrive ist ein cloudbasiertes CRM mit einem sehr klaren Schwerpunkt: dem Vertrieb. Die Schaltzentrale ist die Pipeline — eine Abfolge von Stufen, durch die ein Vorgang läuft, bis er gewonnen oder verloren ist. Entstanden ist das System 2010 in Estland, gegründet von Vertrieblern, denen die damaligen Werkzeuge zu sehr nach Berichtswesen und zu wenig nach Verkaufen aussahen. Diese Herkunft merkt man dem Produkt bis heute an.
Die typischen Anwender sind kleine und mittlere Vertriebsteams: ein paar Leute, die wissen müssen, welche Chance als Nächstes Aufmerksamkeit braucht. Nicht der Konzern-Vertrieb mit dreistufiger Freigabekette, sondern das Team, das Anfragen schnell in einen Prozess bekommen will.
Für eine Website ist ein Punkt entscheidend: Pipedrive dokumentiert seine REST-API öffentlich. JSON als Format, Authentifizierung per API-Token oder OAuth 2.0, benutzerdefinierte Felder, Webhooks. Wer eine Anbindung bauen will, muss weder raten noch verhandeln — es steht in der Entwicklerdokumentation. Genau das macht die Schnittstelle zu einer planbaren Leistung statt zu einem Versprechen.
Wer eine Anbindung plant, muss Pipedrives Datenmodell kennen — sonst landet alles in einem einzigen Feld. Eine Person ist der konkrete Ansprechpartner, eine Organisation das Unternehmen, in dem diese Person arbeitet. Ein Deal ist laut Dokumentation ein laufender Vorgang mit einer Person oder einer Organisation, der durch die Stufen einer Pipeline geführt wird, bis er gewonnen oder verloren ist. Eine Aktivität ist eine Handlung auf dem Weg dorthin: Anruf, Termin, Aufgabe.
Daneben steht der Leads-Eingang — ein eigener Posteingang für vorqualifizierte, noch nicht in die Pipeline übernommene Anfragen. Ein Lead muss dabei laut Dokumentation immer mit einer Person oder einer Organisation verknüpft sein und lässt sich später in einen Deal überführen.
Daraus folgt die wichtigste Erkenntnis für jede Formularstrecke: Ein Website-Lead ist selten „ein Kontakt". In der Regel entstehen mehrere verbundene Objekte auf einmal — Person, im Geschäftskundenfall zusätzlich Organisation, dazu ein Deal in einer bestimmten Stufe und häufig eine Aktivität als Wiedervorlage. Welche davon ein bestimmtes Formular erzeugt, gehört ins Konzept, nicht in den Code.
// praxis
serverseitig · nie im browser
Die erste Entscheidung fällt vor der ersten Zeile Code, und sie ist keine Geschmacksfrage: Das Formular gehört der Website, nicht dem CRM. Es entsteht im eigenen Design, mit den eigenen Feldern, der eigenen Fehlerdarstellung und in derselben Barrierefreiheit wie der Rest der Seite. Eingebettete Fremdformulare bringen fremdes Layout, fremdes Ladeverhalten und fremde Datenflüsse mit — alles drei will man an genau der Stelle nicht, an der eine Anfrage entsteht.
Dahinter steht ein serverseitiger Endpunkt auf der eigenen Domain. Er nimmt die Eingaben entgegen, prüft sie, hält das API-Token und spricht als Einziger mit Pipedrive. Damit verlässt der Schlüssel nie den Server, und die Übergabe lässt sich protokollieren, wiederholen und im Zweifel abschalten, ohne die Seite anzufassen. Ein Formular, das direkt aus dem Browser an ein CRM sendet, gibt sein Token an jeden weiter, der die Entwicklerkonsole öffnet.
Dann folgt das Mapping — die eigentliche Arbeit. Welches Formularfeld wird zur Person, welches zur Organisation, was landet im Deal-Titel, in welche Pipeline und Stufe geht der Vorgang, und wer wird Eigentümer? Beim Anlegen eines Deals sind laut Dokumentation unter anderem Titel, Wert, Währung, verknüpfte Person, verknüpfte Organisation, Pipeline, Stufe und Besitzer vorgesehen — die Zuordnung steht als Dokument, bevor gebaut wird.
Ein Punkt, der in Angeboten fast immer fehlt und im Betrieb sofort auffällt: die Herkunft der Anfrage. Welches Formular, welche Seite, welche Kampagne — als benutzerdefiniertes Feld mitgegeben, damit im CRM nachvollziehbar bleibt, woraus dieser Lead entstanden ist. Ohne dieses Feld sitzt der Vertrieb vor einer Liste gleich aussehender Anfragen und das Marketing kann nicht beantworten, was funktioniert hat.
Danach die Dublettenprüfung. Dieselbe Person schickt ein Formular zweimal ab — das ist der Normalfall, nicht die Ausnahme. Deshalb sucht der Endpunkt vor dem Anlegen, findet die Person über ihre E-Mail-Adresse und aktualisiert sie, statt einen zweiten Datensatz zu erzeugen. Was mit dem Deal geschieht, ist eine Absprache mit dem Vertrieb: ein neuer Vorgang oder eine Notiz am bestehenden.
Und zuletzt der Teil, an dem sich eine Anbindung entscheidet: der Fehlerfall. Die Anfrage wird zuerst auf dem eigenen Server gesichert und erst danach übergeben. Antwortet Pipedrive nicht, langsam oder mit einem Fehler, wird protokolliert und mit Abstand erneut versucht; zusätzlich geht die Anfrage per E-Mail raus. Kein Lead darf verloren gehen, nur weil ein fremdes System gerade eine schlechte Minute hat. Die buchbare Leistung dahinter steht unter Schnittstellenentwicklung.
// technik · 6 details
belegt aus der doku
Was hier steht, stammt aus der öffentlichen Entwicklerdokumentation von Pipedrive — Adressen, Parameter und Bezeichnungen im Original. Wo die Dokumentation Zahlen nennt, stehen sie hier; wo sie keine nennt, steht auch hier keine.
// d-01zugang
Zwei Wege sind dokumentiert. Das API-Token geht im Header x-api-token mit; es gehört zu einem Nutzer in einer Firma, es gibt nur ein aktives, und es liegt in den Unternehmenseinstellungen unter den persönlichen Einstellungen. Der zweite Weg ist OAuth 2.0 mit einem Access-Token im Authorization-Header. Für eine Website-Anbindung reicht meist ein eigenes Token — auf einem eigenen Nutzer, nicht auf dem des Vertriebsleiters.
zweck: authentifizierung
// d-02adressen
Die Basis-Adresse enthält die eigene Firmen-Subdomain und hat in Version 2 die Form https://{COMPANYDOMAIN}.pipedrive.com/api/v2; die Objekttypen stehen in der Mehrzahl dahinter, etwa /api/v2/deals. Dokumentiert sind GET, POST, PUT, PATCH und DELETE, der Content-Type ist application/json, und alle Anfragen laufen über HTTPS. Version 2 nimmt ausschließlich JSON-Rümpfe entgegen.
zweck: transport
// d-03der deal
Beim Anlegen eines Deals ist der Titel Pflicht; optional sind laut Dokumentation unter anderem Wert und Währung, die verknüpfte Person und Organisation, Pipeline und Stufe, der Besitzer, der Status, die Wahrscheinlichkeit, das erwartete Abschlussdatum, Labels und ein Objekt für benutzerdefinierte Felder. Damit landet eine Website-Anfrage nicht irgendwo, sondern genau in der Stufe, die der Vertrieb dafür vorgesehen hat.
zweck: vorgang anlegen
// d-04eigene felder
Hier stolpern die meisten Anbindungen. Benutzerdefinierte Felder tragen keine sprechenden Namen, sondern zufällig erzeugte Kennungen aus 40 Zeichen — und die unterscheiden sich von Konto zu Konto. In den Datenfeld-Einstellungen lässt sich der API-Schlüssel eines Feldes über das Dreipunkt-Menü kopieren. Dokumentiert sind 16 Feldtypen, von Text über Geldbetrag und Auswahl bis Datum, Zeitraum und Adresse.
zweck: kontext & herkunft
// d-05rückweg
Pipedrive kann Änderungen selbst melden, statt abgefragt zu werden: ein POST mit JSON an eine öffentlich erreichbare Adresse, gefiltert nach Aktion (added, deleted, merged, updated) und Objekt (unter anderem deal, person, organization, activity, stage). Der Endpunkt lässt sich per HTTP-Basic-Auth absichern. Erwartet wird ein 2XX; sonst wird nach 3, 30 und 150 Sekunden erneut zugestellt.
zweck: crm meldet sich
// d-06grenzen
Die API rechnet mit einem täglichen Token-Budget: 30.000 Basis-Token, multipliziert mit dem Faktor des gebuchten Tarifs und der Zahl der Sitzplätze. Dazu kommen kurzfristige Grenzen in einem rollierenden Zwei-Sekunden-Fenster je Nutzer. Ist das Budget aufgebraucht, kommt der Status 429; Kopfzeilen wie x-ratelimit-remaining zeigen den Stand. Für ein Formular ist das unkritisch — für einen Massenabgleich nicht.
zweck: sparsam abfragen
Zwei Dinge entscheiden darüber, ob eine Anbindung nach drei Monaten noch Freude macht. Das erste ist die Dublettenprüfung. Die Personen-Suche der API durchsucht laut Dokumentation Name, E-Mail, Telefon, Notizen und benutzerdefinierte Felder; sie ist ein Aufruf mit engerem Berechtigungsumfang auf die allgemeine Objektsuche. Mit der Einstellung für die exakte Übereinstimmung zählt nur der vollständige Treffer, unabhängig von Groß- und Kleinschreibung. In Version 2 heißt diese Einstellung nicht mehr Schalter, sondern Textwert — ein kleines Detail, das eine ältere Anbindung stillschweigend anders arbeiten lässt.
Das zweite ist die Fehlerbehandlung. Eine Übergabe kann aus vielen Gründen scheitern: Zeitüberschreitung, Wartungsfenster, aufgebrauchtes Token-Budget, ein Feld, das im CRM umbenannt wurde. Deshalb gilt die Reihenfolge: erst sichern, dann übergeben. Fehlgeschlagene Übergaben landen in einer Warteschlange und werden mit wachsendem Abstand wiederholt; die Anfrage geht parallel per E-Mail raus, und der Absender sieht davon nichts. Auch der Rückweg gehört durchdacht — Webhooks melden zurück, wenn ein Deal im CRM die Stufe wechselt oder gewonnen wird, und die Website kann daraus etwas machen: eine Bestätigung, einen Status im Kundenbereich, eine Auswertung.
Bleibt die Qualität der Daten. Ein Pflichtfeld, das niemand braucht, kostet Abschlüsse; ein fehlendes Feld kostet Zeit im Vertrieb. Deshalb entsteht das Formular gemeinsam mit denen, die später damit arbeiten — mehr dazu in Formularstrecken und bei Lead-Magnet-Formularen.
// integration
drei systeme · ein muster
Die Anbindung bauen wir in jedem System selbst — mit den Bordmitteln, die das CMS dafür mitbringt. Der Weg ist überall derselbe und ist bewusst systemunabhängig gedacht: Das Formular liegt im CMS, gepflegt von der Redaktion, gestaltet wie der Rest der Seite. Abgeschickt wird an einen serverseitigen Endpunkt auf derselben Domain. Dort werden die Eingaben validiert, auf die Pipedrive-Objekte abgebildet und als Person, Organisation und Deal in die vereinbarte Pipeline-Stufe übergeben, begleitet von den benutzerdefinierten Feldern für Herkunft und Kontext. Das Token liegt in der Konfiguration des Servers und wird nie ausgeliefert.
Der letzte Schritt ist die Rückmeldung an den Absender — und die soll ehrlich sein. Der Endpunkt antwortet mit dem, was tatsächlich passiert ist: angenommen, angenommen und in Bearbeitung, oder mit einem konkreten Hinweis, welches Feld nicht gepasst hat. Ist Pipedrive gerade nicht erreichbar, sieht der Absender trotzdem eine Bestätigung, denn seine Anfrage ist gesichert und wird nachgeliefert. Dazu kommen die Bestätigungs-E-Mail und die Weiterleitung auf eine eigene Danke-Seite, die sich als Ziel messen lässt. Welches CMS darunter arbeitet, ändert an dieser Kette nichts — nur daran, wo Formular, Route und Token liegen.
// cms-01typo3
In TYPO3 entsteht die Anbindung als eigene Extension. Das Formular wird zum Plugin-Element, das die Redaktion auf jeder Seite platziert und dessen Felder sich pro Einsatzort konfigurieren lassen — ein Kontaktformular und ein Rückrufwunsch dürfen unterschiedlich aussehen und trotzdem im selben Deal-Prozess landen. Die Übergabe an Pipedrive läuft über eine serverseitige Route mit eigener Middleware, die den Aufruf validiert, protokolliert und im Fehlerfall zur Wiederholung einreiht. Das API-Token liegt in der Extension-Konfiguration und damit in der Server-Umgebung, nicht im Frontend. Gerendert wird mit Fluid: Formular, Fehlerdarstellung und Bestätigung als Templates, die sich in das Design der Seite einfügen statt daneben zu stehen.
// cms-02wordpress
In WordPress bauen wir ein eigenes Plugin statt Theme-Code — so übersteht die Anbindung einen Theme-Wechsel und einen Relaunch des Designs. Eine eigene REST-Route nimmt die Formulardaten entgegen, prüft sie serverseitig und übergibt sie an Pipedrive; dieselbe Route dient als Empfänger für eingehende Webhooks, wenn das CRM eine Änderung zurückmelden soll. Das Token liegt in der wp-config.php oder in einer Umgebungsvariablen und wird nie an den Browser ausgeliefert. Fürs Frontend kommen Template-Dateien und Blöcke für den Editor dazu, damit die Redaktion das Formular dort einsetzt, wo es hingehört, und Feldbeschriftungen ändern kann, ohne einen Entwickler zu brauchen.
// cms-03statamic
Unter Statamic arbeitet Laravel — und damit steht der ganze Werkzeugkasten bereit, den eine saubere Übergabe braucht. Eine Route mit zugehörigem Controller nimmt das Formular entgegen, ein Blueprint beschreibt das Formularmodell mit seinen Feldern und Pflichtangaben, sodass Redaktion und Code dieselbe Definition benutzen. Das API-Token steht in der .env und bleibt außerhalb des Repositorys. Fehlgeschlagene Übergaben wandern in eine Warteschlange und werden vom Scheduler erneut versucht. Gerendert wird mit Antlers oder Blade, Bestätigung und Fehlerdarstellung inklusive; im Control Panel sieht die Redaktion die eingegangenen Anfragen und den Zustellstatus.
// datenschutz
datensparsam · nachvollziehbar
Bei einer CRM-Anbindung fließen von der ersten Zeile an personenbezogene Daten — Name, E-Mail, Telefonnummer, oft dazu ein Freitext, in dem Menschen erstaunlich viel über sich erzählen. Das ist kein technisches Randthema, sondern der Kern der Aufgabe. Wer im Verhältnis wer ist, lässt sich klar benennen: Der Betreiber der Website ist Verantwortlicher, der CRM-Anbieter verarbeitet in seinem Auftrag. Pipedrive stellt dafür ein Data Processing Addendum bereit und führt eine Liste der eingesetzten Unterauftragsverarbeiter.
Praktisch wird daraus Datensparsamkeit. Jedes Pflichtfeld muss sich begründen lassen — nicht mit „könnte man mal brauchen", sondern mit einem konkreten Schritt im Vertriebsprozess. Was nicht gebraucht wird, wird nicht abgefragt und schon gar nicht übertragen. Dieselbe Regel gilt für das, was der Server zusätzlich mitschickt: Die Herkunft einer Anfrage gehört ins CRM, ein vollständiges Bewegungsprofil des Besuchers nicht.
Die Einwilligung steht am Formular, nicht im Kleingedruckten: verständlich formuliert, ohne Vorauswahl, mit Verweis auf die Datenschutzerklärung, in der das Zielsystem benannt ist. Und sie wird dokumentiert — Zeitpunkt und Textstand — damit später niemand raten muss, worin genau eingewilligt wurde.
Technisch bleiben drei Punkte nicht verhandelbar: Das Token liegt auf dem Server und nie im ausgelieferten Quelltext, die Übertragung läuft ausschließlich über HTTPS, und eingehende Webhook-Aufrufe werden geprüft, bevor sie irgendetwas auslösen. Dazu kommen Löschfristen für die lokal gesicherten Anfragen: Was übergeben und verarbeitet ist, muss auf dem Webserver nicht dauerhaft liegen bleiben. Wie wir das grundsätzlich handhaben, steht unter Sicherheit & Datenschutz.
// faq
Pipedrive ist ein cloudbasiertes CRM, das um die Vertriebs-Pipeline herum gebaut ist: Ein Deal wandert durch die Stufen einer Pipeline, bis er gewonnen oder verloren ist. Entstanden ist das System 2010 in Estland, gegründet von Vertrieblern für Vertriebler. Die typischen Anwender sind kleine und mittlere Vertriebsteams, die einen klaren Blick auf ihre offenen Chancen brauchen und kein Auswertungswerkzeug für die Geschäftsführung. Für die Website zählt vor allem eines: Pipedrive dokumentiert seine REST-API öffentlich, mit JSON als Format, benutzerdefinierten Feldern und Webhooks.
Über ein eigenes Formular im Design der Website und einen serverseitigen Endpunkt dahinter. Der Browser schickt die Eingaben an die eigene Domain, dort werden sie validiert, gegen automatisierte Einsendungen geprüft und auf die Objekte der Pipedrive-API abgebildet. Erst der Server spricht mit Pipedrive: Er hält das Token, setzt Pipeline und Stufe und wertet die Antwort aus. Der Absender bekommt danach eine Rückmeldung, die zum Ergebnis passt. Ein Formular, das direkt aus dem Browser mit dem CRM spricht, bauen wir nicht — das Token wäre für jeden lesbar, der die Seite öffnet.
Selten nur ein Kontakt. Pipedrive kennt Personen als die konkreten Ansprechpartner und Organisationen als die Unternehmen, in denen diese Personen arbeiten. Ein Deal ist laut Dokumentation ein laufender Vorgang mit einer Person oder einer Organisation, der durch die Stufen einer Pipeline läuft, bis er gewonnen oder verloren ist. Eine Aktivität ist eine Handlung auf dem Weg dorthin, etwa ein Anruf, ein Termin oder eine Aufgabe. Aus einer Anfrage wird deshalb meist eine Person, im Geschäftskundenfall zusätzlich eine Organisation, dazu ein Deal in einer festgelegten Pipeline-Stufe und oft eine Aktivität als Wiedervorlage. Alternativ nimmt der Leads-Eingang vorqualifizierte Anfragen auf, die später in einen Deal überführt werden.
Sie ist eine REST-API mit JSON. Die Basis-Adresse enthält die eigene Firmen-Subdomain und hat in Version 2 die Form https://{COMPANYDOMAIN}.pipedrive.com/api/v2, die Objekttypen stehen in der Mehrzahl dahinter, etwa /api/v2/deals. Alle Anfragen laufen laut Dokumentation über HTTPS, der Content-Type ist application/json. Authentifiziert wird entweder mit einem API-Token im Header x-api-token — das Token gehört zu einem Nutzer in einer Firma und liegt in den Unternehmenseinstellungen unter den persönlichen Einstellungen — oder über OAuth 2.0 mit einem Access-Token im Authorization-Header. Benutzerdefinierte Felder tragen dabei keine sprechenden Namen, sondern zufällig erzeugte Kennungen aus 40 Zeichen, die sich von Konto zu Konto unterscheiden.
Dann darf im CRM kein zweiter Datensatz entstehen. Vor dem Anlegen sucht der Endpunkt deshalb erst. Die Personen-Suche der API durchsucht laut Dokumentation Name, E-Mail, Telefon, Notizen und benutzerdefinierte Felder, und mit der Einstellung für die exakte Übereinstimmung zählt nur der vollständige Treffer, unabhängig von Groß- und Kleinschreibung. Wird die Person über ihre E-Mail-Adresse gefunden, aktualisieren wir sie, statt sie neu anzulegen. Ob daneben ein zweiter Deal entsteht oder der bestehende nur eine Notiz bekommt, ist eine Absprache mit dem Vertrieb und keine technische Frage: Beides ist umsetzbar, aber nur eines passt zum Prozess.
Dann ist der Lead trotzdem gesichert. Die Anfrage wird zuerst auf dem eigenen Server abgelegt und erst danach an Pipedrive übergeben. Scheitert die Übergabe, wird sie protokolliert und mit Abstand erneut versucht; parallel geht die Anfrage per E-Mail an das Postfach, das ohnehin gelesen wird. Denselben Umgang verlangen die Rate Limits: Pipedrive rechnet laut Dokumentation mit einem täglichen Token-Budget und zusätzlich mit kurzfristigen Grenzen in einem rollierenden Zwei-Sekunden-Fenster; ist das Budget aufgebraucht, antwortet die API mit dem Status 429. Ein Formular, das darauf mit einer Fehlermeldung an den Absender reagiert, verliert eine Anfrage. Ein Formular, das den Vorgang einreiht und später zustellt, nicht.
Es geht um personenbezogene Daten, und zwar ab dem ersten Tastendruck im Formular. Drei Punkte sind nicht verhandelbar: Das Token liegt auf dem Server und nie im Frontend, übertragen wird ausschließlich über HTTPS, und das Formular fragt nur ab, was der Vertrieb wirklich braucht — jedes Pflichtfeld muss sich begründen lassen. Dazu kommen eine saubere Einwilligung mit Hinweis auf die Verarbeitung im CRM, eine Datenschutzerklärung, die das Zielsystem benennt, und ein Auftragsverarbeitungsvertrag mit dem Anbieter. Pipedrive stellt dafür ein Data Processing Addendum bereit und führt eine Liste der eingesetzten Unterauftragsverarbeiter. Auch Löschfristen gehören festgelegt: Eine Anfrage, aus der nie etwas wurde, muss nicht dauerhaft im System stehen bleiben.
Ja, in allen dreien — und zwar als eigene Entwicklung mit den Bordmitteln des jeweiligen Systems. In TYPO3 bauen wir eine eigene Extension: das Formular als Plugin-Element, eine serverseitige Route mit Middleware für die Übergabe, Fluid für die Ausgabe und das Token in der Extension-Konfiguration. In WordPress entsteht ein eigenes Plugin statt Theme-Code, damit die Anbindung einen Theme-Wechsel übersteht: eine eigene REST-Route nimmt die Übergabe entgegen, das Token liegt in der wp-config.php oder in einer Umgebungsvariablen, ausgegeben wird über Template-Dateien und Blöcke für den Editor. In Statamic arbeitet Laravel darunter: Route plus Controller für die Übergabe, ein Blueprint als Modell des Formulars, das Token in der .env, gerendert mit Antlers oder Blade. Die Mechanik ist überall dieselbe, nur die Werkzeuge heißen anders.
// womit das zusammenhängt
systeme, formulare & leistung
// stack · schnittstelle
Die Plattform aus CRM, Marketing und Service — anderes Datenmodell, dieselbe Frage: Was gehört ins CRM und was bleibt auf der Website?
zur technik →
// stack · schnittstelle
Das CRM für größere Vertriebsorganisationen: mehr Objekte, mehr Regeln, mehr Abstimmung — und deshalb ein umso wichtigeres Mapping.
zur technik →
// stack · schnittstelle
Wenn aus dem Lead ein Newsletter-Empfänger wird: E-Mail-Marketing neben dem CRM, mit eigener Einwilligung und eigener Liste.
zur technik →
// leistung · formulare
Das Formular davor: Feldlogik, Mehrschrittigkeit, Validierung, Barrierefreiheit und eine Bestätigung, die tatsächlich bestätigt.
zur leistung →
// leistung · leads
Der Anlass für die Anfrage: Whitepaper, Checkliste, Rechner — und der Weg vom Download in einen Vertriebsprozess.
zur leistung →
// leistung · buchen
Die Technik hier, das Angebot dort: Analyse, Feld-Mapping, Umsetzung, Test auf Staging, Monitoring und Betrieb. Hier wird gebucht.
zur leistung →
// Leads aus dem Formular direkt nach Pipedrive?
Projekt anfragen