Twenty CRM

n8n-nodes-twenty

npm version CI License: MIT n8n community node

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 ```bash 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 ```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:** ```json { "name": "Acme Inc", "domainName": "acme.com" } ``` **๐Ÿ“ค Node sends to API:** ```json { "name": "Acme Inc", "domainName": { "primaryLinkUrl": "https://acme.com", "primaryLinkLabel": "", "secondaryLinks": [] } } ```
**๐Ÿ‘ค Person โ€” You provide:** ```json { "firstName": "John", "lastName": "Doe", "email": "john@example.com" } ``` **๐Ÿ“ค Node sends to API:** ```json { "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) | ```diff + โœ… 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 ```bash # 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](https://www.npmjs.com/package/@linkedpromo/n8n-nodes-twenty) | | ๐Ÿ’ป GitHub | [github.com/vomos-ua/n8n-nodes-twenty](https://github.com/vomos-ua/n8n-nodes-twenty) | | ๐Ÿ  Twenty CRM | [twenty.com](https://twenty.com) | | ๐Ÿ› Issues | [Report a bug](https://github.com/vomos-ua/n8n-nodes-twenty/issues) | --- ## ๐Ÿ“„ License MIT License โ€” see [LICENSE](LICENSE) for details. ---

Made with โค๏ธ by abm24