Twenty HubSpot Migration Tool

CLI migration tool for HubSpot to Twenty CRM.

Installation

npm install -g twenty-migrate-hubspot

Usage

Basic Migration

twenty-migrate-hubspot \
  --source-key YOUR_HUBSPOT_API_KEY \
  --twenty-url http://localhost:3000 \
  --twenty-key YOUR_TWENTY_API_KEY

Dry Run (Preview)

twenty-migrate-hubspot \
  --source-key YOUR_HUBSPOT_API_KEY \
  --twenty-url http://localhost:3000 \
  --twenty-key YOUR_TWENTY_API_KEY \
  --dry-run

Select Objects

twenty-migrate-hubspot \
  --source-key YOUR_HUBSPOT_API_KEY \
  --twenty-url http://localhost:3000 \
  --twenty-key YOUR_TWENTY_API_KEY \
  --objects contacts,companies

Features

• HubSpot API Integration - Official SDK for data extraction
• Paginated Extraction - Handle large datasets efficiently
• Schema Mapping - HubSpot → Twenty CRM field mapping
• Batch Processing - Process records in configurable batches
• Progress Tracking - Real-time migration progress
• Dry Run Mode - Preview migration without changes
• Error Handling - Detailed error logging and recovery
• Duplicate Prevention - Check for existing records

Migration Mapping

| HubSpot | Twenty | |---------|--------| | contacts → firstname, lastname, email, phone | people → name, email, phone | | companies → name, domain, industry | companies → name, domainName, industry | | deals → dealname, amount, closedate, pipeline | opportunities → name, amount, closeDate | | notes → hs_note_body, associations | notes → body + person/company links |

What Migrates

✅ Supported Objects:

• Contacts → People (name, email, phone, lifecycle stage)
• Companies → Companies (name, domain, industry, description)
• Deals → Opportunities (name, amount, close date, pipeline)
• Notes → Notes (body, associations to contacts/companies)

❌ What Doesn't Migrate:

• Email history and threads
• File attachments
• Custom properties (partially supported)
• Sequences and workflows
• Users and owners
• Activity history
• Lists and segments

Command Line Options

Options:
  -k, --source-key <key>      HubSpot API key (required)
  -u, --twenty-url <url>      Twenty CRM URL (required)
  -t, --twenty-key <key>      Twenty CRM API key (required)
  -d, --dry-run              Preview migration without writing data
  -o, --objects <objects>    Objects to migrate (comma-separated)
  -b, --batch <number>        Batch size for API calls (default: 60)
  -h, --help                 Show help
  -v, --version              Show version

Environment Variables

Create a .env file:

# HubSpot API Configuration
HUBSPOT_API_KEY=your_hubspot_api_key_here
HUBSPOT_API_URL=https://api.hubapi.com

# Twenty CRM Configuration
TWENTY_URL=http://localhost:3000
TWENTY_API_KEY=your_twenty_api_key_here

# Migration Settings
BATCH_SIZE=60
RATE_LIMIT_DELAY=600
DRY_RUN=false
OBJECTS=contacts,companies,deals,notes

Rate Limiting

• HubSpot API: 100 requests per minute
• Automatic delay: 600ms between requests
• Batch processing: 60 records per batch
• Retry mechanism: Automatic retry on failures

Reports

Migration Report

{
  "timestamp": "2026-04-04T14:30:00.000Z",
  "migration": {
    "tool": "twenty-migrate-hubspot",
    "version": "1.0.0",
    "objects": ["contacts", "companies", "deals", "notes"],
    "dryRun": false
  },
  "summary": {
    "total": 1000,
    "success": 985,
    "errors": 15,
    "successRate": "98.50%"
  },
  "objectResults": {
    "people": {
      "attempted": 500,
      "success": 495,
      "errors": 5,
      "successRate": "99.00%"
    },
    "companies": {
      "attempted": 200,
      "success": 198,
      "errors": 2,
      "successRate": "99.00%"
    },
    "opportunities": {
      "attempted": 150,
      "success": 147,
      "errors": 3,
      "successRate": "98.00%"
    },
    "notes": {
      "attempted": 150,
      "success": 145,
      "errors": 5,
      "successRate": "96.67%"
    }
  },
  "errors": [],
  "recommendations": []
}

Error Log

Batch 1 (people): Duplicate email detected - [email protected]
Batch 2 (companies): Invalid industry format - "Tech & IT"
Batch 3 (opportunities): Invalid amount format - "$50,000"

Examples

Large Dataset Migration

twenty-migrate-hubspot \
  --source-key pat_1234567890 \
  --twenty-url https://your-company.twenty.com \
  --twenty-key twenty_api_key_1234567890 \
  --batch 30 \
  --objects contacts,companies

Test Migration

twenty-migrate-hubspot \
  --source-key pat_1234567890 \
  --twenty-url http://localhost:3000 \
  --twenty-key twenty_api_key_1234567890 \
  --dry-run \
  --objects contacts

Development

# Clone repository
git clone https://github.com/deliveredbyai/twenty-migrate-hubspot.git
cd twenty-migrate-hubspot

# Install dependencies
npm install

# Build project
npm run build

# Run tests
npm test

# Start development
npm run dev

Contributing

1. Fork the repository
2. Create feature branch
3. Make your changes
4. Run tests
5. Submit pull request

License

MIT License - see LICENSE file for details.

Troubleshooting

Common Issues

"HubSpot API connection failed"

• Check API key validity
• Verify HubSpot account permissions
• Ensure API key has proper scopes

"Rate limit exceeded"

• Increase batch size delay
• Reduce concurrent requests
• Check HubSpot API limits

"Duplicate records"

• Tool automatically prevents duplicates
• Check existing data in Twenty CRM
• Use dry-run to preview duplicates

"Invalid field mapping"

• Review field mapping table
• Check HubSpot field names
• Verify Twenty CRM field requirements

Support

• Report Issues
• Discussions

Acknowledgments

• HubSpot API Client - Official SDK
• Twenty CRM - Open-source CRM
• Commander.js - CLI framework
• CLI Progress - Progress bars