This recipe shows you how to connect your forms to HubSpot for contact and deal management and to Mailchimp for email list subscription. Both integrations can run simultaneously on the same form.
Part 1: HubSpot Setup
#### Creating the HubSpot Connection
- Log in to your HubSpot account at app.hubspot.com
- Go to Settings > Integrations > Private Apps
- Click Create a Private App
- Name it “Form Forge” and add a description
- Under Scopes, grant these permissions:
| Scope | Purpose |
|---|---|
crm.objects.contacts.write | Create and update contacts |
crm.objects.contacts.read | Check for existing contacts |
crm.objects.deals.write | Create deals (optional) |
crm.objects.deals.read | Read deal pipelines (optional) |
- Click Create App and copy the Access Token
- In WordPress, go to Form Forge > Settings > HubSpot
- Paste the token into the API-key field and click Connect. Connect is a dedicated action — it validates and stores the token through the Forge API in its own request, and does not submit the whole Settings page. The result appears inline in the HubSpot card: a green “Connected to HubSpot” on success, or the specific error on failure (right there in the card, not as a generic notice at the top of the page). If the card reports a missing site capability token, your license isn’t fully connected yet — connect/activate the license first, then click Connect.
#### Enabling HubSpot on a Form
- Open your form in the builder
- Go to the Integrations tab
- Toggle on HubSpot
- Map form fields to HubSpot contact properties:
| Form Field | HubSpot Property |
|---|---|
| Name (first) | First Name |
| Name (last) | Last Name |
| Email (required) | |
| Phone | Phone Number |
| Company | Company Name |
| Position | Job Title |
- Optionally enable Create Deal:
– Select a Deal Stage (e.g., “New Lead”)
– Set a deal name pattern (e.g., “Lead: {name}”)
- Save the form
#### How HubSpot Handles Duplicates
When a form is submitted, HubSpot checks if a contact with that email already exists:
- New contactCreates a new contact record with all mapped fields
- Existing contactUpdates the existing contact’s properties with the new submission data (no duplicate is created)
- DealA new deal is created every time (even for existing contacts), so each submission generates a separate deal
#### HubSpot Submit Saves Locally but Logs “Invalid request”
If the visitor sees the normal success message but formforge_integration_log shows HubSpot status=error, message=Invalid request, and HTTP 400, the request was rejected by the Forge API before HubSpot received it. Current builds normalize empty property maps from PHP ([] -> {}), coerce scalar contact/deal property values to strings, and do not require pipeline or stage fields when Create Deal is off.
Part 2: Mailchimp Setup
#### Creating the Mailchimp Connection
- Log in to Mailchimp at login.mailchimp.com
- Go to Account > Extras > API Keys
- Click Create a Key and copy the key
- In WordPress, go to Form Forge > Settings > Mailchimp
- Click Connect, paste the API key, and save
- Form Forge verifies the connection and stores the key securely on the Forge API server
#### Enabling Mailchimp on a Form
- Open your form in the builder
- Go to the Integrations tab
- Toggle on Mailchimp
- Select the Audience (email list) from the dropdown
- Map form fields to Mailchimp merge fields:
| Form Field | Mailchimp Merge Field |
|---|---|
| Email Address (required) | |
| Name (first) | FNAME |
| Name (last) | LNAME |
| Phone | PHONE |
- Save the form
#### What Happens with Existing Contacts
Mailchimp handles existing subscribers gracefully:
| Scenario | What Happens |
|---|---|
| New email address | Contact is added to the audience as a new subscriber |
| Email already subscribed | Contact properties are updated with the new data; no duplicate |
| Email previously unsubscribed | The contact is NOT re-subscribed (Mailchimp respects unsubscribe) |
| Email in a different audience | A new subscriber is added to the selected audience |
Part 3: Field Mapping Strategies
#### Keep Mappings Minimal at First
Start with only the essential fields (email, first name, last name) to verify the integration works. Once confirmed, add more mappings for phone, company, job title, and custom fields.
#### Use Consistent Field Names
If you have multiple forms feeding into the same HubSpot or Mailchimp account, use consistent field labels across forms. This ensures that “Email Address” on Form A maps to the same property as “Email Address” on Form B.
#### Custom Properties and Merge Fields
If your form collects data that does not match a standard HubSpot property or Mailchimp merge field:
- HubSpot: Create a custom contact property in HubSpot first (Settings > Properties), then map your form field to it
- Mailchimp: Create a custom merge field in your audience settings (Audience > Settings > Audience fields), then map your form field to it
#### Testing the Combined Setup
- Submit the form with a test email address
- Check HubSpot: verify the contact was created with correct field values, and the deal if enabled
- Check Mailchimp: verify the subscriber was added to the correct audience with correct merge field values
- Submit again with the same email: verify HubSpot updates the existing contact (no duplicate) and Mailchimp updates the subscriber
—