Core Forms
Get Core Forms

HubSpot Integration

Create or update a contact in HubSpot CRM when a form is submitted.

Action type: hubspot Class: Core_Forms\Actions\HubSpot Source: src/actions/class-hubspot.php

Setup

  1. In HubSpot, go to Settings > Integrations > Private Apps.
  2. Create a new Private App with the crm.objects.contacts.write scope.
  3. Copy the Private App Token (starts with pat-...).
  4. In WordPress, edit your form > Actions tab > Add Action > Add to HubSpot.
  5. Paste the token and configure field mappings.

Settings Reference

Setting Required Default Description
Private App Token Yes -- HubSpot Private App access token
Email Field No email Form field name containing the email address
Name Field No name Form field name containing the full name
Company Field No -- Form field name containing the company name
Custom Properties No -- Map form fields to HubSpot contact properties

Custom Property Mapping

One mapping per line, form_field=hubspot_property:

phone=phone
company=company
job_title=jobtitle
website=website

The left side is the form field name. The right side is the HubSpot internal property name (lowercase, no spaces). Custom properties must exist in HubSpot before they can be written to.

Name Handling

The Name Field value is automatically split on the first space: - First word becomes firstname - Remaining words become lastname

For example, "Jane Smith" sets firstname: Jane, lastname: Smith.

Contact Deduplication

HubSpot uses the createOrUpdate endpoint (/contacts/v1/contact/createOrUpdate/email/{email}). If a contact with the submitted email already exists, it is updated with the new values. If not, a new contact is created.

Example

Form with name, email, company, phone, and role fields:

  • Email Field: email
  • Name Field: name
  • Company Field: company
  • Custom Properties: phone=phone role=jobtitle

Creates/updates a HubSpot contact with: - Email: jane@example.com - First Name: Jane - Last Name: Smith - Company: Acme Inc - Phone: 555-0100 - Job Title: Marketing Director

How It Works

  1. Validates that an access token is provided and the email field contains a valid email.
  2. Splits the name field into first/last name.
  3. Builds a properties array with standard fields (email, firstname, lastname, company).
  4. Parses custom property mappings and adds them to the array.
  5. All property values are sanitized with sanitize_text_field() and property names with sanitize_key().
  6. POSTs to the HubSpot createOrUpdate endpoint with Bearer auth.
  7. The request times out after 15 seconds.

Troubleshooting

  • Invalid email: The action requires a valid email address. If the email field is empty or invalid, the action silently skips.
  • Property not found: Custom properties must be created in HubSpot first (Settings > Properties). The property name must match exactly.
  • Token scope: Ensure the Private App has crm.objects.contacts.write permission.