Connect CF7 to HubSpot – Contact Form 7 CRM Integration

HubSpot no longer lets you create new private apps (since 28 September 2026 for new accounts, and 26 October 2026 for existing ones). Use a service key instead; a token from an existing private app keeps working.

• Log in to HubSpot as a super admin and create a service key: https://developers.hubspot.com/docs/apps/developer-platform/build-apps/authentication/account-service-keys
• Give it these scopes: crm.objects.contacts.read and .write, crm.objects.companies.read and .write, crm.objects.deals.read and .write, crm.objects.tickets.read and .write, crm.schemas.contacts.read, crm.schemas.companies.read, crm.schemas.deals.read, forms, files.write and communication_preferences.read. (A private app token with the older tickets and files scopes keeps working.)
• If you use journey (custom behavioral) events (cf7_form_submitted, cf7_form_synced, cf7_form_sync_failed), also add analytics.behavioral_events.send and behavioral_events.event_definitions.read_write, create matching custom event definitions in HubSpot, and enable Journey events in the plugin settings.
• Paste the key into CF7 to HubSpot → Settings → Access token and click Connect. The token is saved only after HubSpot accepts it.

Contacts, companies, deals, tickets and HubSpot forms use HubSpot’s standard CRM and Forms APIs. Journey events use HubSpot custom events, which are not part of every HubSpot plan; leave them off if your plan does not have them.

Yes. On the form’s mapping screen click “Add an object” and pick a Company, Deal or Ticket (or another Contact). Each object has its own field mapping and can be associated with an object above it.

A Contact object has a switch: update the contact with the same email, or always create a new one.

Yes. Add a Deal object to the form’s mapping and choose its pipeline and deal stage.

Yes. Any Contact Form 7 field, hidden fields included, can be mapped to a HubSpot property. UTM parameters and ad click ids are added only to the properties you map them to; turn on “Attribution cookies” to keep them from the landing page until the form is sent.

Send to a HubSpot form when you want HubSpot’s form features: form-based workflows, form submission reports and the visitor’s page history on the contact. Send to objects when you need companies, deals or tickets, or several linked records from one submission.

Open CF7 to HubSpot → Logs. Click an entry to see what HubSpot answered and which properties it rejected. Personal data is masked; use “Copy details” to share the entry with support.

HubSpot’s own tracking code can also collect Contact Form 7 submissions. In HubSpot, turn off “Collect data from website forms” under the non-HubSpot forms settings.

Only if background processing is off. Turn it on in Settings and the form answers at once while the HubSpot requests run in the background.

Post in the support forum of this plugin, or write to hello@procoders.tech.

Since 1.4.1 the plugin has developer hooks. They are for people who write PHP; there is no setting for them in the admin.

• cf7hs_object_payload (filter, $data, $module, $form_id, $context): change the HubSpot properties of one object just before it is written. $module is contacts, company, deals or tickets, or the HubSpot form GUID when the form is sent to a HubSpot form. Register with 4 accepted arguments to receive $context (index, action, post_id, request, async, attempt).
• cf7hs_object_synced (action, $record_id, $module, $form_id, $outcome, $context): an object was created or updated. Register with 5 accepted arguments to receive $context. $record_id is an integer, and 0 for a HubSpot form target.
• cf7hs_object_sync_failed (action, $module, $form_id, $outcome, $context): an object failed or was skipped. Register with 4 accepted arguments to receive $context.
• cf7hs_submission_completed (action, $status, $form_id, $outcomes, $context): the submission reached its final outcome. $status is synced when the first object was written, otherwise failed. Register with 4 accepted arguments to receive $context. It does not fire when consent blocks the submission.
• cf7hs_is_form( $form_id, $id_or_hash ): true when the form is the one with that post id or that shortcode hash (the 7 or more characters in [contact-form-7 id="2f24e69"]).

Example: set the lifecycle stage to customer for contacts from one form only.

add_filter( 'cf7hs_object_payload', 'my_cf7hs_customer_stage', 10, 4 );
function my_cf7hs_customer_stage( $data, $module, $form_id, $context ) {
    if ( 'contacts' === $module && cf7hs_is_form( $form_id, '2f24e69' ) ) {
        $data['lifecyclestage'] = 'customer';
    }
    return $data;
}

The value is written in the same request that creates or updates the contact, so it costs no extra API call. For a form sent to a HubSpot form, $module is the HubSpot form GUID, so test that instead of 'contacts': if ( 'your-hubspot-form-guid' === $module && cf7hs_is_form( $form_id, '2f24e69' ) ).

Lifecycle stage notes: use the internal value (customer, not “Customer”). Custom stages have numeric ids; read the options of the lifecyclestage property in HubSpot to find them. HubSpot only moves a lifecycle stage forward through the API and forms, so a contact who is already past customer stays where they are.

Things to know:

• Keep callbacks idempotent. With asynchronous submissions the same object can reach your callback again on a retry (see $context['attempt']); cf7hs_object_sync_failed can repeat, cf7hs_object_synced effectively fires once per object. With async, uploaded files are attached after the objects are written, so cf7hs_object_synced can run before the files are attached.
• cf7hs_submission_completed says failed when the first object was not written. Later objects may still have been written, and no retry follows then. $outcomes lists every object and is empty when the final attempt threw an error. A form whose first object has no mapped fields fires no hooks.
• Return values of the filter: true/false are sent as true/false, other scalars as text, and '' clears the property in HubSpot. Arrays and other non-scalar values are dropped with a warning in the log. Date and datetime values are sent as epoch milliseconds in a string (for example 1760832000000), which is what HubSpot expects, so a callback that sets a date property should send the same format. A multi-checkbox is one value joined with ;. File fields and the HubSpot tracking context are not passed to the filter and cannot be changed by it.
• If a callback throws an error it is caught and logged as a warning, and the submission goes on. For the filter, the unfiltered properties are then sent, so changes made by earlier callbacks are discarded too.
• Warning about consent: the plugin checks consent before the filter runs. If your callback changes email or a consent property, the new value is sent without that check.
• Arguments of these hooks are only ever added at the end; new keys may appear in $context. cf7hs_is_form with a digit-only string of 7 or more characters matches the post id first, so it can differ from how Contact Form 7 resolves the same value.

cf7hs_log_ttl_days sets how many days log entries are kept (30 by default). cf7hs_error_email_throttle_seconds sets the window in which repeated error emails are counted instead of sent (one hour by default).

The admin stylesheets in src/Admin/Assets/build/ are compiled from the SCSS in src/Admin/Assets/scss/, which ships with the plugin. They are built with Dart Sass 1.105.1 and @wordpress/base-styles 13.3.0:
sass –no-source-map –style=compressed –load-path=node_modules src/Admin/Assets/scss:src/Admin/Assets/build