Setup-Guide — Boniforce für HubSpot
Boniforce installieren, konfigurieren und direkt in HubSpot-Unternehmen nutzen. Geschätzte Einrichtungszeit: 5–10 Minuten.
Zuletzt aktualisiert: 22.07.2026
Inhalt
1. Was die Boniforce-App macht
Boniforce ergänzt HubSpot-Unternehmensdatensätze um deutsche B2B-Bonitätsinformationen. Nutzer können eine Firma identifizieren, einen Boniscore auf Abruf erstellen oder aktualisieren und das Ergebnis im Unternehmensdatensatz sehen. Die App kann unter anderem Boniscore, Risikoklasse, Berichtsdatum, Kreditlimit, Registerdaten, Finanzdaten-Verfügbarkeit, Unternehmensprofil und Zahlungsempfehlung in eigens angelegte boniforce_*-Eigenschaften schreiben.
Die App unterstützt die manuelle Nutzung auf einem Unternehmensdatensatz sowie benutzerinitiierte HubSpot-Workflow-Aktionen. Sie installiert sich kostenlos. Boniforce-Berichte werden über deinen separaten Boniforce-Vertrag und dessen Kontingent abgerechnet.
2. Voraussetzungen
- Ein HubSpot-Produktionskonto oder eine HubSpot-Sandbox.
- Ein HubSpot-Nutzer mit der Berechtigung, Marketplace-Apps zu installieren. Für die Eingabe des Boniforce-API-Schlüssels ist ein Portal-Admin erforderlich.
- Ein aktiver Boniforce-Vertrag oder ein Sandbox-Zugang. Einen Testzugang kannst du über team@boniforce.de anfragen.
- Ein Boniforce-API-Schlüssel aus dem Boniforce-Dashboard.
- Die App ist für Unternehmen mit deutscher Register- beziehungsweise Boniforce-Abdeckung vorgesehen.
3. Boniforce installieren und mit HubSpot verbinden
Installation starten
Öffne den Installationslink. Wenn du noch nicht bei HubSpot angemeldet bist, melde dich zunächst an.
HubSpot-Konto auswählen
Wähle das HubSpot-Konto aus, in dem du Boniforce verwenden möchtest. Achte bei mehreren Konten auf den richtigen Kontonamen und die richtige Hub-ID.
Zugriff prüfen und genehmigen
HubSpot zeigt die von Boniforce angeforderten Berechtigungen an. Prüfe sie und klicke auf App verknüpfen beziehungsweise Connect app. Die vollständige Erklärung der Berechtigungen findest du im nächsten Abschnitt.
Installation bestätigen
Nach erfolgreicher OAuth-Verknüpfung erscheint die Boniforce-Bestätigungsseite. Die App legt anschließend die Eigenschaftsgruppe Boniforce und die zugehörigen Unternehmens-Eigenschaften an. Das kann einige Sekunden dauern.
Unternehmen öffnen
Klicke auf Open Companies oder öffne in HubSpot CRM → Unternehmen. Öffne einen deutschen Unternehmensdatensatz. Die Boniforce-Karte erscheint im Datensatz.
4. Warum Boniforce diese HubSpot-Berechtigungen benötigt
| OAuth-Scope | Verwendung | Datenrichtung |
|---|---|---|
crm.objects.companies.read | Liest den geöffneten Unternehmensdatensatz und die für die Firmenidentifikation benötigten Felder. | Von HubSpot zu Boniforce |
crm.objects.companies.write | Schreibt Boniscore, Risikoklasse, Registerdaten, Berichtsdatum und weitere Boniforce-Ergebnisse in den Unternehmensdatensatz. | Zu HubSpot |
crm.schemas.companies.write | Legt die Eigenschaftsgruppe Boniforce und die boniforce_*-Eigenschaften an. | Zu HubSpot |
automation | Stellt die benutzerdefinierten Boniforce-Aktionen in HubSpot-Workflows bereit. | Je nach verwendeter Aktion |
settings.users.read | Prüft, ob der aufrufende Nutzer Admin- oder CRM-Berechtigungen hat, und ordnet kostenpflichtige Aktionen für das Audit-Protokoll einem HubSpot-Nutzer zu. | Von HubSpot zu Boniforce |
oauth | Verknüpft dein HubSpot-Konto sicher mit der App und ermöglicht die Erneuerung der Autorisierung. | Autorisierung |
5. Boniforce konfigurieren
Boniforce-Einstellungen öffnen
Öffne in HubSpot die Boniforce-App-Einstellungen. Du kannst sie auch über den Hinweis in der Boniforce-Karte auf einem Unternehmensdatensatz erreichen.
API-Schlüssel einfügen
Füge deinen Boniforce-API-Schlüssel in das Feld Boniforce-API-Schlüssel ein und klicke auf Verbinden. Nur ein Portal-Admin kann den Schlüssel hinzufügen oder ersetzen.
Verbindung prüfen
Die App validiert den Schlüssel über die Boniforce-API. Bei Erfolg zeigt der Status Verbunden und das Abonnement AKTIV. Die Einstellungen zeigen außerdem die Anzahl erfolgreicher Berichte im aktuellen Abrechnungszeitraum.
6. Boniforce manuell auf einem Unternehmen verwenden
Unternehmensdatensatz öffnen
Öffne unter CRM → Unternehmen das Unternehmen, das du prüfen möchtest. Für zuverlässige Treffer sollten Firmenname, Ort und vorhandene Registerdaten korrekt gepflegt sein.
Rechtsträger identifizieren
Falls das Unternehmen noch nicht zugeordnet ist, starte die Suche in der Boniforce-Karte. Prüfe die Treffer und wähle den richtigen deutschen Rechtsträger anhand von Name, Adresse, Registergericht und Registernummer aus. Die Suche allein erzeugt keinen kostenpflichtigen Bericht.
Boniscore abrufen
Klicke auf Boniscore abrufen beziehungsweise die in der Karte angezeigte Aktualisierungsaktion. Ein neuer Bericht dauert typischerweise 30–90 Sekunden. Verlasse den Datensatz während der Verarbeitung möglichst nicht.
Ergebnis verwenden
Die Karte zeigt den Boniscore, Risikohinweise, Kreditlimit, Berichtsdatum sowie – sofern verfügbar – Finanzkennzahlen und Profilinformationen. Gleichzeitig schreibt die App die aktuellen Werte in die boniforce_*-Unternehmens-Eigenschaften, sodass sie in Ansichten, Listen, Berichten und weiteren HubSpot-Prozessen verwendet werden können.
7. Boniforce in HubSpot-Workflows verwenden
Erstelle oder bearbeite einen unternehmensbasierten Workflow und füge über das Aktionspanel eine Boniforce-Aktion hinzu. Veröffentliche den Workflow erst, nachdem du Aufnahmekriterien, Aktion und mögliche Berichtskosten geprüft hast.
| Workflow-Aktion | Verhalten | Kostenhinweis |
|---|---|---|
| Enrich Company with Boniforce | Ermittelt oder aktualisiert den Boniscore des aufgenommenen Unternehmens und schreibt die Ergebnisse nach HubSpot. Mit „Reuse fresh score“ können frische Ergebnisse wiederverwendet werden. | Kann einen neuen kostenpflichtigen Bericht erzeugen. |
| Get or refresh Boniforce credit score | Verwendet standardmäßig einen frischen vorhandenen Score. Mit „Force refresh“ wird unabhängig vom Cache ein neuer Bericht erzeugt. | Erzeugt bei veraltetem Score oder erzwungener Aktualisierung einen kostenpflichtigen Bericht. |
| Look up a German company in Boniforce | Sucht passende deutsche Rechtsträger anhand des Firmennamens und optional des Registergerichts. | Die Suche selbst erzeugt keinen kostenpflichtigen Bericht. |
8. Daten und Synchronisierung
Keine automatische Vollsynchronisierung: Boniforce importiert weder alle bestehenden noch automatisch alle neuen HubSpot-Unternehmen. Ein Unternehmen wird nur verarbeitet, wenn ein Nutzer eine Aktion auf dem Datensatz startet oder wenn es in einen von deinem Team konfigurierten HubSpot-Workflow aufgenommen wird.
- Von HubSpot gelesen: Unternehmensdaten für Identifikation und Anzeige sowie Nutzerinformationen für Berechtigungsprüfung und Audit-Zuordnung.
- Nach HubSpot geschrieben: eigens angelegte Boniforce-Unternehmens-Eigenschaften mit Identifikations- und Berichtsergebnissen.
- Keine Überschreibung von Standardfeldern: Die App schreibt Berichtswerte in ihre eigene Eigenschaftsgruppe Boniforce.
- EU-Verarbeitung: App-eigene Daten werden in Frankfurt verarbeitet und gespeichert.
9. Boniforce-Zugriff pausieren oder trennen
Boniforce verwendet neben HubSpot OAuth keinen separaten Nutzer-Login. Wenn du vorübergehend verhindern möchtest, dass neue Berichte erstellt werden, widerrufe oder rotiere den verwendeten API-Schlüssel im Boniforce-Dashboard. Bereits in HubSpot gespeicherte boniforce_*-Werte bleiben dabei erhalten.
Wenn du ausschließlich den gespeicherten Boniforce-Schlüssel entfernen lassen möchtest, ohne die HubSpot-App zu deinstallieren, kontaktiere team@boniforce.de. Zum vollständigen Trennen der HubSpot-OAuth-Verbindung deinstalliere die App wie im nächsten Abschnitt beschrieben.
10. Boniforce aus HubSpot deinstallieren
- Öffne in HubSpot Einstellungen → Integrationen → Verknüpfte Apps.
- Suche nach Boniforce.
- Öffne das Aktionsmenü und wähle Deinstallieren.
- Bestätige die Deinstallation.
11. Troubleshooting
| Problem | Lösung |
|---|---|
| Die Boniforce-Karte erscheint nicht. | Lade den Unternehmensdatensatz neu. Prüfe unter Einstellungen → Integrationen → Verknüpfte Apps, ob Boniforce installiert ist, und kontrolliere die Nutzerberechtigung für Unternehmen. |
| Der API-Schlüssel wird abgelehnt. | Prüfe im Boniforce-Dashboard, ob der Schlüssel aktiv, vollständig kopiert und für die richtige Umgebung vorgesehen ist. Ersetze ihn anschließend in den Boniforce-Einstellungen. |
| Die Firmensuche liefert keinen eindeutigen Treffer. | Prüfe Firmenname, Ort, Rechtsform, Registergericht und Registernummer. Wähle bei mehreren Treffern den Rechtsträger manuell aus. |
| Der Bericht dauert länger als erwartet. | Warte bis zu drei Minuten und lade danach den Datensatz neu. Starte nicht mehrfach dieselbe Aktualisierung. Besteht das Problem weiter, sende Hub-ID, Unternehmens-ID und ungefähre Uhrzeit an den Support – niemals den API-Schlüssel. |
| „Permission denied“ / „Zugriff verweigert“. | Bitte einen HubSpot-Admin, deine Unternehmens- oder Admin-Berechtigungen zu prüfen. Nur Portal-Admins können den API-Schlüssel verwalten; Berichtserstellung erfordert Unternehmenszugriff. |
| Kontingent erschöpft oder Abonnement nicht aktiv. | Prüfe deinen Boniforce-Vertrag und das verfügbare Kontingent. Die App selbst kann das verbleibende Vertragskontingent nicht abrufen. |
Support
E-Mail: team@boniforce.de
Support-Seite: www.boniforce.de/hubspot/support/
Bitte sende für technische Fragen deine HubSpot-Hub-ID, die betroffene Unternehmens-ID, eine kurze Problembeschreibung und den ungefähren Zeitpunkt. Sende niemals deinen Boniforce-API-Schlüssel.