> ## 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.

# Salesforce Troubleshooting

> Diagnose and resolve Salesforce CRM integration issues

Platform administrators can diagnose and assist with Salesforce integration issues.

## Common Issues

### Authentication & Connection

<AccordionGroup>
  <Accordion title="OAuth authentication failures">
    **Symptoms:**

    * Integration shows "disconnected"
    * 401 Unauthorized errors in sync logs

    **Resolution:**

    1. Check OAuth token expiry
    2. Verify Connected App settings in Salesforce
    3. Confirm callback URL is correctly configured
    4. Re-authorize if refresh token has expired
  </Accordion>

  <Accordion title="Insufficient permissions">
    **Symptoms:**

    * Partial sync failures
    * "INSUFFICIENT\_ACCESS" errors

    **Resolution:**

    1. Review Salesforce user's profile permissions
    2. Verify object-level and field-level security
    3. Check sharing rules for relevant records
  </Accordion>
</AccordionGroup>

### Data Sync Issues

<AccordionGroup>
  <Accordion title="Contacts not syncing">
    **Common causes:**

    * Duplicate rules blocking insert
    * Required fields not mapped
    * Validation rules failing

    **Troubleshooting:**

    1. Check Salesforce duplicate management settings
    2. Review field mapping configuration
    3. Check Salesforce validation rules on Contact object
    4. Review sync error logs for specific field errors
  </Accordion>

  <Accordion title="Field mapping errors">
    **Common causes:**

    * Picklist value not in Salesforce
    * Data type mismatch
    * Field no longer exists

    **Troubleshooting:**

    1. Compare field mapping with current Salesforce schema
    2. Verify picklist values exist in Salesforce
    3. Check for recent Salesforce schema changes
  </Accordion>

  <Accordion title="Bidirectional sync conflicts">
    **Common causes:**

    * Record modified in both systems
    * Sync timing causing overwrites
    * Missing conflict resolution rules

    **Troubleshooting:**

    1. Review sync timestamps for both systems
    2. Check conflict resolution configuration
    3. Identify which system should be source of truth
  </Accordion>
</AccordionGroup>

### Activity Tracking Issues

<AccordionGroup>
  <Accordion title="Activities not appearing">
    **Common causes:**

    * Task/Event creation disabled
    * Activity history limits reached
    * Activity type not configured

    **Troubleshooting:**

    1. Verify activity sync is enabled in settings
    2. Check Salesforce activity history retention
    3. Review activity type mapping
  </Accordion>
</AccordionGroup>

## Diagnostic Endpoints

### Connection Status

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

**Response:**

```json theme={null}
{
  "connected": true,
  "instance_url": "https://na123.salesforce.com",
  "api_version": "59.0",
  "token_expires_at": "2025-01-15T16:00:00Z",
  "last_sync": "2025-01-15T10:30:00Z",
  "sync_stats": {
    "contacts_synced": 1523,
    "contacts_failed": 12,
    "activities_synced": 8934,
    "last_full_sync": "2025-01-10T00:00:00Z"
  }
}
```

### View Sync Errors

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

**Response:**

```json theme={null}
{
  "errors": [
    {
      "id": "err-uuid-1",
      "type": "contact_sync",
      "salesforce_error": "DUPLICATES_DETECTED",
      "record_id": "member-uuid",
      "details": "Duplicate contact found with matching email",
      "timestamp": "2025-01-15T09:15:00Z",
      "retry_count": 2
    }
  ],
  "total": 12,
  "page": 1
}
```

### Retry Failed Records

```bash theme={null}
POST /api/admin/integrations/salesforce/{organization_id}/retry
Authorization: Bearer {admin_token}
Content-Type: application/json

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

### Test Field Mapping

```bash theme={null}
POST /api/admin/integrations/salesforce/{organization_id}/test-mapping
Authorization: Bearer {admin_token}
Content-Type: application/json

{
  "object_type": "Contact",
  "sample_record_id": "member-uuid"
}
```

## Escalation

For complex Salesforce issues:

1. Collect organization ID, Salesforce org ID, error details
2. Review Salesforce debug logs if available
3. Check Salesforce Trust status for service issues
4. Escalate to development team with full diagnostic output