HubSpot API: was Sie bauen können, was der Betrieb braucht und wie Sie es beauftragen

Was ist die HubSpot API?

Die HubSpot API ist die Schnittstelle, über die andere Software mit Ihrem HubSpot-Account arbeitet, ohne dass jemand klickt. Die API arbeitet in drei Richtungen, und die meisten Projekte brauchen mehr als eine.

Die API ist eine Reihe von Webadressen unter api.hubapi.com, eine Familie je Objekt, die Daten kommen als JSON. Ein Entwickler braucht einen Zugriffsschlüssel mit den passenden Berechtigungen (HubSpot nennt sie Bereiche, englisch Scopes), die Dokumentation auf developers.hubspot.com und einen Test-Account. HubSpot gibt Entwicklern kostenlose Test-Accounts mit einer 90-tägigen Testversion vieler Enterprise-Funktionen.

Der HubSpot MCP-Server ist etwas anderes: Über ihn arbeiten KI-Assistenten wie ChatGPT oder Claude in HubSpot, und unser Ratgeber zum HubSpot MCP-Server behandelt ihn. Apps im HubSpot Marketplace nutzen die API ebenfalls, aber jemand anderes baut und betreibt sie.

Was können Sie mit der HubSpot API bauen?

Über die HubSpot API lassen sich fast alle Daten in HubSpot hinein- und herausbewegen. Das sind die Aufgaben, nach denen Unternehmen am häufigsten fragen, und womit sie in HubSpot gebaut werden.

Der ERP-Ratgeber zeigt, welche ERP-Daten Sie nach HubSpot holen und wer für jedes Feld zuständig ist.

Was die API Ihnen nicht abnimmt

• Rückgängig machen. Es gibt kein Rollback. Schreibt eine Integration falsche Werte in 20.000 Kontakte, reparieren Sie sie aus dem Eigenschaftsverlauf oder einem Export. Testen Sie zuerst an einer Kopie.
• Ihre Edition überspringen. Eine API für eine Funktion, die Ihr Abo nicht hat, etwa benutzerdefinierte Objekte unter Enterprise, antwortet mit einem Fehler.
• Ihre Regeln umgehen. Seit API-Version 2026-09 gelten bedingt erforderliche Eigenschaften und Pflichtfelder beim Anlegen auch für Schreibzugriffe über die API. Ein Aufruf ohne sie schlägt fehl.
• Datensätze für Sie abgleichen. Die API schreibt, was sie bekommt. Duplikate entstehen durch Integrationen, die anlegen, statt zuerst nachzusehen; unser Ratgeber zu Duplikaten zeigt die Regeln, die sie verhindern.
• Alles, was Sie klicken können. Einige Einstellungen haben noch keinen Endpunkt. Pipeline-Regeln und Objekt-Tags haben erst im September 2026 einen bekommen. Prüfen Sie die API-Referenz, bevor Sie eine Funktion darauf planen.

Welcher Weg für Ihre HubSpot-Integration passt: Marketplace-App, Make oder Zapier, Workflow-Code oder eigener Code

Wählen Sie den Weg nach der Aufgabe, dann danach, wer ihn betreut. Eigener Code kommt zuletzt, denn seine Pflege tragen Sie, solange er läuft.

Viele Teams starten mit Make oder Zapier und bleiben jahrelang dabei, für einfache Abläufe ist das in Ordnung. Muss eine Integration HubSpot und ein anderes System in beide Richtungen abgleichen oder große Mengen tragen, verlegen Sie sie auf eine Sync-App oder eigenen Code, bevor sich die Abläufe vermehren.

Zugriff auf die HubSpot API: Service-Schlüssel, Apps und das Ende der privaten Legacy-Apps

Jeder API-Aufruf trägt einen Zugriffsschlüssel. Seit September 2026 gibt es drei aktuelle Wege zu einem Schlüssel, und der Weg, den die meisten Anleitungen noch beschreiben, die private App, läuft aus.

Geben Sie jedem Schlüssel nur die Bereiche, die seine Aufgabe braucht. Ein Abgleich, der Unternehmen und Deals liest, bekommt Lese-Bereiche für Unternehmen und Deals, sonst nichts. Ein Schlüssel, der nur lesen darf, kann Ihre Daten auch in falschen Händen nicht ändern, und ein versehentlicher Schreibzugriff wird abgelehnt.

1. Schritt 01

   Service-Schlüssel anlegen

   Gehen Sie zu Entwicklung > Schlüssel > Service-Schlüssel und klicken Sie auf „Neuen Service-Schlüssel erstellen“. Benennen Sie ihn nach Aufgabe und System, etwa „ERP-Sync (nur lesen)“, denn der Name steht in den Protokollen. Anlegen können ihn nur Super-Admins und Benutzer mit der Berechtigung für Entwickler-Tools.

   

2. Schritt 02

   Nur die Bereiche auswählen, die die Aufgabe braucht

   Klicken Sie auf „Neuen Bereich hinzufügen“, suchen Sie das Objekt und wählen Sie den Lese- oder Schreib-Bereich. Bereiche mit Warnzeichen reichen an sensible oder hochsensible Daten; lassen Sie sie weg, außer die Aufgabe braucht genau diese Daten.

   

3. Schritt 03

   Den Schlüssel sicher übergeben

   Klicken Sie auf „Erstellen“. Der Schlüssel bleibt verborgen, bis jemand auf „Anzeigen“ klickt, und nur Admins sehen ihn. Geben Sie ihn Ihrem Entwickler über einen Passwort-Manager, nie per E-Mail oder Chat. Planen Sie alle sechs Monate eine Rotation: „Diesen Schlüssel später rotieren und verfallen lassen“ gibt sieben Tage für den Wechsel.

   

4. Schritt 04

   Das Aufrufprotokoll lesen

   Klicken Sie auf „Protokolle anzeigen“. Jeder Aufruf der letzten 30 Tage steht dort mit Ergebnis, Methode und Endpunkt. Ein 403 heißt, dass dem Schlüssel ein Bereich fehlt; hier wurde ein Schreibzugriff abgelehnt, weil der Schlüssel nur lesen darf. HubSpot speichert bei erfolgreichen Aufrufen keine Inhalte, protokollieren Sie also in Ihrem eigenen System, was Sie senden.

   

5. Schritt 05

   Die Tagesnutzung im Blick behalten

   Unter Entwicklung > Beobachten zeigt die „Nutzung von API-Aufrufen“ die Aufrufe der letzten 24 Stunden gegen Ihr Tageslimit, getrennt nach „Hier erstellte Apps und Service-Schlüssel“ und „Drittanbieter-Apps“. Alle privaten Apps und Schlüssel Ihres Accounts teilen sich ein Tageslimit.

   

HubSpot API-Limits je Edition

Die Nutzungsrichtlinien von HubSpot begrenzen die Aufrufe je 10 Sekunden für jede App und je Tag für den ganzen Account. Der Tag beginnt um Mitternacht in der Zeitzone, die in Ihrem Account eingestellt ist. Über dem Limit schlagen Aufrufe mit Fehler 429 fehl, bis das Zeitfenster vorbei ist.

Das Tageslimit ist selten das Problem. Fehler 429 kommen meist von Integrationen, die einen Datensatz je Aufruf aktualisieren, jede Nacht alle Datensätze neu lesen statt nur die geänderten oder sich auf die Suche stützen.

• Die Suche hat ein eigenes Limit: fünf Anfragen je Sekunde und Account, 200 Datensätze je Seite und 10.000 Treffer je Abfrage. Ein Abgleich, der jeden Datensatz über die Suche findet, stößt hier zuerst an.
• Alles im Batch: Bis zu 100 Datensätze je Aufruf anlegen, aktualisieren und lesen.
• Nur Änderungen lesen: Filtern Sie nach dem Datum der letzten Änderung, oder lassen Sie sich von Webhooks benachrichtigen.
• Große Exporte: Die Exports-API liefert ein ganzes Objekt in einer Datei.
• Webhooks aus Workflows zählen nicht gegen das API-Limit.

Welche HubSpot APIs welche Edition brauchen

Die meisten CRM-APIs funktionieren in jedem Abo, auch im kostenlosen CRM. Einige folgen der Funktion, zu der sie gehören.

Der Data-Hub-Ratgeber zeigt, was Data Hub Professional sonst bringt und wann es sich lohnt.

Ein Webhook braucht kein Data Hub. Die Workflow-Aktion „Webhook senden“ braucht es, aber eine App als HubSpot-Projekt kann Datensatzänderungen in jedem Abo abonnieren. Der App-Weg braucht einen Entwickler, die Workflow-Aktion ein paar Klicks.

HubSpot Webhooks und Custom Code: andere Systeme aus dem Workflow aufrufen

Mit Data Hub Professional führt ein Workflow Ihren eigenen JavaScript- oder Python-Code aus und ruft jede Webadresse auf. Workflow-Code deckt kurze Prüfungen und Übergaben ab, ohne eigenen Server. Das Beispiel prüft, ob das Unternehmen eines gewonnenen Deals eine ERP-Kundennummer hat, und schickt den Deal dann ans ERP.

1. Schritt 01

   Den Schlüssel als Geheimnis speichern

   Klicken Sie in der Aktion „Benutzerdefinierter Code“ auf „Geheimnis hinzufügen“ und fügen Sie dort den Service-Schlüssel ein. Der Code liest ihn als process.env, und der Schlüssel steht nie im Code. Alle Geheimnisse einer Aktion zusammen dürfen bis zu 1.000 Zeichen lang sein.

   

2. Schritt 02

   Werte für spätere Schritte zurückgeben

   Legen Sie Datenausgaben fest, etwa erp_ready und erp_customer_number. Spätere Aktionen und Verzweigungen nutzen sie, zum Beispiel um einen Deal ohne ERP-Nummer aufzuhalten, bevor er das ERP erreicht.

   

3. Schritt 03

   Den Deal per Webhook senden

   Fügen Sie „Webhook senden“ hinzu: Methode POST, die Adresse, auf der Ihr ERP wartet, ein API-Schlüssel aus einem Geheimnis im Anfrage-Header und nur die Felder, die das ERP braucht. HubSpot wiederholt einen fehlgeschlagenen Aufruf bis zu drei Tage lang.

   

Grenzen, die Sie einplanen müssen

• 20 Sekunden und 128 MB je Ausführung. Nächtliche Dateien und große Aufgaben gehören nicht hierher.
• Aufrufe über dem Limit werden bis zu drei Tage wiederholt, aber nur, wenn der Code den Fehler auslöst. Code, der ihn verschluckt, markiert die Ausführung als erledigt.
• Keine Versionsverwaltung. Der Code liegt im Workflow. Legen Sie den Quellcode in Ihrem Git-Repository ab, halten Sie die Aktion kurz und packen Sie die Logik in eine Bibliothek, die Sie dort testen.
• Jede Aufnahme ist eine Ausführung. Ein Workflow, der 50.000 Datensätze auf einmal aufnimmt, macht 50.000 Ausführungen samt ihren API-Aufrufen.

Für Vertriebsautomatisierung ohne Code zeigt unser Ratgeber zu Workflows im Vertrieb, was Standard-Workflows schon können.

App-Karten: Daten aus anderen Systemen am HubSpot-Datensatz zeigen

Eine App-Karte ist eine kleine Ansicht, die Ihr Entwickler in die Datensatzseite einbaut. Die Karte zeigt Daten, die woanders liegen, so sieht der Vertrieb das Kreditlimit oder die letzte Rechnung, ohne dass jede Rechnung nach HubSpot kopiert wird. App-Karten funktionieren in jedem Abo.

1. Schritt 01

   Die App als Projekt bauen

   Ihr Entwickler legt mit dem Kommandozeilen-Tool von HubSpot ein Projekt auf Plattformversion 2026.09 an, mit einer Karte und bei Bedarf Webhook-Abonnements. Das Projekt zeigt seine Bestandteile und seine Builds unter Entwicklung > Projekte.

   

2. Schritt 02

   Die App in Ihrem Account installieren

   Installieren Sie die App im Tab „Verteilung“. HubSpot listet die Bereiche, die die App anfordert, und warnt, dass die App nicht verifiziert ist; bei Ihrer eigenen App ist das normal. Prüfen Sie die Bereiche, bevor Sie das Kästchen anhaken.

   

3. Schritt 03

   Die nötigen Änderungen abonnieren

   Die Webhook-Abonnements stehen in der Projektdatei: hier ein neu angelegtes Unternehmen und eine geänderte Deal-Phase. HubSpot schickt sie an Ihren Server, sobald sie passieren. Bis zu 1.000 Abonnements je App.

   

4. Schritt 04

   Die Karte am Datensatz platzieren

   Setzen Sie die Karte beim Anpassen der Datensatzseite dorthin, wo der Vertrieb zuerst hinsieht. Ihr Entwickler kann die Werte in der Sprache und im Zahlenformat jedes Benutzers zeigen, wie hier.

   

Eine Karte, die nur HubSpot-Daten zeigt, braucht keinen Server. Eine Karte, die Daten live aus Ihrem ERP holt, braucht ein Backend, das Ihr Entwickler betreibt, oder die serverlosen Funktionen von HubSpot, die Enterprise brauchen.

HubSpot API-Versionen 2026 und die Fristen 2027

Seit März 2026 benennt HubSpot API-Versionen nach Datum, etwa /crm/objects/2026-09/contacts, und bringt jeden März und September eine neue heraus. Jede wird 18 Monate unterstützt. Die alten nummerierten Versionen laufen aus.

Eine API ohne Support wird an diesem Tag nicht abgeschaltet. HubSpot behebt dann keine Fehler mehr und garantiert nicht mehr, dass sie funktioniert. Hängt Ihr Auftragsprozess an einer Integration, behandeln Sie das Datum als Frist. HubSpot kündigt Änderungen, die bestehenden Code brechen, etwa 90 Tage vorher im Entwickler-Changelog an, deshalb muss es jemand lesen.

Stellen Sie Integrationen direkt auf die neueste datierte Version um. Ein Zwischenhalt bei v3 oder v4 heißt zweimal migrieren. Die Seite „Migrationen“ erkennt alte Aufrufe erst, wenn sie laufen, ein Quartalsexport, der diesen Monat nicht lief, fehlt dort also. Prüfen Sie auch den Code.

Was bei HubSpot-Integrationen bricht, und wem der Code gehört

Diese Fehler sehen wir bei HubSpot-Integrationen nach dem Start am häufigsten. Wenige davon beginnen im Code.

Fehlermeldungen der HubSpot API und was sie bedeuten

Das Aufrufprotokoll zeigt für jeden fehlgeschlagenen Aufruf einen Code. Die vier in dieser Tabelle kommen aus den Limits, Bereichen und Regeln oben.

Seit Herbst 2026 hat jede verknüpfte App in HubSpot eine formal zuständige Person, anfangs die Person, die sie installiert hat; ein Admin kann sie ändern. Wenn Sie einen Benutzer deaktivieren, warnt HubSpot, falls er für eine App zuständig ist oder sie installiert hat.

So briefen Sie einen Entwickler für eine HubSpot-Integration

Beantworten Sie diese zwölf Fragen, bevor jemand den Aufwand schätzt, damit jedes Angebot dieselbe Aufgabe kalkuliert.

1. 01Die Aufgabe in einem Satz, aus Sicht der Nutzer: „Der Vertrieb sieht offene Posten und die Liefersperre am Unternehmen, bevor er ein Angebot schreibt.“
2. 02Die Systeme und ihre Versionen, und ob jedes in der Cloud oder auf Ihren eigenen Servern läuft.
3. 03Jedes Feld, wer dafür zuständig ist und seine Richtung: welches System für das Feld maßgeblich ist und ob es in eine oder in beide Richtungen fließt.
4. 04Der Abgleichsschlüssel: die ID, die einen HubSpot-Datensatz mit dem im anderen System verbindet, nie ein Name.
5. 05Mengen: Datensätze heute, Änderungen am Tag, die Stunde mit der meisten Last.
6. 06Wie schnell es sein muss: Sekunden, stündlich oder nächtlich.
7. 07Fehler: Was passiert, wenn ein Datensatz fehlschlägt, wer davon erfährt und wie.
8. 08Zugriff: Service-Schlüssel oder App, mit welchen Bereichen, angelegt in Ihrem Account.
9. 09Ihre HubSpot-Regeln: Pflichtfelder, bedingte Eigenschaften und Workflows, die die Integration auslöst.
10. 10Testplan: eine Sandbox oder ein Test-Account, Testdatensätze und wer abnimmt.
11. 11Zuständigkeit: Wem gehören Code, Hosting, Schlüssel und Dokumentation, und wer liest danach das Entwickler-Changelog von HubSpot?
12. 12Version: die neueste datierte API-Version und Plattform 2026.09, nichts Altes.

HubSpot API-Projekte in Deutschland, Österreich und der Schweiz

• ERPs auf eigenen Servern. Viele ERPs hier, von SAP bis zu kleineren Systemen, laufen im eigenen Rechenzentrum. HubSpot kann sie nur aufrufen, wenn die IT eine Schnittstelle öffnet; sonst holt sich die Integration die Daten aus HubSpot. Klären Sie das zuerst.
• Auftragsverarbeitung. Ein Middleware-Tool, ein Hosting-Anbieter oder der Server eines Entwicklers verarbeitet Ihre Kundendaten. Prüfen Sie, wo es läuft und dass ein Auftragsverarbeitungsvertrag besteht. Die Entscheidung trifft Ihr Datenschutzbeauftragter; unser Ratgeber zum EU-Rechenzentrum zeigt, was HubSpot selbst wo speichert.
• Betriebsrat. Zeichnet eine Integration auf, was Mitarbeitende tun, etwa Anruf- oder Anmeldedaten, beziehen Sie den Betriebsrat ein, bevor sie startet.
• Formate. Die API von HubSpot sendet Zahlen mit Punkt und Datumsangaben im ISO-Format. Deutsche Formate gehören nur in die Anzeige, wie in der Karte oben.

So gehen wir bei HubSpot API-Projekten vor

Unsere Reihenfolge bei einem HubSpot API-Projekt, vom Briefing bis zur Übergabe.

1. Schritt 01

   Die Aufgabe aufnehmen

   Felder, Zuständige, Schlüssel und Mengen aus dem Briefing oben in einer Tabelle, abgestimmt mit den Leuten, die die Daten nutzen.
2. Schritt 02

   Prüfen, was es schon gibt

   Marketplace-Apps, HubSpots eigener Datenabgleich und Tools, die Sie schon nutzen, geprüft gegen die Tabelle.
3. Schritt 03

   Die Lücke bauen

   Nur, was nichts anderes abdeckt, auf der neuesten Version, mit Schlüsseln, die nur lesen dürfen, wo Lesen reicht, und mit Warnungen bei Fehlern.
4. Schritt 04

   Übergeben

   Code in Ihrem Repository, Schlüssel in Ihrem Account, eine benannte zuständige Person und ein kurzes Betriebshandbuch für den Fall, dass etwas ausfällt.

Häufige Fragen