# HubSpot

Werk het HubSpot-contact achter elke inzending bij of maak het aan, gevonden via e-mailadres.

## Wat je krijgt

- Eén HubSpot-contact per e-mailadres: een bestaand contact wordt bijgewerkt, een nieuw e-mailadres maakt een contact aan

- Veldkoppeling aan contacteigenschappen, met typecompatibiliteitscontroles

- Een wijziging door de respondent werkt hetzelfde contact opnieuw bij

- Lege antwoorden wissen nooit een eigenschap, en eigenschappen die je niet koppelt blijven zoals ze zijn

- Een rechtsgrond voor nieuwe contacten, voor accounts die er een vereisen

- Een testverzending die alleen een speciaal testcontact aanraakt

- Een contact zoeken in het venster Nieuwe aanvraag, de aanvraag ermee vooraf invullen en de antwoorden terugschrijven naar dat contact

## HubSpot verbinden

1. **Open Formulierinstellingen → Integraties**

   Kies HubSpot in de groep CRM.

2. **Verbind een HubSpot-account**

   Kies een bestaand verbonden HubSpot-account of verbind een nieuw account. Je wordt doorgestuurd naar HubSpot om het account te kiezen en toegang goed te keuren. Formstep laadt daarna de contacteigenschappen van het account en toont hoeveel er klaar zijn om toe te wijzen.

3. **Koppel formuliervelden → contacteigenschappen**

   Koppel elk formulierveld aan een contacteigenschap. Alleen compatibele eigenschappen worden getoond. Eén formulierveld moet worden gekoppeld aan E-mailadres, want daarmee wordt het contact gevonden. De pijl op elke rij bepaalt welke kant de waarden op gaan: → antwoorden werken HubSpot bij, ← een contact dat je kiest vult het veld vooraf in, ↔ allebei. Vraagt het account om een rechtsgrond, kies er dan hier ook een.

4. **Afronden**

   Gebruik "Test versturen" om voorbeeldwaarden naar het testcontact formstep-test\@example.com te schrijven. Nieuwe inzendingen werken contacten bij zodra je opslaat.

## Hoe een inzending haar contact vindt

Het antwoord op het formulierveld dat je hebt gekoppeld aan **E-mailadres** bepaalt bij welk contact een inzending hoort. Bij elke voltooide inzending doet Formstep het volgende:

1. Het werkt het HubSpot-contact met dat e-mailadres bij en schrijft alleen de eigenschappen die je hebt gekoppeld.

2. Het maakt het contact aan als geen enkel contact dat e-mailadres heeft. Een nieuw contact krijgt de gekoppelde antwoorden, het e-mailadres en de rechtsgrond.

Wanneer een respondent zijn inzending wijzigt, wordt hetzelfde contact opnieuw bijgewerkt met de nieuwe antwoorden. Een leeg gelaten antwoord wordt overgeslagen, dus het wist nooit een waarde die al in HubSpot staat, en eigenschappen die je niet hebt gekoppeld worden nooit aangeraakt.

Een aanvraag die je in het venster Nieuwe aanvraag vooraf hebt ingevuld vanuit een contact vormt de uitzondering: de antwoorden werken dat contact bij, welk e-mailadres er ook is getypt. Zie [Aanvragen en vooraf invullen](#requests).

> **Maak de e-mailvraag verplicht**
>
> Een inzending zonder e-mailantwoord heeft geen contact om bij te werken, dus de levering mislukt en wordt niet opnieuw geprobeerd. Markeer de vraag die je aan E-mailadres hebt gekoppeld als verplicht.

## Rechtsgrond voor nieuwe contacten

HubSpot-accounts waarvoor privacyinstellingen voor gegevens zijn ingeschakeld, wat de standaard is voor accounts in de EU, weigeren een contact aan te maken zonder rechtsgrond voor de verwerking van de gegevens. Heeft je account die instelling, dan toont de stap Configureren **Rechtsgrond voor nieuwe contacten** met de eigen opties van je account, en moet je er een kiezen voordat je verder kunt.

Formstep schrijft de rechtsgrond alleen wanneer het een contact aanmaakt. Een bestaand contact behoudt de rechtsgrond die het al heeft, omdat die waarde de toestemming vastlegt die je team heeft verzameld. De rechtsgrond wordt nooit aangeboden als koppelingsbestemming.

## Eigenschaptypen

| Formulierveld | Compatibele HubSpot-eigenschappen |
| - | - |
| Elk veld | Single-line text, Multi-line text |
| Getal, Beoordeling, Schaal | Number, plus tekst |
| Datum | Date picker, Date and time picker, plus tekst |
| Telefoon | Phone number, plus tekst |
| Radio, Dropdown, Selectievakjes, Afbeeldingskeuze | Dropdown select, Radio select, Multiple checkboxes, plus tekst |
| Schakelaar | Single checkbox, plus tekst |
| Herhalende groep (hele groep) | Alleen tekst |

- Een keuzeantwoord gaat naar de HubSpot-optie waarvan de interne waarde of het label overeenkomt met de sleutel of het label van de Formstep-optie, zonder hoofdlettergevoeligheid. Een antwoord zonder overeenkomende optie wordt weggelaten in plaats van dat de hele schrijfactie mislukt.

- Meerdere geselecteerde opties gaan samen naar een Multiple checkboxes-eigenschap.

- Metagegevens kunnen ook worden gekoppeld, bijvoorbeeld **Submitted at** aan een datumeigenschap of **PDF Link** aan een tekst-eigenschap.

Alleen-lezen, berekende, verborgen en gearchiveerde eigenschappen kunnen niet worden beschreven, dus ze worden niet aangeboden. De lijst met eigenschappen wordt vernieuwd telkens wanneer je de integratie opent; als het laden mislukt, klik je op **Opnieuw proberen**.

## Testgebeurtenis

De stap Afronden en het integratie-detailpaneel hebben beide een knop **Test versturen**. Die schrijft naar het contact `formstep-test@example.com` en maakt het aan als het niet bestaat, en wijzigt nooit een ander contact. Tekst-eigenschappen krijgen `[Question title]`-strings, getallen krijgen `0`, datums krijgen de datum van vandaag, Single checkbox-eigenschappen krijgen _Nee_ en dropdowns gebruiken de eerste HubSpot-optie van de eigenschap. Verwijder het testcontact in HubSpot als je klaar bent.

## Aanvragen en vooraf invullen

Met een HubSpot-integratie op het formulier toont het venster Nieuwe aanvraag **Zoeken in HubSpot** onder de ontvanger. Zoek op naam, e-mailadres, telefoonnummer of bedrijf en kies een contact: het e-mailadres en de naam worden de ontvanger, en elk formulierveld waarvan de rij vooraf invult (← of ↔) neemt de waarde van het contact over. Op Pro en Business kun je meerdere contacten aanvinken en in één keer toevoegen, elk met een eigen aanvraag: zie [Bulkverzending](https://docs.formstep.io/nl/requests/bulk-send/). Je kunt alles nog wijzigen voordat je verstuurt. Wanneer de ontvanger de [aanvraag](https://docs.formstep.io/nl/requests/overview/) voltooit, werken de antwoorden datzelfde contact bij via zijn id, ook als de ontvanger een ander e-mailadres typte, en het e-mailadres van het contact wordt nooit gewijzigd.

- Waarden worden één keer gelezen, op het moment dat je het contact kiest. Een wijziging in HubSpot daarna bereikt de aanvraag niet.

- Een veld dat niet vooraf kan worden ingevuld houdt een gewone →-pijl: een bestand, een handtekening, een betaling, een lijst met opties, een matrix, een herhalende groep, metagegevens of een berekend veld. Een verborgen veld neemt zijn waarde aan als context.

- Een keuzeveld neemt de optie waarvan de sleutel of het label overeenkomt met de HubSpot-optie, zonder hoofdlettergevoeligheid. Een waarde die bij geen enkele optie past, wordt weggelaten.

- **Probeer het zelf** vult dezelfde waarden in maar werkt HubSpot nooit bij: een testaanvraag bereikt geen integraties.

- Wordt het contact verwijderd voordat de ontvanger indient, dan gaan de antwoorden naar het contact met het ingediende e-mailadres.

> **Alleen in het dashboard**
>
> De API en MCP lezen HubSpot niet. Een automatisering die aanvragen aanmaakt zoekt het contact zelf op (n8n en Zapier hebben er allebei een HubSpot-stap voor) en geeft de waarden door in `prefill`. Vul het veld dat aan E-mailadres is gekoppeld vooraf in met het e-mailadres van het contact en vergrendel het, en de antwoorden werken dat contact bij via het e-mailadres. Zie [Vooraf invullen](https://docs.formstep.io/nl/requests/creating-requests/#prefill).

## Wat het niet doet

- Verlaten inzendingen worden niet naar HubSpot gestuurd. Alleen voltooide inzendingen en wijzigingen werken contacten bij.
- Bestaande inzendingen worden niet geëxporteerd wanneer je verbindt. Contacten worden bijgewerkt vanaf de volgende inzending.
- Het schrijft alleen contacten, geen bedrijven, deals of tickets.

## Eigenschapwijzigingen in HubSpot

Formstep leest bij elke levering de actuele definities van de gekoppelde eigenschappen. Als je een gekoppelde eigenschap in HubSpot verwijdert, wordt die weggelaten uit de schrijfactie en wordt de rest van het contact nog steeds bijgewerkt. Als het type of de opties van een eigenschap veranderen, worden antwoorden omgezet naar de nieuwe definitie; als het nieuwe type niet meer past bij het formulierveld, toont de koppeling een waarschuwing zodat je dat veld opnieuw kunt koppelen.

## Problemen oplossen

- **Autorisatie verlopen** — HubSpot-toegangstokens zijn 30 minuten geldig en worden automatisch vernieuwd. Als het vernieuwen mislukt, bijvoorbeeld omdat de app in HubSpot is verwijderd, wordt de verbinding als verlopen gemarkeerd en stoppen de bijbehorende integraties. Klik op **Verbind opnieuw**.

- **Een waarde wordt geweigerd** — HubSpot kan een waarde weigeren, bijvoorbeeld een waarde die een validatieregel van de eigenschap schendt. De mislukte vermelding onder **Recente gebeurtenissen** toont de eigen melding van HubSpot. Los het formulierveld of de eigenschap op en zie daarna [mislukte leveringen](https://docs.formstep.io/nl/integrations/health-monitoring/#failed-deliveries) om de levering opnieuw te versturen.

- **Contacteigenschappen konden niet worden geladen** — klik op **Opnieuw proberen**. Blijft het mislukken, verbind dan het account opnieuw.

## Veelgestelde vragen

**Welke toegang heeft Formstep nodig?**

Contacten lezen en schrijven, en de definities van contacteigenschappen lezen. Formstep gebruikt OAuth, dus er zijn geen API-sleutels te beheren, en het vraagt geen toegang tot bedrijven, deals of andere objecten.

**Kunnen andere werkruimteleden mijn HubSpot-verbinding zien?**

Ja. HubSpot-verbindingen zijn gekoppeld aan de werkruimte. Elk lid kan elk verbonden account gebruiken bij het instellen van een integratie.

**Kan ik meerdere HubSpot-accounts verbinden?**

Ja. Verbind een extra account tijdens het instellen van een nieuwe integratie. Elk formulier kiest welk account wordt gebruikt.

**Maakt een wijziging een tweede contact aan?**

Nee. De wijziging werkt het contact bij met het e-mailadres in de inzending. Als de respondent het e-mailantwoord zelf wijzigt, is het nieuwe e-mailadres een ander contact, dus dat contact wordt bijgewerkt of aangemaakt.

**Hoe verwijder ik de integratie?**

Ga naar Formulierinstellingen → Integraties → HubSpot en verwijder de integratie. Om ook de toegang van Formstep in te trekken, verwijder je de Formstep-app in HubSpot onder Settings → Integrations → Connected apps.

## Volgende stappen

[Een aanvraag maken](https://docs.formstep.io/nl/requests/creating-requests/) — Velden vooraf invullen en vergrendelen voor één ontvanger

[Gezondheid en monitoring](https://docs.formstep.io/nl/integrations/health-monitoring/) — Gebeurtenislogboeken, nieuwe pogingen en foutmails

[Airtable](https://docs.formstep.io/nl/integrations/airtable/) — Maak records aan in een Airtable-base