Recipe: Connecting Forms to CRM (HubSpot + Mailchimp)

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

1. Log in to your HubSpot account at app.hubspot.com
2. Go to Settings > Integrations > Private Apps
3. Click Create a Private App
4. Name it “Fillin Forge” and add a description
5. Under Scopes, grant these permissions:

1. Click Create App and copy the Access Token
2. In WordPress, go to Fillin Forge > Settings (the HubSpot CRM card)
3. Paste the token into the Private App Access Token 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

1. Open your form in the builder
2. Find the HubSpot CRM card in the builder
3. Toggle on Send lead to HubSpot on submission. Fillin Forge sends the form’s first Email field to HubSpot as the contact’s email address. The builder has no screen for mapping other fields to HubSpot properties, so the other form fields are not sent
4. Optionally toggle on Also create a Deal, then enter the Pipeline ID and the Stage ID of the stage new deals should start in. A deal is created only when both are filled in. The deal name is the form title followed by a dash and the submission number (for example, Contact Us – #42), and there is no setting for it
5. 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 the email address
• Existing contactFillin Forge finds it by the email address and no duplicate is created. Only the email address is sent, so no other property of the contact is changed
• 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 Also create a Deal is off.

Part 2: Mailchimp Setup

#### Creating the Mailchimp Connection

1. Log in to Mailchimp at login.mailchimp.com
2. Go to Account > Extras > API Keys
3. Click Create a Key and copy the key
4. In WordPress, go to Fillin Forge > Settings (the Mailchimp card)
5. Paste the API key into the API Key field and click Connect. You do not need to click Save Settings for it
6. Fillin Forge checks the key and stores it on the Forge API server. The card then shows “Connected to Mailchimp” with your account name and a Disconnect button

#### Enabling Mailchimp on a Form

1. Open your form in the builder
2. Find the Mailchimp card in the builder
3. Toggle on Subscribe to Mailchimp list on submission
4. Enter the List ID of the audience (email list). In Mailchimp you find it under Audience, Settings, Audience ID
5. Under Email Field, pick the form field with the subscriber’s email address, or keep Auto-detect email field
6. Other fields cannot be mapped to Mailchimp merge fields in the builder: the email address is what gets sent
7. Save the form

#### What Happens with Existing Contacts

For every submission Fillin Forge sends one request for the contact with that email address. It asks for the status “subscribed” only if the address is new; for an address that is already on the list no status is sent, so Mailchimp keeps the status the contact has. It never reads the current status of the contact. What happens next:

Part 3: Which Fields Are Sent

#### One Email Address for Both

HubSpot and Mailchimp both work from an email address. HubSpot gets the first Email field of the form that has a value. Mailchimp gets the field you chose under Email Field, or, when none is chosen, the first Email field that has a value. If the submission has no valid email address, nothing is sent to either service.

#### Other Fields Are Not Sent

The builder has no screen for mapping form fields to HubSpot properties or Mailchimp merge fields, so the other answers stay in the Fillin Forge submission. If another system needs them, the Webhook card sends the submitted fields as JSON to a URL, for example a Zapier webhook.

#### Testing the Combined Setup

1. Submit the form with a test email address
2. Check HubSpot: verify the contact was created with the email address, and the deal if enabled
3. Check Mailchimp: verify the subscriber was added to the correct audience
4. Submit again with the same email: verify that HubSpot still has one contact for it and that Mailchimp still has one subscriber for it (no duplicates)

—