Description

n8n-nodes-twenty

n8n community node for Twenty CRM — the Open Source CRM platform

—

✨ Features

| | Feature | Description |
|:—:|———|————-|
| 🔄 | Full CRUD | Create, Read, Update, Delete for all resources |
| ⚡ | Auto Transform | Handles Twenty’s complex object formats automatically |
| 📦 | Bulk Operations | Process multiple records in a single request |
| 🔍 | Upsert | Create or update based on matching field |
| 🔔 | Webhooks | Real-time triggers for all CRM events |
| 🔁 | Auto Retry | Automatic retries with exponential backoff for transient errors |
| 📋 | Dynamic Dropdowns | Company/Person lists loaded from API in UI |
| 🧩 | Custom Objects | Support for any Twenty CRM custom object |

—

📥 Installation

Via n8n UI (Recommended)

1. Go to Settings → Community Nodes
2. Click Install a community node
3. Enter: @linkedpromo/n8n-nodes-twenty
4. Click Install

Via npm

npm install @linkedpromo/n8n-nodes-twenty

—

🔑 Configuration

Step 1: Get Your API Key

1. Log into your Twenty CRM instance
2. Go to Settings → Developers → API Keys
3. Create a new API key or copy an existing one

Step 2: Add Credentials in n8n

1. Go to Credentials → Add Credential → Twenty CRM API
2. Fill in the fields:

| Field | Value | Example |
|:——|:——|:——–|
| API URL | Your Twenty instance URL (without /rest) | https://your-twenty.com |
| API Key | JWT token from Twenty | eyJhbGciOiJIUzI1NiIs... |

> ⚠️ Important: URL must be WITHOUT trailing slash (/) and WITHOUT /rest

—

📋 Supported Operations

TwentyCrm Node

| Category | Resource | Operations | Description |
|:——–:|:———|:———–|:————|
| 🏢 | Company | Create, Get, Get Many, Update, Delete, Upsert | Manage organizations and businesses |
| 👤 | Person | Create, Get, Get Many, Update, Delete, Upsert | Manage contacts and individuals |
| 💰 | Opportunity | Create, Get, Get Many, Update, Delete, Upsert | Track deals and sales pipeline |
| 📝 | Note | Create, Get, Get Many, Update, Delete | Add notes to records |
| ✅ | Task | Create, Get, Get Many, Update, Delete | Manage tasks and to-dos |
| 📊 | Activity | Create, Get, Get Many, Update, Delete | Track activities and interactions |
| 📦 | Bulk | Bulk Create, Bulk Update, Bulk Delete | Mass operations on records |
| 🔍 | Search | Search | Find records across multiple types |
| 🧩 | Custom Object | Create, Get, Get Many, Update, Delete | Work with any custom object |

TwentyCrmTrigger Node

| Category | Events | Description |
|:——–:|:——-|:————|
| 🏢 | company.created company.updated company.deleted | Company changes |
| 👤 | person.created person.updated person.deleted | Person changes |
| 💰 | opportunity.created opportunity.updated opportunity.deleted | Deal changes |
| ✅ | task.created task.updated task.deleted | Task changes |
| 📝 | note.created note.updated note.deleted | Note changes |

—

🧩 Custom Objects

Work with any Twenty CRM custom object using the Custom Object resource:

1. Select Custom Object as the resource
2. Enter the Object API Name (e.g., customLeads, myCustomObject)
3. Provide fields as JSON

{
  "customField1": "value1",
  "customField2": "value2"
}

> 💡 Find your object’s API name in Twenty CRM Settings → Data Model → Your Object → API Name

—

📋 Dynamic Dropdowns

The node automatically loads data from your CRM for convenient selection:

| Field | Loads From | Used In |
|:——|:———–|:——–|
| Company | /rest/companies | Person → Company field |
| Assignee | /rest/people | Task → Assignee field |
| Opportunities | /rest/opportunities | Various relation fields |

> 💡 Dropdowns show up to 60 items. For more, use the record ID directly.

—

🔁 Automatic Retry

The node automatically retries failed requests for transient errors:

| Status Code | Error Type | Retries |
|:———–:|:———–|:——-:|
| 429 | Rate Limit Exceeded | ✅ 3x |
| 502 | Bad Gateway | ✅ 3x |
| 503 | Service Unavailable | ✅ 3x |
| 504 | Gateway Timeout | ✅ 3x |
| Network | Connection errors | ✅ 3x |

• Exponential backoff: 1s → 2s → 4s (with jitter)
• Respects Retry-After header from API
• No retry for client errors (400, 401, 403, 404)

—

🔄 Auto Field Transformation

The node automatically transforms simple values to Twenty’s complex format:

🏢 Company — You provide: { "name": "Acme Inc", "domainName": "acme.com" }	📤 Node sends to API: { "name": "Acme Inc", "domainName": { "primaryLinkUrl": "https://acme.com", "primaryLinkLabel": "", "secondaryLinks": [] } }
👤 Person — You provide: { "firstName": "John", "lastName": "Doe", "email": "john@example.com" }	📤 Node sends to API: { "name": { "firstName": "John", "lastName": "Doe" }, "emails": { "primaryEmail": "john@example.com", "additionalEmails": [] } }

> ⚠️ Note: Twenty CRM Notes API does NOT support a body field. Only title and position are available.

—

🔧 Troubleshooting

🐌 Node hangs / timeout

| | |
|:–|:–|
| Symptom | Node runs for a long time without returning results |
| Cause | Incorrect API URL in credentials |
| Solution | Check URL format (see below) |

+ ✅ Correct:   https://your-twenty-instance.com
❌ Wrong:     https://your-twenty-instance.com/
❌ Wrong:     https://your-twenty-instance.com/rest

🔄 Node still doesn’t work after changing credentials

Solution: Delete the node completely and add a new one with correct credentials

❌ Common API Errors

| Code | Error | Cause | Solution |
|:—-:|:——|:——|:———|
| 401 | Unauthorized | Invalid API key | Check credentials |
| 404 | Not Found | Wrong endpoint | Verify API URL |
| 400 | Bad Request | Invalid data | Check field values |
| 429 | Rate Limited | Too many requests | Node auto-retries |

—

📦 Compatibility

| Requirement | Version |
|:————|:——–|
| n8n | 2.4.6+ |
| Node.js | 18.10+ |
| Twenty CRM | API v1 |

—

🧪 Development

Install dependencies
npm install
Build
npm run build
Run tests
npm test
Run tests with coverage
npm run test:coverage
Lint
npm run lint

—

🔗 Links

| | |
|:–|:–|
| 📦 npm | npmjs.com/package/@linkedpromo/n8n-nodes-twenty |
| 💻 GitHub | github.com/vomos-ua/n8n-nodes-twenty |
| 🏠 Twenty CRM | twenty.com |
| 🐛 Issues | Report a bug |

—

📄 License

MIT License — see LICENSE for details.

—

Made with ❤️ by abm24