Logo

Documentation

Troubleshooting HubSpot Integration

Resolve common issues with your HubSpot integration

Common Issues & Solutions

Connection & Authentication Issues

Integration Connection Failed

Symptoms:

  • Unable to connect to HubSpot during setup
  • "Authorization failed" error messages
  • Redirect loops during OAuth flow

Solutions:

  1. Check HubSpot Permissions

    • Ensure you have admin access to the HubSpot portal
    • Verify your user account has integration management permissions
    • Confirm the HubSpot plan includes required features

  2. Browser & Network Issues

    • Disable popup blockers for Quotient and HubSpot domains
    • Clear browser cache and cookies
    • Try the connection process in an incognito/private window
    • Check for corporate firewall restrictions

  3. Multiple HubSpot Accounts

    • Ensure you're logged into the correct HubSpot portal
    • Log out of other HubSpot accounts before connecting
    • Use a dedicated browser session for the integration setup

Token Refresh Failures

Symptoms:

  • "Invalid token" errors in sync logs
  • Intermittent sync failures
  • Authentication errors after initial setup

Solutions:

  1. Reconnect Integration

    • Go to HubSpot integration settings
    • Click "Reconnect" to refresh OAuth tokens
    • Complete the authorization flow again

  2. Check HubSpot App Status

    • Verify the Quotient app is still installed in HubSpot
    • Check app permissions haven't been revoked
    • Review HubSpot's connected apps settings

Data Sync Issues

Records Not Syncing

Symptoms:

  • New HubSpot contacts don't appear in Quotient
  • Changes in one system don't reflect in the other
  • Sync dashboard shows no recent activity

Troubleshooting Steps:

  1. Verify Sync Preferences

    ✓ Check that object sync is enabled for the affected type
✓ Confirm sync direction allows the desired data flow
✓ Verify dependencies (e.g., Lists requires Contacts)

  2. Check Data Requirements

    • Contacts: Must have valid email addresses
    • Companies: Must have a name
    • Lists: Must contain contacts with email addresses

  3. Review Sync Logs

    • Check the integration dashboard for error messages
    • Look for rate limiting or API quota issues
    • Verify network connectivity during sync windows

  4. Manual Sync Test

    • Trigger a manual sync for the affected object type
    • Monitor progress in real-time
    • Check if specific records are causing failures

Field Mapping Issues

Symptoms:

  • Data appears in one system but not the other
  • Field values are incorrect or truncated
  • Custom properties not syncing

Solutions:

  1. Verify Field Mappings

    • Check that mappings exist for the affected fields
    • Ensure data types are compatible between systems
    • Verify sync direction allows the desired data flow

  2. Data Type Compatibility

    HubSpot Text → Quotient STRING ✓
HubSpot Number → Quotient STRING ✗ (use NUMBER)
HubSpot Date → Quotient DATETIME ✗ (use DATE)

  3. Custom Property Setup

    • Ensure custom properties exist in both systems
    • Check property permissions and visibility
    • Verify property names match exactly in mappings

Duplicate Records

Symptoms:

  • Multiple records for the same person/company
  • Sync conflicts between similar records
  • Data inconsistencies across systems

Prevention & Resolution:

  1. Email-Based Deduplication

    • Ensure all contacts have unique, valid email addresses
    • Clean up duplicate emails in HubSpot before syncing
    • Use HubSpot's built-in deduplication tools

  2. Company Matching

    • Verify company names are consistent between systems
    • Use domain-based matching where possible
    • Manually merge duplicates in both systems

  3. Sync Conflict Resolution

    • Review conflict resolution logs in the integration dashboard
    • Understand timestamp-based conflict resolution
    • Manually resolve conflicts that require business logic

List & Segment Sync Issues

Lists Not Creating in Quotient

Symptoms:

  • HubSpot lists don't appear in Quotient
  • List sync shows errors or warnings
  • Empty lists in Quotient despite HubSpot membership

Solutions:

  1. Check List Requirements

    • Verify the list contains contacts with email addresses
    • Ensure list members are also synced as contacts
    • Check that list sync is enabled in preferences

  2. List Type Compatibility

    • Dynamic lists → Quotient segments (inbound only)
    • Static lists → Quotient lists (bi-directional)
    • Verify the list type matches expected behavior

  3. Member Sync Dependencies

    • Ensure contact sync is enabled and working
    • Check that list members exist in Quotient
    • Review member email address validity

Bi-directional List Sync Conflicts

Symptoms:

  • Members added in one system don't appear in the other
  • Sync conflicts for list membership
  • Inconsistent member counts between systems

Solutions:

  1. Conflict Resolution Strategy

    • Understand that most recent change wins
    • Avoid simultaneous changes in both systems
    • Use manual sync to resolve immediate conflicts

  2. Member Email Matching

    • Ensure members have matching email addresses
    • Check for email format differences (case, spacing)
    • Verify email addresses are not suppressed

Email Sync Issues

Template Creation Failed

Symptoms:

  • "Template setup failed" error messages
  • Missing quotient-base.html template in HubSpot
  • Email sync toggle won't enable

Solutions:

  1. HubSpot Plan Verification

    • Confirm Marketing Hub Starter or higher plan
    • Verify marketing email API access is included
    • Check Design Manager permissions

  2. Template Setup Process

    • Try the automated template setup again
    • Manually verify template creation in HubSpot Design Manager
    • Check for template naming conflicts

  3. Permission Issues

    • Ensure integration has content and marketing-email scopes
    • Verify user permissions for Design Manager access
    • Check HubSpot app installation status

Email Content Not Displaying

Symptoms:

  • Blank emails in HubSpot
  • Content not injecting into template
  • Formatting issues in synced emails

Solutions:

  1. Template Validation

    • Verify quotient-base.html contains required modules
    • Check for template modifications that break injection
    • Test template with sample content

  2. Content Format Issues

    • Review HTML compatibility with HubSpot
    • Check for unsupported CSS or JavaScript
    • Verify image URLs are accessible

Performance & Rate Limiting

Slow Sync Performance

Symptoms:

  • Sync operations take hours to complete
  • Timeouts during large data imports
  • Delayed sync completion

Optimization Strategies:

  1. Selective Sync

    • Only enable objects you actively use in Quotient
    • Disable unused custom property mappings
    • Focus on essential data for initial sync

  2. Batch Size Optimization

    • Allow automatic batch size adjustment
    • Monitor sync performance metrics
    • Consider breaking large datasets into phases

  3. Timing Optimization

    • Schedule manual syncs during off-peak hours
    • Avoid simultaneous large operations
    • Rely on daily automatic sync for regular updates

API Rate Limiting

Symptoms:

  • "Rate limit exceeded" errors in sync logs
  • Sync operations failing intermittently
  • Delayed sync completion

Solutions:

  1. Rate Limit Management

    • Monitor API usage in integration dashboard
    • Spread sync operations across time
    • Use HubSpot's rate limit headers for optimization

  2. Sync Frequency Adjustment

    • Reduce manual sync frequency
    • Rely on scheduled daily sync for bulk updates
    • Allow automatic sync processes to handle regular updates

Best Practices

Data Management

Maintain Data Quality

Before Syncing:

  • Clean up duplicate records in HubSpot
  • Standardize data formats (phone numbers, addresses)
  • Validate email addresses and remove invalid ones
  • Ensure required fields are populated

Ongoing Maintenance:

  • Regularly review sync logs for errors
  • Monitor data consistency between systems
  • Set up alerts for sync failures
  • Perform periodic data audits

Field Mapping Strategy

Default Mappings:

  • Start with Quotient's default field mappings
  • Only customize mappings when necessary
  • Document custom mapping decisions
  • Test mappings with sample data before full deployment

Custom Properties:

  • Use consistent naming conventions between systems
  • Choose appropriate data types for each field
  • Avoid overly complex custom property structures
  • Plan for future scalability

Sync Configuration

Object Sync Strategy

Phased Approach:

  1. Phase 1: Enable Contacts sync only
  2. Phase 2: Add Companies after contact sync stabilizes
  3. Phase 3: Enable Lists and Segments
  4. Phase 4: Add Deals and Email sync

Selective Enablement:

  • Only sync objects you'll actively use in Quotient
  • Consider data volume and sync performance
  • Plan for future growth and additional objects

Performance Optimization

Large Datasets:

  • Expect longer initial sync times for large HubSpot accounts
  • Monitor sync progress and performance metrics
  • Consider data archiving for very old records
  • Use HubSpot's data export tools for historical analysis

Sync Strategy:

  • Rely on daily automatic sync for comprehensive updates
  • Use manual sync only when immediate updates are needed
  • Schedule intensive operations during off-peak hours
  • Allow background processes to handle regular synchronization

Monitoring & Maintenance

Proactive Monitoring

Daily Checks:

  • Review sync status dashboard
  • Monitor error rates and performance metrics
  • Check for failed sync operations
  • Verify sync scheduling and automation

Weekly Reviews:

  • Analyze sync performance trends
  • Review data consistency reports
  • Check for new error patterns
  • Update field mappings as needed

Maintenance Schedule

Monthly Tasks:

  • Review and clean up sync logs
  • Update custom field mappings
  • Audit data quality across systems
  • Test disaster recovery procedures

Quarterly Reviews:

  • Assess integration performance and ROI
  • Review and update sync preferences
  • Plan for new feature adoption
  • Conduct security and compliance audits

Need Help? Check the HubSpot Knowledge Base for additional HubSpot-specific guidance, or contact support if issues persist.