The HubSpot integration sends form submission data to HubSpot CRM through our API (api.avakode.com), automatically creating a new contact (and optionally a deal) every time someone submits your form. This eliminates manual data entry and ensures every lead is captured in your sales pipeline immediately, with no delay and no chance of a lead slipping through the cracks.
For teams that use HubSpot as their source of truth for customer relationships, this integration means your website forms feed directly into the same system your sales and marketing teams use every day.
What You Need Before Starting
- A HubSpot account (the free CRM works, or any paid plan)
- A HubSpot Private App Token (for API access)
Setup Walkthrough
Step 1 — Create a Private App in HubSpot- Log in to HubSpot and go to Settings (gear icon in the top navigation).
- In the left sidebar, go to Integrations > Private Apps.
- Click Create a Private App.
- Give it a name like “Fillin Forge Integration.”
- Under the Scopes tab, grant these permissions:
crm.objects.contacts.write — to create and update contacts
– crm.objects.contacts.read — to check for existing contacts (prevents duplicates)
– crm.objects.deals.write — to create deals (optional, only if you want deal creation)
– crm.objects.deals.read — to read deal properties (optional)
- Click Create App and copy the generated Access Token.
- In WordPress, go to Fillin Forge > Settings (the HubSpot CRM card).
- Paste your Access Token into the Private App Access Token field and click Connect.
- Fillin Forge verifies the connection and shows “Connected to HubSpot”. If the site license connection is incomplete, the card shows the specific Avakode/site-token warning.
- Open your form in the builder.
- Find the HubSpot CRM card in the builder.
- Toggle on Send lead to HubSpot on submission.
- That is all for a contact: Fillin Forge finds the form’s first Email field and sends it to HubSpot as the contact’s email address (HubSpot uses email as the unique identifier). The builder has no screen for mapping other fields to HubSpot properties, so the other form fields are not sent.
Creating Deals (Optional)
If each form submission should also create a deal in your sales pipeline:
- In the same card, toggle on Also create a Deal.
- Enter the Pipeline ID of the deal pipeline.
- Enter the Stage ID of the deal stage new deals should start in. A deal is created only when both the Pipeline ID and the Stage ID are filled in.
- The deal name is the form title followed by a dash and the submission number (for example, Contact Us – #42).
- Save the form.
How It Works
- When someone submits the form, Fillin Forge creates a contact in HubSpot with the email address from the form.
- If a contact with that email already exists, Fillin Forge finds it by the email address and no duplicate is created. Only the email address is sent, so no other property of that contact is changed.
- If deal creation is enabled, a new deal is created and associated with the contact.
- The form submission is also saved in Fillin Forge as usual.
- Deal creation is optional. With Also create a Deal off, Fillin Forge still creates or updates the HubSpot contact.
- If HubSpot rejects the request, the visitor still gets the normal success state and Fillin Forge records a diagnostic entry for support.
Troubleshooting HubSpot
| Problem | Most likely cause | Solution |
|---|---|---|
| Contacts not appearing | Private App Token lacks the correct scopes | Regenerate with contacts.write and contacts.read scopes |
| “Unauthorized” error | Token was revoked or expired | Create a new Private App in HubSpot and reconnect |
| Name, phone or company missing on the contact | Fillin Forge sends only the email address; the builder has no screen for mapping other fields | Read the other answers in the Fillin Forge submission, or send them to another tool with the Webhook card |
| Deals not being created | Deal scopes not granted, or the Pipeline ID or Stage ID is empty | Add deal scopes to the Private App and fill in both IDs in the HubSpot CRM card |
| Duplicate contacts | This should not happen (HubSpot deduplicates by email) | If it does, compare the email addresses of the duplicate contacts in HubSpot |
| Submission is saved but the diagnostic log says “Invalid request” | The Worker rejected the HubSpot payload before calling HubSpot | Update to the current Forge API build; empty property maps are normalized and scalar property values are sent as strings |
> Tip: Test the integration by submitting the form with your own email address and check that the contact appears in HubSpot. If you create deals, check the deal too. This makes troubleshooting easier.
> Good to know: Without PRO, the HubSpot integration is not available. You can export submissions to CSV and import them into HubSpot manually, or use the Webhook integration to connect through a middleware tool like Zapier or Make.
Common Mistakes to Avoid
- Creating the Private App without the right scopes and wondering why contacts do not appear. Always include both read and write scopes for contacts.
- Expecting the name, phone or company in HubSpot. Fillin Forge sends only the email address, so the other answers stay in the Fillin Forge submission.
- Forgetting to fill in the Pipeline ID and the Stage ID when deal creation is on. Without both, no deal is created.
[Screenshot: The HubSpot CRM card of the form builder showing the lead toggle, the Also create a Deal toggle and the Pipeline ID and Stage ID fields]
—