👋 Greetings from the Cleanlist.ai team. This knowldge base will cover everything required to start!
Guides
CRM Integration Setup

CRM Integration Setup

Connect Cleanlist with your CRM to automatically sync and enrich leads without manual imports and exports. This guide walks through the setup process.

Supported CRMs

Currently supported:

  • ✅ HubSpot (Full integration)
  • ✅ Salesforce (Full integration)

Coming soon:

  • Pipedrive
  • Zoho CRM
  • Microsoft Dynamics
  • Close.com

HubSpot Integration

Prerequisites

  • HubSpot account (any tier)
  • Admin access to HubSpot
  • Cleanlist subscription

Step 1: Connect HubSpot

  1. Navigate to Integrations page in Cleanlist
  2. Find HubSpot card
  3. Click Connect HubSpot
  4. OAuth login window opens
  5. Log in to HubSpot if not already logged in
  6. Review permissions Cleanlist is requesting
  7. Click Grant Access
  8. Redirected back to Cleanlist
  9. Connection status shows Connected ✓

Step 2: Configure Field Mapping

Map Cleanlist fields to HubSpot properties:

Default mappings (auto-configured):

Cleanlist          → HubSpot
--------------------------------
first_name         → firstname
last_name          → lastname
email              → email
phone              → phone
company            → company
job_title          → jobtitle
linkedin_url       → linkedin_url
city               → city
state              → state
country            → country

Custom field mapping:

  1. Click Edit Field Mapping
  2. Add mappings for custom fields
  3. Map Smart Columns to HubSpot custom properties
  4. Save configuration

Step 3: Set Sync Direction

Choose how data flows:

Option 1: HubSpot → Cleanlist (Import only)

  • Import contacts from HubSpot
  • Enrich in Cleanlist
  • Manual export back to HubSpot

Option 2: Two-Way Sync (Recommended)

  • Import contacts from HubSpot
  • Enrich in Cleanlist
  • Auto-sync enriched data back
  • Keep both systems updated

Configure:

  1. Select sync direction
  2. Choose update frequency:
    • Real-time (instant sync)
    • Hourly
    • Daily (recommended for most)
    • Manual only
  3. Set conflict resolution:
    • HubSpot wins
    • Cleanlist wins
    • Newest wins (recommended)
  4. Save settings

Step 4: Configure Sync Rules

Import filters:

  • Which HubSpot lists to sync
  • Lifecycle stage filters
  • Date range (e.g., created in last 90 days)
  • Custom properties

Example filters:

Import contacts where:
- Lifecycle stage = "Lead" or "MQL"
- Created date > 90 days ago
- Email is known
- NOT in "Do Not Enrich" list

Auto-enrichment:

  • ☐ Enrich new contacts automatically
  • ☐ Enrich email only
  • ☐ Enrich phone only
  • ☐ Enrich both email and phone

Step 5: Initial Sync

First-time sync:

  1. Review sync configuration
  2. Click Start Initial Sync
  3. System imports contacts matching filters
  4. Preview shows count: "Ready to import 1,250 contacts"
  5. Confirm import
  6. Monitor progress

Sync status dashboard:

  • Total contacts synced
  • Successful imports
  • Errors/skipped
  • Last sync time
  • Next scheduled sync

Step 6: Test and Verify

  1. Check synced contacts in Cleanlist
  2. Verify field mappings are correct
  3. Test enrichment on sample contact
  4. Verify sync back to HubSpot
  5. Review HubSpot for updated properties

Common test:

  1. Create test contact in HubSpot
  2. Wait for sync (or trigger manual)
  3. Enrich in Cleanlist
  4. Verify enriched data appears in HubSpot

Salesforce Integration

Prerequisites

  • Salesforce account (any edition)
  • System Administrator permissions
  • Cleanlist subscription

Step 1: Connect Salesforce

  1. Navigate to Integrations page
  2. Find Salesforce card
  3. Click Connect Salesforce
  4. Choose Salesforce environment:
    • Production (login.salesforce.com)
    • Sandbox (test.salesforce.com)
  5. OAuth login window opens
  6. Log in to Salesforce
  7. Review permissions
  8. Click Allow
  9. Redirected back to Cleanlist
  10. Connection status shows Connected ✓

Step 2: Choose Objects to Sync

Salesforce has multiple objects:

Select which to sync:

  • ☐ Leads: Unqualified prospects
  • ☐ Contacts: Qualified contacts (associated with Account)
  • ☐ Campaign Members: Contacts in campaigns

Most common: Sync both Leads and Contacts

Step 3: Configure Field Mapping

Standard field mappings (auto-configured):

Cleanlist          → Salesforce Lead
-----------------------------------
first_name         → FirstName
last_name          → LastName
email              → Email
phone              → Phone
company            → Company
job_title          → Title
linkedin_url       → LinkedIn_URL__c (custom field)
city               → City
state              → State
country            → Country

Custom field mapping:

  1. Click Add Custom Mapping
  2. Select Cleanlist field (or Smart Column)
  3. Select Salesforce field
  4. Set update permission (read-only or read-write)
  5. Save mapping

Step 4: Set Sync Rules

Lead/Contact filters:

Sync Leads where:
- Status != "Converted"
- Created Date >= 90 days ago
- Email is not empty

Sync Contacts where:
- Account is not null
- Last Activity < 180 days ago

Enrichment settings:

  • Auto-enrich new leads: Yes/No
  • Skip leads with phone: Yes/No (avoid re-enriching)
  • Default enrichment: Email, Phone, or Both

Duplicate handling:

  • Use Salesforce duplicate rules
  • Skip duplicates
  • Update existing records

Step 5: Initial Sync

  1. Review configuration
  2. Estimate sync size: "~2,500 Leads, ~1,800 Contacts"
  3. Start sync
  4. Monitor progress:
    • Leads imported: 2,500/2,500
    • Contacts imported: 1,800/1,800
    • Errors: 15 (view log)
  5. Review error log if any
  6. Verify in Cleanlist

Step 6: Configure Sync Back

Update Salesforce with enriched data:

Options:

  • Update immediately after enrichment
  • Batch updates hourly
  • Manual sync only

What to sync back:

  • Newly found emails
  • Newly found phones
  • Smart Column data (to custom fields)
  • Enrichment timestamps
  • Validation status

Field permissions:

  • Configure which fields Cleanlist can update
  • Respect field-level security
  • Audit trail in Salesforce

Sync Monitoring

Sync Dashboard

View real-time sync status:

Metrics:

  • Total records synced
  • Last sync time
  • Next scheduled sync
  • Success rate (%)
  • Error count

Charts:

  • Sync volume over time
  • Success vs. error rate
  • Credits used per sync
  • Data quality trends

Sync Logs

Detailed logs for troubleshooting:

Log entries show:

  • Timestamp
  • Operation (import, export, update)
  • Records affected
  • Status (success, failed, skipped)
  • Error message (if failed)
  • Credits used

Filter logs by:

  • Date range
  • Operation type
  • Status
  • Record ID

Error Handling

Common errors:

Insufficient permissions:

Error: User does not have permission to edit field 'Phone'
Solution: Grant edit permission in CRM or remove field from sync

Duplicate records:

Error: Duplicate record found
Solution: Enable duplicate handling or merge duplicates

Invalid data format:

Error: Phone number format invalid for Salesforce
Solution: Enable auto-formatting in sync settings

Advanced Features

Webhook Triggers

Set up webhooks for real-time enrichment:

Example: New lead in CRM → Auto-enrich

  1. CRM creates new lead
  2. Webhook fires to Cleanlist
  3. Cleanlist enriches lead automatically
  4. Syncs enriched data back to CRM
  5. Total time: <10 seconds

Setup:

  1. Enable webhooks in integration settings
  2. Configure trigger events (create, update)
  3. Set enrichment rules
  4. Test with sample record

Campaign Syncing

Sync specific CRM campaigns:

HubSpot Lists:

  • Sync specific lists only
  • Map lists to Cleanlist lead lists
  • Auto-enrich list members

Salesforce Campaigns:

  • Sync campaign members
  • Map campaigns to lead lists
  • Track enrichment per campaign

Scheduled Enrichment

Set up automatic enrichment schedules:

Example workflow:

Every Monday at 9 AM:
1. Sync new leads from CRM (last 7 days)
2. Enrich emails automatically
3. Sync enriched data back
4. Send summary email report

Configure:

  1. Go to integration settings
  2. Enable "Scheduled Enrichment"
  3. Set schedule (cron or UI)
  4. Choose enrichment options
  5. Set notification preferences

Best Practices

Data Quality

  1. Clean CRM data first:

    • Remove obvious duplicates
    • Standardize company names
    • Fix formatting issues

  2. Use filters wisely:

    • Don't sync entire CRM (unnecessary)
    • Focus on active leads/contacts
    • Exclude unqualified records

  3. Map fields carefully:

    • Test mappings on sample first
    • Verify data types match
    • Use custom fields for Smart Columns

Cost Management

  1. Avoid re-enriching:

    • Skip records with existing data
    • Set "last enriched" date filter
    • Only enrich when needed

  2. Use selective enrichment:

    • Enrich MQLs/SQLs only
    • Email-only for most leads
    • Phone for qualified leads only

  3. Monitor credit usage:

    • Set up low credit alerts
    • Review sync reports weekly
    • Adjust filters to reduce volume

Performance

  1. Optimize sync frequency:

    • Don't sync more often than needed
    • Daily is sufficient for most
    • Hourly for high-velocity teams

  2. Batch large syncs:

    • Initial sync during off-hours
    • Split large syncs into chunks
    • Use async processing for 10,000+

  3. Leverage caching:

    • Recently synced data is cached
    • Faster subsequent syncs
    • Reduces API calls to CRM

Troubleshooting

Sync Not Working

Check:

  • Integration still connected (re-auth if needed)
  • Sync is enabled (not paused)
  • Filters aren't too restrictive
  • CRM API limits not exceeded
  • Permissions still valid

Data Not Updating

Check:

  • Sync direction configured correctly
  • Field mappings are correct
  • Field-level permissions in CRM
  • Conflict resolution settings
  • Two-way sync enabled

Missing Records

Check:

  • Records match sync filters
  • Not marked as duplicate
  • Not in exclusion list
  • Created after last sync time
  • Review sync logs for errors

Disconnecting Integration

To disconnect CRM:

  1. Go to Integrations page
  2. Find connected CRM
  3. Click Disconnect
  4. Choose what to do with synced data:
    • Keep in Cleanlist
    • Delete from Cleanlist
  5. Confirm disconnection

Note: This revokes Cleanlist's access to your CRM. Data already in CRM remains unchanged.

Learn More

Exporting Your DataChangelog