HubSpot Integration
HubSpot is a CRM and marketing platform with contact management, email campaigns, and automation workflows. WP Smart Consent integrates with HubSpot via the CRM Contacts API v3, creating or updating contacts in real time using a single batch upsert call keyed by email address.
Enabling the Integration#
In the WP Smart Consent dashboard, go to CRMs & ESPs, find the HubSpot card, open the Connection tab, and paste in your Private App access token. Toggle the integration on and save.
To generate a token, log into HubSpot and go to Settings → Integrations → Private Apps. Create a new private app and grant it the crm.objects.contacts.write scope. Copy the access token from the app detail page. HubSpot Private App tokens do not expire unless rotated manually.
Custom Fields#
HubSpot contact properties are referenced by their internal property name — a lowercase snake_case identifier, not the display label shown in HubSpot. To find a property’s internal name, go to Settings → Properties in HubSpot, open the property, and check the internal name shown below the label.
In the Custom fields tab, add a row, select the WPSC source field on the left, and enter the HubSpot property internal name on the right — for example city, phone, jobtitle, or any custom property you have defined. These are sent inside the properties object on the contact upsert call.
Field Mapping#
The Field mapping tab maps WPSC fields to HubSpot’s standard contact properties. HubSpot’s native property names for the core fields are firstname, lastname, email, and phone. Additional standard properties include company, city, state, zip, country, and website. Custom properties use whatever internal name you assigned when creating them in HubSpot.
How It Works#
WP Smart Consent sends a POST to https://api.hubapi.com/crm/v3/objects/contacts/batch/upsert with idProperty: email. HubSpot’s native batch upsert handles both create and update in a single call — if a contact with that email already exists their properties are updated; if not, a new contact is created. No separate lookup call is needed.
Tags are sent as a semicolon-separated string in the hs_tags property if the HubSpot account has tags enabled.
Authentication uses a Bearer token in the Authorization header from the Private App.
Options#
The Options tab has three settings.
Update existing contacts — controls whether an existing HubSpot contact matched by email has their properties updated on each opt-in.
Send on unchecked — when enabled, contacts are forwarded to HubSpot even when the opt-in checkbox was not ticked.
Tags — a semicolon-separated list of tag values applied to the contact via the hs_tags property. Requires the HubSpot account to have tags enabled on contacts.
Troubleshooting#
Contact not appearing in HubSpot — confirm the Private App token is correct and has the crm.objects.contacts.write scope. A missing scope returns a 403. Check the WPSC Logs tab to confirm the opt-in event fired.
Custom property values not saving — confirm the destination key is the internal property name, not the display label. Internal names are shown in HubSpot → Settings → Properties and are always lowercase with underscores.
Tags not applying — the hs_tags property is only available on HubSpot accounts with the tags feature enabled. If tags are not supported on your plan or account, this field is silently ignored by HubSpot.