Twenty Zoho CRM Migration Tool

CLI migration tool for Zoho CRM to Twenty CRM.

Installation

npm install -g twenty-migrate-zoho

Usage

Basic Migration

twenty-migrate-zoho \
  --client-id YOUR_ZOHO_CLIENT_ID \
  --client-secret YOUR_ZOHO_CLIENT_SECRET \
  --refresh-token YOUR_ZOHO_REFRESH_TOKEN \
  --twenty-url http://localhost:3000 \
  --twenty-key YOUR_TWENTY_API_KEY

Dry Run (Preview)

twenty-migrate-zoho \
  --client-id YOUR_ZOHO_CLIENT_ID \
  --client-secret YOUR_ZOHO_CLIENT_SECRET \
  --refresh-token YOUR_ZOHO_REFRESH_TOKEN \
  --twenty-url http://localhost:3000 \
  --twenty-key YOUR_TWENTY_API_KEY \
  --dry-run

Select Objects

twenty-migrate-zoho \
  --client-id YOUR_ZOHO_CLIENT_ID \
  --client-secret YOUR_ZOHO_CLIENT_SECRET \
  --refresh-token YOUR_ZOHO_REFRESH_TOKEN \
  --twenty-url http://localhost:3000 \
  --twenty-key YOUR_TWENTY_API_KEY \
  --objects leads,contacts

Features

• Zoho CRM API Integration - REST API v7 with OAuth 2.0
• Paginated Extraction - Handle large datasets efficiently
• Schema Mapping - Zoho CRM → 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

| Zoho CRM | Twenty | |----------|--------| | Leads/Contacts → First Name, Last Name, Email, Phone | people → name, email, phone | | Accounts → Account Name, Website, Industry | companies → name, website, industry | | Deals → Deal Name, Amount, Currency, Stage | opportunities → name, amount, stage | | Notes → Note Content, Parent Module | notes → body, associations |

What Migrates

✅ Supported Objects:

• Leads → People (name, email, phone, company, lead source)
• Contacts → People (name, email, phone, job title, account)
• Accounts → Companies (name, website, industry, description)
• Deals → Opportunities (name, amount, currency, stage, close date)
• Notes → Notes (content, associations to parent objects)

❌ What Doesn't Migrate:

• Custom fields and modules
• File attachments
• Activity history and logs
• Pipeline stages (mapped to stage field)
• Currency conversion (stored as pipeline)
• Users and owners
• Webhooks and integrations
• Reports and dashboards

Command Line Options

Options:
  -c, --client-id <id>          Zoho Client ID (required)
  -s, --client-secret <secret>  Zoho Client Secret (required)
  -r, --refresh-token <token>   Zoho Refresh Token (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:

# Zoho CRM API Configuration
ZOHO_CLIENT_ID=your_zoho_client_id_here
ZOHO_CLIENT_SECRET=your_zoho_client_secret_here
ZOHO_REFRESH_TOKEN=your_zoho_refresh_token_here
ZOHO_API_URL=https://www.zohoapis.com/crm/v7

# 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=leads,contacts,accounts,deals,notes

Zoho CRM OAuth Setup

1. Create Zoho CRM Application

1. Go to Zoho Developer Console
2. Create a new server-based application
3. Configure OAuth 2.0 settings
4. Add redirect URL: https://www.zoho.com

2. Generate Refresh Token

1. Use the OAuth 2.0 Playground to generate refresh token
2. Or use this URL (replace with your client ID):

https://accounts.zoho.com/oauth/v2/auth?scope=ZohoCRM.modules.ALL&client_id=YOUR_CLIENT_ID&response_type=code&redirect_uri=https://www.zoho.com&access_type=offline

3. Exchange authorization code for refresh token

3. Test API Access

curl -X GET "https://www.zohoapis.com/crm/v7/users" \
  -H "Authorization: Zoho-oauthtoken YOUR_ACCESS_TOKEN"

Rate Limiting

• Zoho CRM 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-zoho",
    "version": "1.0.0",
    "objects": ["leads", "contacts", "accounts", "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-zoho \
  --client-id 1000.ABCDEFGHIJKLMNOPQRSTUVWXYZ \
  --client-secret abc123def456ghi789 \
  --refresh-token 1000.abcdefghijklmnopqrstuvwxyz \
  --twenty-url https://your-company.twenty.com \
  --twenty-key twenty_api_key_1234567890 \
  --batch 30 \
  --objects leads,contacts,accounts

Test Migration

twenty-migrate-zoho \
  --client-id 1000.ABCDEFGHIJKLMNOPQRSTUVWXYZ \
  --client-secret abc123def456ghi789 \
  --refresh-token 1000.abcdefghijklmnopqrstuvwxyz \
  --twenty-url http://localhost:3000 \
  --twenty-key twenty_api_key_1234567890 \
  --dry-run \
  --objects leads

Development

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

# 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

"Zoho CRM API connection failed"

• Check OAuth credentials (Client ID, Client Secret, Refresh Token)
• Verify Zoho CRM account permissions
• Ensure OAuth scope includes CRM modules

"Rate limit exceeded"

• Increase batch size delay
• Reduce concurrent requests
• Check Zoho CRM 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 Zoho CRM field names
• Verify Twenty CRM field requirements

"OAuth token expired"

• Generate new refresh token
• Update environment variables
• Re-run migration

Support

• Report Issues
• Discussions

Acknowledgments

• Zoho CRM API - REST API documentation
• Twenty CRM - Open-source CRM
• Commander.js - CLI framework
• CLI Progress - Progress bars