# HubSpot

Aktualisieren oder legen Sie den HubSpot-Kontakt hinter jeder Einreichung an, abgeglichen per E-Mail-Adresse.

## Was Sie erhalten

- Ein HubSpot-Kontakt pro E-Mail-Adresse: Ein vorhandener Kontakt wird aktualisiert, eine neue E-Mail-Adresse legt einen Kontakt an
- Feldzuordnung auf Feldebene zu Kontakteigenschaften mit Typkompatibilitätsprüfungen
- Eine Bearbeitung durch die befragte Person aktualisiert denselben Kontakt erneut
- Leere Antworten löschen nie eine Eigenschaft, und Eigenschaften, die Sie nicht zuordnen, bleiben unverändert
- Eine Rechtsgrundlage für neue Kontakte, für Konten, die eine verlangen
- Ein Test, der nur einen eigenen Testkontakt berührt
- Einen Kontakt im Sheet Neue Anfrage finden, den Request daraus vorausfüllen und die Antworten in diesen Kontakt zurückschreiben

## HubSpot verbinden

1. **Formulareinstellungen → Integrationen öffnen**

   Wählen Sie HubSpot in der Gruppe CRM.

2. **Ein HubSpot-Konto verbinden**

   Wählen Sie ein vorhandenes verbundenes HubSpot-Konto oder verbinden Sie ein neues. Sie werden zu HubSpot weitergeleitet, um das Konto auszuwählen und den Zugriff zu genehmigen. Formstep lädt anschließend die Kontakteigenschaften des Kontos und zeigt an, wie viele zur Zuordnung bereitstehen.

3. **Formularfelder → Kontakteigenschaften zuordnen**

   Ordnen Sie jedes Formularfeld einer Kontakteigenschaft zu. Es werden nur kompatible Eigenschaften angezeigt. Ein Formularfeld muss E-Mail zugeordnet werden, denn so wird der Kontakt gefunden. Der Pfeil in jeder Zeile legt fest, in welche Richtung Werte gehen: → Antworten aktualisieren HubSpot, ← ein Kontakt, den Sie auswählen, füllt das Feld vor, ↔ beides. Verlangt das Konto eine Rechtsgrundlage, wählen Sie hier ebenfalls eine aus.

4. **Fertigstellen**

   Verwenden Sie „Test senden", um Beispielwerte in den Testkontakt formstep-test\@example.com zu schreiben. Neue Einreichungen aktualisieren Kontakte, sobald Sie speichern.

## Wie eine Einreichung ihren Kontakt findet

Die Antwort auf das Formularfeld, das Sie **E-Mail** zugeordnet haben, entscheidet, zu welchem Kontakt eine Einreichung gehört. Bei jeder abgeschlossenen Einreichung geht Formstep so vor:

1. Es aktualisiert den HubSpot-Kontakt mit dieser E-Mail-Adresse und schreibt nur die Eigenschaften, die Sie zugeordnet haben.

2. Es legt den Kontakt an, wenn kein Kontakt diese E-Mail-Adresse hat. Ein neuer Kontakt erhält die zugeordneten Antworten, die E-Mail-Adresse und die Rechtsgrundlage.

Bearbeitet eine befragte Person ihre Einreichung, wird derselbe Kontakt mit den neuen Antworten erneut aktualisiert. Eine leer gelassene Antwort wird übersprungen und löscht daher nie einen Wert, der bereits in HubSpot steht, und Eigenschaften, die Sie nicht zugeordnet haben, werden nie angefasst.

Ein Request, den Sie im Sheet Neue Anfrage aus einem Kontakt vorausgefüllt haben, ist die Ausnahme: Seine Antworten aktualisieren diesen Kontakt, unabhängig davon, welche E-Mail-Adresse eingetippt wird. Siehe [Requests und Prefill](#requests).

> **Machen Sie die E-Mail-Frage zum Pflichtfeld**
>
> Eine Einreichung ohne E-Mail-Antwort hat keinen Kontakt, den sie aktualisieren könnte; ihre Zustellung schlägt fehl und wird nicht wiederholt. Markieren Sie die Frage, die Sie E-Mail zugeordnet haben, als erforderlich.

## Rechtsgrundlage für neue Kontakte

HubSpot-Konten mit aktivierten Datenschutzeinstellungen, was für Konten in der EU der Standard ist, lehnen es ab, einen Kontakt ohne Rechtsgrundlage für die Verarbeitung seiner Daten anzulegen. Hat Ihr Konto diese Einstellung, zeigt der Schritt Konfigurieren **Rechtsgrundlage für neue Kontakte** mit den Optionen Ihres eigenen Kontos an, und Sie müssen eine auswählen, bevor Sie fortfahren können.

Formstep schreibt die Rechtsgrundlage nur, wenn es einen Kontakt anlegt. Ein vorhandener Kontakt behält die Rechtsgrundlage, die er bereits hat, denn dieser Wert hält die Einwilligung fest, die Ihr Team eingeholt hat. Die Rechtsgrundlage wird nie als Zuordnungsziel angeboten.

## Eigenschaftstypen

| Formularfeld | Kompatible HubSpot-Eigenschaften |
| - | - |
| Beliebiges Feld | Single-line text, Multi-line text |
| Zahl, Bewertung, Skala | Number, zusätzlich Text |
| Datum | Date picker, Date and time picker, zusätzlich Text |
| Telefon | Phone number, zusätzlich Text |
| Radio, Dropdown, Kontrollkästchen, Bildauswahl | Dropdown select, Radio select, Multiple checkboxes, zusätzlich Text |
| Schalter | Single checkbox, zusätzlich Text |
| Wiederholungsgruppe (gesamte Gruppe) | Nur Text |

- Eine Auswahlantwort geht an die HubSpot-Option, deren interner Wert oder Bezeichnung dem Schlüssel oder der Bezeichnung der Formstep-Option entspricht, ohne Beachtung der Groß- und Kleinschreibung. Eine Antwort ohne passende Option wird ausgelassen, statt den gesamten Schreibvorgang scheitern zu lassen.

- Mehrere ausgewählte Optionen gehen gemeinsam an eine Multiple-checkboxes-Eigenschaft.

- Auch Metadaten können zugeordnet werden, zum Beispiel **Submitted at** zu einer Datumseigenschaft oder **PDF Link** zu einer Texteigenschaft.

Schreibgeschützte, berechnete, ausgeblendete und archivierte Eigenschaften können nicht geschrieben werden und werden daher nicht angeboten. Die Eigenschaftsliste wird jedes Mal aktualisiert, wenn Sie die Integration öffnen; lädt sie nicht, drücken Sie **Erneut versuchen**.

## Testereignis

Der Schritt Fertigstellen und das Integrations-Detailpanel haben beide eine Schaltfläche **Test senden**. Sie schreibt in den Kontakt `formstep-test@example.com`, legt ihn an, falls er nicht existiert, und ändert nie einen anderen Kontakt. Texteigenschaften erhalten `[Question Title]`-Zeichenfolgen, Zahlen erhalten `0`, Datumsangaben erhalten das heutige Datum, Single-checkbox-Eigenschaften erhalten _Nein_, und Dropdowns verwenden die erste HubSpot-Option der Eigenschaft. Löschen Sie den Testkontakt in HubSpot, wenn Sie fertig sind.

## Requests und Prefill

Ist am Formular eine HubSpot-Integration eingerichtet, zeigt das Sheet Neue Anfrage unter der empfangenden Person das Feld **In HubSpot suchen**. Suchen Sie nach Name, E-Mail-Adresse, Telefonnummer oder Unternehmen und wählen Sie einen Kontakt aus: Seine E-Mail-Adresse und sein Name werden zur empfangenden Person, und jedes Formularfeld, dessen Zeile vorausfüllt (← oder ↔), übernimmt den Wert des Kontakts. Mit Pro und Business können Sie mehrere Kontakte ankreuzen und auf einmal hinzufügen, jeweils mit einer eigenen Anfrage: siehe [Sammelversand](https://docs.formstep.io/de/requests/bulk-send/). Vor dem Senden können Sie noch alles ändern. Schließt die empfangende Person den [Request](https://docs.formstep.io/de/requests/overview/) ab, aktualisieren die Antworten genau diesen Kontakt anhand seiner ID, auch wenn eine andere E-Mail-Adresse eingetippt wurde, und die E-Mail-Adresse des Kontakts wird nie geändert.

- Die Werte werden einmal gelesen, wenn Sie den Kontakt auswählen. Eine spätere Änderung in HubSpot erreicht den Request nicht.

- Ein Feld, das nicht vorausgefüllt werden kann, behält einen einfachen →-Pfeil: eine Datei, eine Signatur, eine Zahlung, eine Liste von Optionen, eine Matrix, eine Wiederholungsgruppe, Metadaten oder ein berechnetes Feld. Ein verstecktes Feld übernimmt seinen Wert als Kontext.

- Ein Auswahlfeld übernimmt die Option, deren Schlüssel oder Bezeichnung der HubSpot-Option entspricht, ohne Beachtung der Groß- und Kleinschreibung. Ein Wert, der zu keiner Option passt, wird ausgelassen.

- **Selbst ausprobieren** füllt dieselben Werte aus, aktualisiert HubSpot aber nie: Ein Test-Request erreicht keine Integrationen.

- Wird der Kontakt gelöscht, bevor die empfangende Person einreicht, gehen die Antworten stattdessen an den Kontakt mit der eingereichten E-Mail-Adresse.

> **Nur im Dashboard**
>
> Die API und MCP lesen HubSpot nicht. Eine Automatisierung, die Requests erstellt, schlägt den Kontakt selbst nach (n8n und Zapier haben dafür jeweils einen HubSpot-Schritt) und übergibt die Werte in `prefill`. Füllen Sie das Feld, das E-Mail zugeordnet ist, mit der E-Mail-Adresse des Kontakts vor und sperren Sie es, dann aktualisieren die Antworten diesen Kontakt anhand der E-Mail-Adresse. Siehe [Prefill](https://docs.formstep.io/de/requests/creating-requests/#prefill).

## Was nicht unterstützt wird

- Abgebrochene Einreichungen werden nicht an HubSpot gesendet. Nur abgeschlossene Einreichungen und Bearbeitungen aktualisieren Kontakte.

- Vorhandene Einreichungen werden bei der Verbindung nicht exportiert. Kontakte werden ab der nächsten Einreichung aktualisiert.

- Es werden nur Kontakte geschrieben, keine Unternehmen, Deals oder Tickets.

## Eigenschaftsänderungen in HubSpot

Formstep liest bei jeder Zustellung die aktuellen Definitionen der zugeordneten Eigenschaften. Löschen Sie eine zugeordnete Eigenschaft in HubSpot, wird sie beim Schreiben ausgelassen, und der Rest des Kontakts wird weiterhin aktualisiert. Ändern sich Typ oder Optionen einer Eigenschaft, werden Antworten in die neue Definition umgewandelt; passt der neue Typ nicht mehr zum Formularfeld, zeigt die Zuordnung eine Warnung, damit Sie dieses Feld neu zuordnen können.

## Fehlerbehebung

- **Autorisierung abgelaufen** — HubSpot-Zugriffstoken sind 30 Minuten gültig und werden automatisch erneuert. Schlägt die Erneuerung fehl, zum Beispiel weil die App in HubSpot deinstalliert wurde, wird die Verbindung als abgelaufen markiert, und ihre Integrationen stoppen. Drücken Sie Erneut verbinden.

- **Ein Wert wird abgelehnt** — HubSpot kann einen Wert ablehnen, zum Beispiel einen, der gegen eine für die Eigenschaft festgelegte Validierungsregel verstößt. Der fehlgeschlagene Eintrag im Ereignisprotokoll zeigt die eigene Meldung von HubSpot. Beheben Sie das Formularfeld oder die Eigenschaft und lesen Sie dann [fehlgeschlagene Zustellungen](https://docs.formstep.io/de/integrations/health-monitoring/#failed-deliveries), um den Eintrag erneut zu senden.

- **Kontakteigenschaften konnten nicht geladen werden** — Drücken Sie **Erneut versuchen**. Schlägt es weiter fehl, verbinden Sie das Konto erneut.

## FAQ

**Welchen Zugriff benötigt Formstep?**

Kontakte lesen und schreiben sowie die Definitionen der Kontakteigenschaften lesen. Formstep verwendet OAuth, es sind also keine API-Schlüssel zu verwalten, und fragt nicht nach Zugriff auf Unternehmen, Deals oder andere Objekte.

**Können andere Workspace-Mitglieder meine HubSpot-Verbindung sehen?**

Ja. HubSpot-Verbindungen sind workspace-weit gültig. Jedes Mitglied kann bei der Einrichtung einer Integration ein beliebiges verbundenes Konto verwenden.

**Kann ich mehrere HubSpot-Konten verbinden?**

Ja. Verbinden Sie bei der Einrichtung einer neuen Integration ein weiteres Konto. Jedes Formular wählt, welches Konto verwendet werden soll.

**Erzeugt eine Bearbeitung einen zweiten Kontakt?**

Nein. Die Bearbeitung aktualisiert den Kontakt mit der E-Mail-Adresse aus der Einreichung. Ändert die befragte Person die E-Mail-Antwort selbst, ist die neue E-Mail-Adresse ein anderer Kontakt, sodass stattdessen dieser Kontakt aktualisiert oder angelegt wird.

**Wie entferne ich die Integration?**

Gehen Sie zu Formulareinstellungen → Integrationen → HubSpot und löschen Sie die Integration. Um auch den Zugriff von Formstep zu widerrufen, deinstallieren Sie die Formstep-App in HubSpot unter Settings → Integrations → Connected apps.

## Nächste Schritte

[Einen Request erstellen](https://docs.formstep.io/de/requests/creating-requests/) — Felder für eine empfangende Person vorausfüllen und sperren

[Gesundheit und Überwachung](https://docs.formstep.io/de/integrations/health-monitoring/) — Ereignisprotokolle, Wiederholungsversuche und Fehler-E-Mails

[Airtable](https://docs.formstep.io/de/integrations/airtable/) — Datensätze in einer Airtable-Base erstellen