HubSpot Integration
Connect Top Provider with HubSpot to automatically create/augment Contact and post timeline events
Purpose-built for teams that keep HubSpot as the system of record for Contacts and want automated contact creation plus clear activity on the contact timeline.
What This Integration Does
Top Provider's HubSpot integration performs two actions — and only these two:
- Create or augment a Contact in HubSpot using your field mappings.
- Post a Timeline Event on that contact's activity feed for traceability.
Prerequisites
- A HubSpot account with permission to install apps.
- Access to the Top Provider Seller Portal to manage integrations.
Quick Setup Guide
Connect your HubSpot account in minutes:
Open Delivery Settings
Sign in to the Seller Portal and go to Delivery Settings (left sidebar) or navigate to /delivery.
Connect with HubSpot
Click "+ Connect with HubSpot" to start the HubSpot OAuth flow in a new tab.
Grant Permissions (Scopes)
When prompted, grant only the scopes our integration needs:
crm.objects.contacts.write— create/update contactstimeline— create timeline events
Verify Connection
After authorization you'll return to the Seller Portal. In HubSpot Connections you'll see:
- HubSpot portal (domain)
- Connected user email
- Granted scopes
- Connection date
Complete Setup
Your integration is ready to create contacts and post timeline events.
Configuring Your Integration
Customize behavior to match your workflow:
Access Integration Details
In HubSpot Connections, locate your connection and click "Details."
Configure Settings
On the integration page, click "Settings."
Adjust Constants (Optional)
Add key–value pairs that will be sent with every contact we create. Common examples for HubSpot Contacts:
lifecyclestage(e.g.,lead,marketingqualifiedlead)hs_lead_status(e.g.,NEW,OPEN,IN_PROGRESS— values depend on your portal)- Any custom contact property you maintain (e.g.,
source_system: top_provider)
Configure Lead Order Assignment (Optional)
Click "Attached Lead Orders" to choose which Top Provider lead orders feed this connection. By default, all lead orders will send to HubSpot.
Save
Click "Save" to apply your configuration.
Field Mappings
Control which Top Provider fields map to contact properties in HubSpot.
Open Field Mappings
In Settings, click "Adjust Field Mappings."
Map Standard Fields
For each field, enter the exact internal property name from HubSpot (e.g., email, firstname, lastname, lifecyclestage, hs_lead_status).
Add More Mappings
Under Available Fields, add any additional Top Provider fields and map them to HubSpot contact properties — including your custom contact properties.
Save
Click "Save" to confirm.
Need to check internal names? In HubSpot go to Settings → Properties → Contacts, open a property, and click the </> icon to see its internal name.
Timeline Events
Each delivery generates a clear Timeline Event on the contact's activity feed. You can filter for these in HubSpot's activity panel (look under Integrations or by event type) to audit deliveries and build workflows.
Testing Your Configuration
Send a Test
On the integration details page, click "Test Endpoint." We'll send a sample contact payload and a sample timeline event.
Review Notifications
Open Notification History to see delivery attempts, timestamps, status, and any error messages returned by HubSpot.
Check in HubSpot
In HubSpot, open Contacts and find the test contact. Confirm properties populated as expected. In the contact's Activity feed, verify your Top Provider timeline event appears.
If the test contact or timeline event doesn't appear, use Notification History to identify any property name typos or permission mismatches.
Behavior with Existing Contacts
If the contact already exists in HubSpot, our integration does not create a duplicate. We post a Timeline Event to the existing contact for traceability. (Your mapped properties are only updated if you've enabled that behavior in your field mappings.)
Common Issues & Fixes
| Symptom | Cause | Fix |
|---|---|---|
PROPERTY_DOESNT_EXIST for hs_pipeline_stage, hs_pipeline, or dealstage | These are not contact properties (they belong to Tickets/Deals). | Remove pipeline-related fields from constants and mappings. Use contact properties only (e.g., lifecyclestage, hs_lead_status). |
| Contact not created | Missing required fields like email | Ensure email is mapped and present in the payload. |
| Timeline event missing | App lacks timeline scope or event type not installed | Reconnect and grant timeline scope; confirm the app's event template is active. |
| "Invalid property value" | Using display labels instead of internal values | Use internal names/values (see tip above or use HubSpot's Properties API). |
FAQ
Need help? Contact support at support@topprovider.com.