Skip to main content

Documentation Index

Fetch the complete documentation index at: https://memberpulseptyltd.mintlify.app/llms.txt

Use this file to discover all available pages before exploring further.

Platform administrators can diagnose and assist with HubSpot integration issues.

​
Common Issues

​
Authentication & Connection

Symptoms:
  • Integration disconnected
  • 401 errors in sync logs
Resolution:
  1. Check token expiry in integration status
  2. Verify HubSpot app hasn’t been uninstalled
  3. Re-authorize through Client Portal if needed
  4. Verify OAuth scopes match requirements
Symptoms:
  • 429 Too Many Requests errors
  • Syncs completing partially
Resolution:
  1. Check HubSpot API usage in their portal
  2. Review sync frequency settings
  3. Implement backoff if hitting limits
  4. Consider upgrading HubSpot plan for higher limits

​
Data Sync Issues

Common causes:
  • Duplicate detection blocking
  • Required properties missing
  • Property doesn’t exist in HubSpot
Troubleshooting:
  1. Check HubSpot duplicate management settings
  2. Verify all mapped properties exist
  3. Review property mapping configuration
  4. Check sync error logs for specific issues
Common causes:
  • Company not found in HubSpot
  • Association type not configured
  • Multiple companies with same domain
Troubleshooting:
  1. Verify company exists or needs to be created first
  2. Check association mapping settings
  3. Review company matching rules (by domain, name)
Common causes:
  • List is static (not dynamic)
  • Contact doesn’t meet list criteria
  • List enrollment automation disabled
Troubleshooting:
  1. Verify list type in HubSpot
  2. Check list criteria/filters
  3. Review automation settings in integration

​
Engagement Tracking Issues

Common causes:
  • Engagement type not supported
  • Timeline API permissions missing
  • Custom timeline event type not configured
Troubleshooting:
  1. Verify timeline event type is created in HubSpot
  2. Check OAuth scopes include timeline permissions
  3. Review engagement type mapping

​
Diagnostic Endpoints

​
Connection Status

GET /api/admin/integrations/hubspot/{organization_id}/status
Authorization: Bearer {admin_token}
Response: 
{
  "connected": true,
  "hub_id": "12345678",
  "portal_name": "Example Organization",
  "token_expires_at": "2025-01-15T16:00:00Z",
  "scopes": ["contacts", "companies", "timeline"],
  "last_sync": "2025-01-15T10:30:00Z",
  "sync_stats": {
    "contacts_synced": 892,
    "contacts_failed": 5,
    "companies_synced": 234,
    "engagements_synced": 4521
  },
  "rate_limit": {
    "daily_limit": 500000,
    "daily_used": 12534,
    "secondly_limit": 100
  }
}

​
View Sync Errors

GET /api/admin/integrations/hubspot/{organization_id}/errors
Authorization: Bearer {admin_token}
Response: 
{
  "errors": [
    {
      "id": "err-uuid-1",
      "type": "contact_sync",
      "hubspot_error": "PROPERTY_DOESNT_EXIST",
      "property": "custom_field_xyz",
      "record_id": "member-uuid",
      "timestamp": "2025-01-15T09:15:00Z"
    }
  ],
  "total": 5,
  "page": 1
}

​
Retry Failed Records

POST /api/admin/integrations/hubspot/{organization_id}/retry
Authorization: Bearer {admin_token}
Content-Type: application/json

{
  "error_ids": ["err-uuid-1", "err-uuid-2"]
}

​
Verify Property Mapping

GET /api/admin/integrations/hubspot/{organization_id}/property-mapping
Authorization: Bearer {admin_token}
Response: 
{
  "contact_properties": [
    {
      "memberpulse_field": "email",
      "hubspot_property": "email",
      "status": "valid"
    },
    {
      "memberpulse_field": "membership_type",
      "hubspot_property": "membership_tier",
      "status": "valid"
    },
    {
      "memberpulse_field": "custom_field",
      "hubspot_property": "custom_xyz",
      "status": "invalid",
      "error": "Property does not exist in HubSpot"
    }
  ]
}

​
Escalation

For complex HubSpot issues:
  1. Collect organization ID, HubSpot portal ID, error details
  2. Check HubSpot system status page
  3. Review HubSpot API changelog for breaking changes
  4. Escalate to development team with diagnostic output