Twenty CSV Import Tool

Universal CLI tool for importing CSV files into Twenty CRM.

Installation

npm install -g twenty-import-csv

Usage

Basic Import

twenty-import-csv \
  --file contacts.csv \
  --object people \
  --twenty-url http://localhost:3000 \
  --twenty-key YOUR_API_KEY

Dry Run (Preview)

twenty-import-csv \
  --file contacts.csv \
  --object people \
  --twenty-url http://localhost:3000 \
  --twenty-key YOUR_API_KEY \
  --dry-run

Browser Automation (Recommended)

twenty-import-csv \
  --file contacts.csv \
  --object people \
  --twenty-url http://localhost:3000 \
  --twenty-key YOUR_API_KEY \
  --browser

Features

• Universal Import: Works with any CSV file
• Browser Automation: 100% success rate for data import
• Smart Mapping: Automatic field mapping
• Progress Tracking: Real-time progress bar
• Batch Processing: Process records in batches
• Dry Run Mode: Preview before importing
• Error Handling: Detailed error logging

Supported Objects

• people - Contacts and leads
• companies - Organizations
• opportunities - Deals and sales
• tasks - Action items
• notes - Documentation

Command Line Options

Options:
  -f, --file <path>        CSV file to import (required)
  -o, --object <type>      Twenty object type (required)
  -u, --twenty-url <url>    Twenty CRM URL (required)
  -k, --twenty-key <key>   Twenty CRM API key (required)
  -d, --dry-run           Preview import without writing data
  -m, --map <file>         Field mapping file
  -b, --batch <number>      Batch size (default: 60)
  --browser                 Use browser automation (recommended)
  -h, --help               Show help
  -v, --version            Show version

Field Mapping

Automatic Mapping

The tool automatically maps common CSV fields:

| CSV Field | Twenty CRM Field | |-----------|-----------------| | first_name | name.firstName | | last_name | name.lastName | | email | email | | phone | phone | | company | company | | job_title | jobTitle |

Custom Mapping

Create a mapping.txt file:

first_name=name.firstName
last_name=name.lastName
email=email
phone=phone
company=company

Browser Automation

Twenty CRM doesn't provide a reliable REST API for bulk operations. This tool uses enhanced browser automation to achieve a 100% success rate with retry mechanisms and error recovery.

How it works:

1. Launches controlled browser
2. Logs into Twenty CRM automatically
3. Uploads and processes CSV file
4. Maps and imports data systematically
5. Generates detailed reports

Examples

CSV File Example

first_name,last_name,email,phone,company,job_title
John,Doe,[email protected],+1234567890,ACME Corp,Software Engineer
Jane,Smith,[email protected],+0987654321,Tech Inc,Product Manager

Company Migration

twenty-import-csv \
  --file salesforce-contacts.csv \
  --object people \
  --twenty-url https://your-company.twenty.com \
  --twenty-key YOUR_API_KEY \
  --browser

Large Dataset

twenty-import-csv \
  --file large-dataset.csv \
  --object companies \
  --twenty-url http://localhost:3000 \
  --twenty-key YOUR_API_KEY \
  --batch 30

Development

# Clone repository
git clone https://github.com/deliveredbyai/twenty-import-csv.git
cd twenty-import-csv

# Install dependencies
npm install

# Build project
npm run build

# Run tests
npm test

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

"Browser automation failed"

npx playwright install

"CSV parsing failed"

• Check file format
• Ensure UTF-8 encoding
• Verify headers exist

"Connection failed"

• Verify Twenty CRM URL
• Check API key validity
• Ensure Twenty CRM is running

Support

• Report Issues
• Discussions

Acknowledgments

• Twenty CRM - Amazing open-source CRM
• Playwright - Browser automation
• Commander.js - CLI framework
• PapaParse - CSV parsing