34. HubSpot Integration

Creates or updates contacts and optionally creates deals. PRO feature.

Forge API HubSpot and Mailchimp endpoints also require the site capability envelope (license_key, product, forge_site_url, site_token). The token is stored locally by the Avakode Connect flow and is not a public integration secret. Restored sites may have a Freemius license before the local Form Forge license cache is rebuilt; the shared Forge Connect helper can fall back to the Freemius license key and stamps fresh site tokens with site_token_refreshed_at so they are not treated as stale immediately after reconnect. HubSpot connect requests force-refresh the token before sending the Private App token, so a stale local token fails early as a site-binding problem instead of a misleading HubSpot authentication error.

Form Settings

{
  "settings": {
    "hubspot_enabled": true,
    "hubspot_create_deal": true,
    "hubspot_pipeline": "default",
    "hubspot_stage": "appointmentscheduled",
    "hubspot_field_mapping": {
      "field_1": "firstname",
      "field_3": "company"
    }
  }
}

Submission Flow

1. Finds email from first email type field
2. Maps form fields to HubSpot contact properties
3. Forge API performs contact upsert and optional deal creation
4. Empty PHP property arrays are accepted as {} by the Worker, scalar property values are coerced to strings, and deal fields are only required when create_deal=true
5. Errors and skipped states are written to formforge_integration_log without blocking the saved submission

FORMFORGE_Forge_API::instance()->hubspot_submit(
    '[email protected]',
    [ 'firstname' => 'John', 'company' => 'Acme' ],
    true,                      // create_deal
    'Contact Form -- #42',     // deal_name
    'default',                 // pipeline
    'appointmentscheduled'     // stage
);

—