Description
n8n-nodes-twenty-fork
This is an advanced n8n community node that provides comprehensive Twenty CRM integration using modern GraphQL architecture. Originally forked from n8n-nodes-twenty by S Hodgson, it has been completely rewritten with GraphQL-first approach and modular architecture by Matias Lopez.
Twenty CRM is a modern open-source CRM platform. This node is compatible with Twenty v1.4.0 and later.
🚀 Key Features
- 🔄 GraphQL-First Architecture: Uses Twenty’s native GraphQL API for optimal performance
- 📊 4 Main Resources: Complete CRUD operations for People, Companies, Opportunities, and Notes
- 🔍 Unified Search: Search by email, phone, custom fields with smart matching
- ✅ Robust Validation: UUID validation, field resolution, and centralized error handling
- 🏗️ Modular Design: Well-organized, maintainable codebase with TypeScript
- 🎯 Advanced Operations: Create, Find, Update, Delete, List with filtering and pagination
- 🔗 Smart Relationships: Automatic linking between People, Companies, and Opportunities
- 📝 Rich Note System: Attach notes to any entity with full text support
- Twenty CRM v1.4.0 or later
- n8n v0.140.0 or later
- Node.js 18.10 or later
- Create: Add new contacts with names, emails, phones, job titles, and company relationships
- Find: Search by email, phone, or custom fields with confidence scoring
- Update: Modify existing contact information using email or ID lookup
- Delete: Remove contacts by ID
- List by Company: Get all people associated with a specific company
- Create: Add companies with names, domains, addresses, and revenue information
- Find: Search by company name with fuzzy matching
- Update: Modify company details including contact information and financials
- Delete: Remove companies by ID
- Create: Add new sales opportunities with amounts, stages, and relationships
- Find: Search opportunities by name or custom criteria
- Update: Modify deal information, stages, and amounts
- Delete: Remove opportunities by ID
- List: Get filtered lists of opportunities with pagination
- Create: Attach notes to people, companies, or opportunities
- Update: Modify note content and titles
- Delete: Remove notes by ID
- List: Get notes associated with specific entities
- Single Request Efficiency: GraphQL queries fetch exactly the data needed
- Type Safety: Full TypeScript support with schema validation
- Future-Proof: Aligned with Twenty’s primary development direction
- Better Error Handling: Detailed GraphQL error messages and field validation
- Optimized Performance: Reduced network overhead compared to multiple REST calls
📦 Installation
For n8n
1. Go to Settings → Community Nodes
2. Install: n8n-nodes-twenty-fork
Requirements
🔧 Configuration
1. Generate API Key: In Twenty, go to Settings → Developers → API Keys
2. Add Credentials: In n8n, search for “Twenty API” credentials
3. Configure:
– API Key: Your Twenty API key
– Domain: Your Twenty instance URL (e.g., https://app.twenty.com or http://localhost:3000)
– ⚠️ Do not include /graphql in the domain – the node handles this automatically
📋 Available Resources & Operations
| Resource | Operations | Description |
|———-|————|————-|
| 👤 Person | Create, Find, Update, Delete, List by Company | Manage contacts with full profile data |
| 🏢 Company | Create, Find, Update, Delete | Handle organizations and business entities |
| 💼 Opportunity | Create, Find, Update, Delete, List | Track sales opportunities and deals |
| 📝 Note | Create, Update, Delete, List | Attach notes to people, companies, or opportunities |
Person Operations
Company Operations
Opportunity Operations
Note Operations
🏗️ Technical Architecture
GraphQL Migration Benefits
Modular Code Organization
nodes/Twenty/
├── operations/ # Resource-specific business logic
│ ├── PersonOperations.ts
│ ├── CompanyOperations.ts
│ ├── OpportunityOperations.ts
│ └── NoteOperations.ts
├── shared/ # Shared utilities and helpers
│ ├── ValidationUtils.ts
│ ├── ErrorHandler.ts
│ └── LoadOptionsUtils.ts
├── properties/ # n8n UI property definitions
├── types/ # TypeScript type definitions
├── constants/ # Application constants
├── builders/ # Property builders for dynamic UI
└── GenericFunctions.ts # Core GraphQL infrastructure
Smart Features
🤝 Credits & Acknowledgments
Original Creator
S Hodgson – Original author of n8n-nodes-twenty
The foundation of this work is built upon S Hodgson’s excellent initial implementation. This fork extends and modernizes that work with GraphQL migration and enhanced architecture.
Fork Maintainer
Matias Lopez – GraphQL migration, modern architecture, and ongoing maintenance
Development Tools
What This Fork Adds
This fork transforms the original REST-based implementation into a modern, GraphQL-first solution:
🛠️ Compatibility
| Component | Version | Status |
|———–|———|——–|
| Twenty CRM | v1.4.0+ | ✅ Tested |
| n8n | v0.140.0+ | ✅ Supported |
| Node.js | 18.10+ | ✅ Required |
📚 Resources
🐛 Issues & Support
For issues, feature requests, or questions:
📄 License
MIT License – see LICENSE.md for details.
—
This README was created with assistance from Claude Code for comprehensive documentation.
