> ## Documentation Index
> Fetch the complete documentation index at: https://memberpulseptyltd.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# HubSpot Troubleshooting

> Diagnose and resolve HubSpot CRM integration issues

Platform administrators can diagnose and assist with HubSpot integration issues.

## Common Issues

### Authentication & Connection

<AccordionGroup>
  <Accordion title="OAuth token issues">
    **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
  </Accordion>

  <Accordion title="API rate limiting">
    **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
  </Accordion>
</AccordionGroup>

### Data Sync Issues

<AccordionGroup>
  <Accordion title="Contacts not syncing">
    **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
  </Accordion>

  <Accordion title="Company association 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)
  </Accordion>

  <Accordion title="List membership not updating">
    **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
  </Accordion>
</AccordionGroup>

### Engagement Tracking Issues

<AccordionGroup>
  <Accordion title="Activities not appearing in timeline">
    **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
  </Accordion>
</AccordionGroup>

## Diagnostic Endpoints

### Connection Status

```bash theme={null}
GET /api/admin/integrations/hubspot/{organization_id}/status
Authorization: Bearer {admin_token}
```

**Response:**

```json theme={null}
{
  "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

```bash theme={null}
GET /api/admin/integrations/hubspot/{organization_id}/errors
Authorization: Bearer {admin_token}
```

**Response:**

```json theme={null}
{
  "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

```bash theme={null}
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

```bash theme={null}
GET /api/admin/integrations/hubspot/{organization_id}/property-mapping
Authorization: Bearer {admin_token}
```

**Response:**

```json theme={null}
{
  "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