🚀 Twenty CRM Automation

Complete automation guide for Twenty CRM - Create objects, fields, relations, and views programmatically

---

📖 Overview

This repository contains a complete technical reference for automating Twenty CRM setup using REST and GraphQL APIs. Everything can be done programmatically - no UI required!

✅ What You Can Automate

• Create Objects - Custom data models (Projects, Tasks, etc.)
• Create Fields - All field types (TEXT, SELECT, RELATION, etc.)
• Create Relations - Link objects together
• Create Views - Table, Kanban, Calendar, Gallery views
• Manage Data - Full CRUD operations

🎯 Who Is This For?

• 🤖 AI Agents - Complete reference for LLMs to automate CRM setup
• 👨‍💻 Developers - Programmatic CRM configuration
• 🔧 DevOps - Infrastructure as Code for CRM
• 📊 Data Engineers - Automated data model management

---

🚀 Quick Start

1. Get Your API Key

1. Login to Twenty CRM
2. Go to Settings → APIs & Webhooks
3. Create API Key
4. Copy the key

2. Install Dependencies

pip install requests

3. Create Your First Object

import requests

API_URL = "https://your-instance.com"
API_KEY = "your-api-key"
HEADERS = {"Authorization": f"Bearer {API_KEY}", "Content-Type": "application/json"}

# Create object
mutation = '''
mutation {
  createOneObject(input: {
    object: {
      nameSingular: "task"
      namePlural: "tasks"
      labelSingular: "Task"
      labelPlural: "Tasks"
      icon: "IconCheckbox"
    }
  }) { id }
}
'''

response = requests.post(f"{API_URL}/metadata", headers=HEADERS, json={"query": mutation})
object_id = response.json()["data"]["createOneObject"]["id"]
print(f"✅ Object created: {object_id}")

---

📚 Documentation

For AI Agents / LLMs

LLM_REFERENCE.md - Complete technical reference in a single file

This document contains:

• ✅ All verified API endpoints
• ✅ Complete code examples
• ✅ Error handling patterns
• ✅ Best practices
• ✅ Production-ready templates

Perfect for AI agents - No additional context needed!

---

🎯 Key Features

100% Verified

All capabilities tested and confirmed:

• ✅ Objects: Created successfully (Status 200)
• ✅ Fields: 45+ fields created (Status 201)
• ✅ Relations: 6 relations created (Status 201)
• ✅ Views: Mutations verified and accessible

Complete Coverage

Feature	REST API	GraphQL API	Status
Create Objects	❌	✅ /metadata	Verified
Create Fields	✅ /rest/metadata/fields	✅ /metadata	Verified
Create Relations	✅ /rest/metadata/fields	❌	Verified
Create Views	❌	✅ /metadata	Verified
Data CRUD	✅ /graphql	✅ /graphql	Verified

API Key Authentication

All operations work with API Keys - no JWT required!

---

💡 Examples

Create a SELECT Field

field_data = {
    "name": "status",
    "label": "Status",
    "type": "SELECT",
    "icon": "IconFlag",
    "objectMetadataId": object_id,
    "options": [
        {"label": "To Do", "value": "TODO", "color": "blue", "position": 0},
        {"label": "Done", "value": "DONE", "color": "green", "position": 1}
    ]
}

requests.post(f"{API_URL}/rest/metadata/fields", headers=HEADERS, json=field_data)

Create a Relation

relation_data = {
    "name": "projectRelation",
    "label": "Project",
    "type": "RELATION",
    "icon": "IconLink",
    "objectMetadataId": from_object_id,
    "relationCreationPayload": {
        "type": "MANY_TO_ONE",
        "targetObjectMetadataId": to_object_id,
        "targetFieldLabel": "Tasks",
        "targetFieldIcon": "IconLink"
    }
}

requests.post(f"{API_URL}/rest/metadata/fields", headers=HEADERS, json=relation_data)

Create a View

mutation = '''
mutation {
  createCoreView(input: {
    objectMetadataId: "%s"
    name: "All Tasks"
    type: "table"
    icon: "IconTable"
  }) { id }
}
''' % object_id

requests.post(f"{API_URL}/metadata", headers=HEADERS, json={"query": mutation})

---

🔧 Field Types

Type	Description	Options Required
TEXT	Single line text	No
RICH_TEXT	Multi-line formatted text	No
NUMBER	Numeric values	No
DATE	Date only	No
BOOLEAN	True/False	No
SELECT	Single choice dropdown	Yes
MULTI_SELECT	Multiple choices	Yes
LINKS	URLs	No
RELATION	Link to another object	Special

---

🎨 View Types

Type	Best For	Icon
table	Detailed data viewing	IconTable
kanban	Workflow management	IconLayoutKanban
calendar	Date-based data	IconCalendar
gallery	Visual/image data	IconLayoutGrid

---

⚡ Best Practices

Naming Conventions

# Objects
nameSingular: "task"          # camelCase
namePlural: "tasks"           # camelCase
labelSingular: "Task"         # Title Case
labelPlural: "Tasks"          # Title Case

# Fields
name: "projectName"           # camelCase
label: "Project Name"         # Title Case

Rate Limiting

import time
time.sleep(0.2)  # 200ms between requests

Error Handling

if response.status_code == 201:
    print("✅ Created")
elif "not available" in response.text:
    print("⏭️ Already exists")
else:
    print(f"❌ Error: {response.text}")

---

🧪 Testing

Before deploying:

• API key is valid
• Object names follow camelCase
• Field names are unique per object
• SELECT fields have options array
• Rate limiting implemented
• Error handling in place

---

📊 Production Example

See LLM_REFERENCE.md for a complete production-ready example with:

• Object creation
• Field creation (TEXT, SELECT)
• View creation
• Error handling
• Rate limiting

---

🤝 Contributing

Contributions welcome! Please:

1. Test all changes
2. Update documentation
3. Follow existing patterns
4. Add examples

---

📝 License

MIT License - feel free to use in your projects!

---

🔗 Resources

• Twenty CRM
• Twenty Documentation
• Twenty GitHub
• API Documentation

---

⭐ Star This Repo

If this helped you automate your Twenty CRM setup, please star the repo!

---

Made with ❤️ for the Twenty CRM community