# AI Source: https://docs.twenty.com/getting-started/core-concepts/ai How Twenty uses AI to enhance your CRM experience. Twenty integrates AI directly into your CRM — not as a gimmick, but as a tool that works within your data model and permission system. ## AI Chatbot Ask questions about your data in natural language. The AI chatbot can query your CRM records, summarize information, and help you find what you're looking for without building complex filters. ## AI Agents AI agents go beyond chat — they can execute multi-step tasks autonomously: * Enrich records with data from external sources * Draft and send follow-up emails * Analyze pipeline health and flag at-risk deals * Process incoming data and route it to the right team Agents work within your existing workflows, so you can combine AI with manual approvals, conditional logic, and external API calls. ## Permissions & safety AI in Twenty respects your permission model. Agents can only access objects and fields that the user (or role) has permission to view. Sensitive data stays protected even when AI is involved. Detailed reference on the chatbot, agents, and permission controls. # Apps Source: https://docs.twenty.com/getting-started/core-concepts/apps Extend Twenty with code — custom objects, server-side logic, UI components, and AI agents, all as TypeScript packages. Most CRMs give you a config panel. Twenty gives you a platform. Apps are how developers extend Twenty beyond what the UI offers — defining data models, server-side logic, UI components, and AI capabilities as code, then deploying them to one or more workspaces. ## Why apps exist Workflows cover no-code automation. But some things need code: a custom pricing engine, a proprietary enrichment pipeline, a compliance check that runs on every record update, a custom UI panel that pulls data from an internal tool. Apps let you build these as first-class extensions — not brittle scripts talking to an API from outside, but code that runs on the platform with full access to the type system, permission model, and UI. ## What an app can define An app is a TypeScript package that declares **entities** using the `twenty-sdk`: | Entity | What it does | | - | - | | **Objects & Fields** | New data tables and fields on existing objects — same treatment as built-in ones | | **Logic Functions** | Server-side TypeScript triggered by HTTP routes, cron schedules, or database events | | **Front Components** | Sandboxed React components that render inside Twenty's UI (side panel, widgets, command menu) | | **Skills & Agents** | AI capabilities — reusable instructions and autonomous assistants | | **Views & Navigation** | Pre-configured list views and sidebar menu items | Everything is detected via AST analysis at build time — no config files, no registration boilerplate. Put a `export default defineObject(...)` in any `.ts` file and the SDK picks it up. ## How they run * **Logic functions** execute in isolated Node.js processes, sandboxed from the host. They access data through a typed API client scoped to the app's role permissions. * **Front components** run in Web Workers using Remote DOM — sandboxed from the main page but rendering native DOM elements (not iframes). * **Permissions** are enforced at the API level. An app only sees what its role allows. ## The developer experience You write your app as a TypeScript project on your machine. The CLI watches your source files and live-syncs them to a running Twenty server — edit a file, see the change in the UI within a second. The typed API client regenerates automatically when the schema changes. When you're ready, `yarn twenty app:publish --private` pushes to a production server, or `yarn twenty app:publish` lists your app on npm and the Twenty marketplace. Three-phase walkthrough — scaffold, run a local server, sync your changes. # Calendar & Email Source: https://docs.twenty.com/getting-started/core-concepts/calendar-and-email Sync your email and calendar with Twenty. Twenty connects to your existing tools so your CRM stays up to date without manual data entry. ## Email sync Connect your **Google Workspace** or **Microsoft 365** mailbox. Once connected: * Emails are automatically linked to the matching Company and People records * Full email threads are visible on each record's timeline * You can send emails directly from Twenty * Multiple mailboxes per user are supported You control what gets imported — filter by date range or sender to avoid pulling in irrelevant emails. ## Calendar sync Calendar events sync automatically from your connected account. Events appear on the relevant CRM records, giving you a complete picture of your interactions with each contact or company. ## Integrations Beyond email and calendar, Twenty connects to external tools through: | Method | Use case | | - | - | | **API** | Build custom integrations with the GraphQL or REST API | | **Webhooks** | Push real-time notifications to external systems when records change | | **Zapier** | Connect to 5,000+ apps without code | | **Workflow HTTP actions** | Call any external API as part of an automated workflow | ## Custom apps Developers can build full-featured apps on top of Twenty — adding custom UI, server-side logic, and deep integrations. Apps can be published for the community or kept private. Set up email sync, calendar sync, and troubleshoot issues. Build custom integrations with the Twenty API. # Dashboards Source: https://docs.twenty.com/getting-started/core-concepts/dashboards Track performance and visualize your CRM data with custom dashboards. Dashboards give you real-time visibility into your business metrics — pipeline health, team performance, revenue trends, and anything else you want to track. ## Widgets Each dashboard is made up of widgets. A widget is a single chart or metric tied to your CRM data. You can configure: * **Chart type** — Bar, line, pie, number, and more * **Data source** — Any object in your data model (standard or custom) * **Filters** — Narrow down to specific records, date ranges, or segments * **Aggregation** — Count, sum, average, min, max on any numeric field * **Grouping** — Break down by select fields, dates, or relations ## What you can track * Pipeline value by stage * Deals closed over time * Average deal size by source * Task completion rates * Custom metrics on any object ## Sharing Dashboards are workspace-level — everyone on your team can see them. Arrange widgets in a grid layout and resize them to build the view that works for your team. Detailed reference on creating dashboards, configuring widgets, and chart settings. # Data Model Source: https://docs.twenty.com/getting-started/core-concepts/data-model Understand how Twenty structures your data with objects, fields, and relations. Everything in Twenty is built around **objects** and **fields** — the building blocks of your data model. ## Objects Objects are the tables that hold your data. Twenty comes with standard objects out of the box: * **Companies** — Organizations you do business with * **People** — Individual contacts * **Opportunities** — Deals in your pipeline * **Tasks** — Action items for your team * **Notes** — Free-form text linked to records You can also create **custom objects** for anything your business needs — projects, support tickets, products, contracts, or anything else. ## Fields Fields are the properties on each object. Twenty supports a wide range of field types: | Category | Types | | - | - | | **Basic** | Text, Number, Boolean, Date, Currency, Rating, Select | | **Composite** | Address (street, city, state, zip), Full Name, Links, Phones, Emails | | **Special** | Relation, File Attachment, JSON, Actor (who created/modified) | Every object also gets automatic system fields: `id`, `createdAt`, `updatedAt`, `createdBy`, and `position`. ## Relations Objects connect to each other through relations. A Company has many People, an Opportunity belongs to a Company, and so on. You can create custom relations between any objects, including many-to-many relationships. ## What makes this powerful Unlike traditional CRMs where you're limited to pre-defined fields on pre-defined objects, Twenty lets you model your data exactly the way your business works. Custom objects get the same first-class treatment as built-in ones — including API endpoints, views, permissions, and workflow triggers. Full reference on objects, fields, relations, and how to configure them. # Glossary Source: https://docs.twenty.com/getting-started/core-concepts/glossary Key terms used throughout Twenty. ## API API (Application Programming Interface) allows you to connect Twenty with other software systems and build custom integrations. ## Apps Apps are custom extensions built as code that can define data models and logic functions. They enable developers to create reusable customizations that can be deployed across multiple workspaces. ## Code Actions Code Actions are workflow steps that let you write custom JavaScript to transform data, make calculations, or perform complex logic that isn't possible with built-in actions. ## Command Menu The Command Menu is a quick-access interface (opened with `Cmd + K` on Mac and `Ctrl + K` on Windows) that lets you perform actions, create records, and navigate your workspace efficiently. ## Company & People The CRM has two fundamental types of records: * A `Company` represents a business or organization. * `People` represent your company's current and prospective customers or clients. ## Custom Fields Custom Fields are data fields you create to capture information specific to your business needs and processes. ## Data Model A Data Model is the structure that defines how information is organized in your CRM, including what objects exist, their properties (fields), and how they relate to each other. ## Favorites Favorites are records you've marked for quick access, appearing in your sidebar for instant navigation to important data. ## Field A field refers to a specific area where particular data is stored for an entity. ## Iterator An Iterator is a workflow action that loops through an array of items, executing subsequent actions for each item in the list. ## Kanban A `Kanban` is a visual way to track your business processes using cards and columns. Each column represents a stage in your process (for example: new, ongoing, won, lost), and you move records through these stages as they progress. ## Object An Object is a data structure that represents a specific type of entity in your CRM (like People, Companies, or Opportunities). Objects can be standard (built-in) or custom (created by you). ## Opportunities Opportunities in Twenty CRM are potential deals or sales with accounts or contacts. ## Record A Record indicates an instance of an object, like a specific account or contact. ## Relation Fields Relation Fields create connections between different objects, allowing you to link records together (like connecting a Person to a Company). ## Standard Fields Standard Fields are pre-built data fields that come with objects by default and provide common functionality across all workspaces. ## Tasks Tasks in Twenty CRM are assigned activities relating to contacts, accounts, or opportunities. ## Triggers Triggers are the starting point of a workflow — the event or condition that initiates the automation. Examples include record creation, record updates, webhooks, or scheduled times. ## Views You can customize the display of your records using views, setting different filters, layouts and sorting options for each view. ## Upsert Upsert is an operation that combines "update" and "insert" — it updates an existing record if a match is found, or creates a new record if no match exists. ## Webhooks Webhooks are automated messages sent from Twenty to other applications when specific events occur, enabling real-time data synchronization. ## Workflows Workflows are automated processes that trigger actions based on specific conditions, helping you automate repetitive tasks and business processes. ## Workspace A `Workspace` typically represents a company using Twenty. It holds all the records and data that you and your team members add to Twenty. It has a single domain name, which is typically the domain name your company uses for employee email addresses. ## Workspace Members Workspace Members are the Twenty users from your team who have access to your workspace. They can be assigned as owners or assignees for records. # Layout Source: https://docs.twenty.com/getting-started/core-concepts/layout How to navigate, browse, and view records in Twenty. ## The main layout The center of the screen is where your records live — people, companies, opportunities, tasks, notes, dashboards, workflows, and any custom objects. You view, edit, and delete records here, and create new views. ## Sidebar The left sidebar gives you: * **Workspace switcher** — switch between workspaces or create a new one (top dropdown) * **Search** — press `/` to focus instantly, searches across all objects * **Settings** — access from the top left * **Favorites** — pinned views, unique per user * **Object shortcuts** — quick access to People, Companies, Opportunities, etc. * **Workflows** — create automations Drag items to reorder, create folders to group related objects, hide what you don't use. Use the collapse button at the top of the sidebar, or choose **Collapse sidebar** from the command menu (`Cmd+K` on Mac or `Ctrl+K` on Windows). When collapsed, use **Expand sidebar** to show it again. ## Command menu Press `Cmd+K` (Mac) or `Ctrl+K` (Windows) — or click the three dots in the top right. From here you can: * Create new records * Import and export data via CSV * Create new views * Access deleted records (Twenty supports soft and hard deletes) * See keyboard shortcuts for navigating your workspace ## Search Accessible via the Command Menu, the top of the sidebar, or by pressing `/`. Search works across all objects. ## Side panel Click a record to open the side panel on the right — a quick overview of the record's key information without leaving the current page. Click **Open** to go to the full record page. ## Views Every object supports multiple views — unlimited per object. Use the dropdown at the top left to switch between them. * **Table** — spreadsheet-style rows and columns, with grouping, inline editing, and column customization * **Kanban** — drag-and-drop cards organized by a select field, ideal for pipelines * **Calendar** — records plotted by a date field for time-based planning Each view saves its own filters, sorting, and field visibility. Share views with your workspace or keep them private. Favorite views for fast access from the sidebar. ## Record pages When you open a record, the detail page is built from configurable **tabs** and **widgets**. Add, remove, reorder, and resize widgets on a grid — fields, related records, emails, timeline, tasks, notes, files, charts, iframes, and more. Each object type has its own layout. Sidebar, views, record pages — detailed reference and how-tos. # Workflows Source: https://docs.twenty.com/getting-started/core-concepts/workflows Automate your business processes with Twenty's visual workflow builder. Workflows let you automate repetitive tasks and connect Twenty to external tools — without writing code (though you can if you want to). ## How workflows work Every workflow has three parts: 1. **Trigger** — What starts the workflow 2. **Steps** — What happens next (one or more actions in sequence) 3. **Variables** — Data that flows between steps ## Triggers | Trigger | When it fires | | - | - | | **Record event** | A record is created, updated, deleted, or upserted | | **Manual** | A user clicks a button (on a single record, multiple records, or globally) | | **Schedule** | On a recurring interval (cron syntax) | | **Webhook** | An external system sends an HTTP POST | ## Actions Workflows can chain any combination of: * **Record operations** — Create, update, find, delete, or upsert records * **Send email** — Send or draft emails from connected accounts * **HTTP request** — Call any external API * **Code** — Run custom JavaScript for complex logic * **Branches** — If/else conditions to split the workflow path * **Iterator** — Loop over arrays of data * **AI Agent** — Let an AI agent process data autonomously * **Delay** — Wait before continuing * **Form** — Collect user input mid-workflow ## What you can build * Send Slack alerts when a deal reaches a certain stage * Auto-enrich new contacts with data from external APIs * Detect stale opportunities and notify the owner * Sync data between Twenty and your billing system * Generate PDFs or invoices from record data * Auto-reply to inbound emails matching certain criteria Detailed reference on triggers, actions, variables, and real-world automation recipes. # Why Twenty Source: https://docs.twenty.com/getting-started/introduction You've been choosing between software that's easy to start but impossible to change, and software that's flexible but takes months to set up. Twenty is the third option: **a production-ready CRM you can reshape as you go.** ## What makes Twenty different Twenty is a platform you can build on, not a product you configure. Built for Agents Agents operate inside your data model with real permissions. Skills, Tools, MCP. Secured Extensibility The flexibility of vibe-coded tools on secured foundations. Modern Stack React, TypeScript. Your team already knows how to extend Twenty. No proprietary languages, no gatekeeping. No Lock-In Open-source core, self-hostable, export your data anytime. ## Who is Twenty for * **Large enterprises replacing Salesforce** — your team spends more time fighting the tool than using it. You feel locked-in and the costs keep rising. * **Startups with technical founders** — you've outgrown spreadsheets and Notion. You have big ambitions and want a CRM that scales with you. * **GTM teams looking for an edge** — you want to build your own lead scoring, your own enrichment, your own outbound workflows. * **Privacy-conscious organizations** — you need to self-host and own your data end to end. Regulatory, contractual, or just principle. * **Salesforce partners** — your developers are tired of presenting license cost increases to your clients. You want a better DX, and to deliver projects faster at a lower license cost for your clients. * **Web development agencies** — your team knows TypeScript, React, and PostgreSQL. Twenty opens the CRM market to you without learning APEX or getting proprietary certifications. ## Who Twenty is not for * **Teams that want a CRM they never have to think about.** Twenty rewards teams that want to stay close to their tools and shape them over time. If you want something fully managed, Pipedrive or HubSpot will serve you well. * **Companies that need hundreds of pre-built integrations today.** Our ecosystem is growing fast, but it's not yet as broad as Salesforce or HubSpot. If you're comfortable building what's missing, you'll love it. If not, give us another year. * **Organizations where tools are chosen in boardrooms, not by the people using them.** We don't do steak dinners and executive briefings. We win with teams that have the authority to pick their own tools. Set up Twenty in under 5 minutes — cloud or self-hosted. # Key Features Source: https://docs.twenty.com/getting-started/key-features A tour of everything Twenty can do — from custom data models to AI-powered automation. Twenty is a full-featured CRM platform. Here's what you can build with it. Custom Data Model Define the exact data structure your business needs.
Create custom objects, add custom fields with 20+ field types, and build relationships between any objects. Views & Pipelines Switch between table views, kanban boards, and calendar views.
Filter with AND/OR logic, sort by multiple fields, group records, and save custom views. Workflows & Automation Automate any business process without writing code.
Trigger workflows on record changes, schedules, manual actions, or incoming webhooks. Calendar & Email Sync Connect your Google Workspace or Microsoft 365 account.
Emails and calendar events automatically appear on the relevant CRM records. AI AI agents that work autonomously within your CRM — answering questions, enriching records, and executing multi-step tasks within your permission model. Dashboards & Reporting Build custom dashboards with real-time widgets.
Track pipeline metrics, team performance, and business KPIs with configurable charts and filters. Permissions & Access Control Role-based access control at every level — objects, fields, and individual records.
Configure SSO with SAML or OIDC. Audit logs track who did what. API & Extensibility A developer-first API that adapts to your custom data model.
Both GraphQL and REST endpoints, with auto-generated documentation per workspace. Data Import & Export Import data from CSV files or via API.
Field mapping, duplicate detection, and error handling built in. Export your data anytime — no lock-in. Self-Hosting Run Twenty on your own infrastructure with a single Docker Compose command.
Full control over your data, updates on your schedule. # Quickstart Source: https://docs.twenty.com/getting-started/quickstart Get Twenty up and running in under 5 minutes — on the cloud or self-hosted. ## Signup Go to [app.twenty.com](https://app.twenty.com) and sign up with Google, Microsoft, or email. Pick **30 days** (with card) or **7 days** (without card). Both include full access — unlimited contacts, email integration, custom objects, API. You can change plan or billing interval anytime. After payment confirmation via Stripe, you'll set up your workspace name and user profile. You can cancel anytime. ## Configure your workspace Once you're in, three steps to make Twenty yours: ### 1. Connect your mailbox Go to **Settings → Accounts** and connect your Google or Microsoft account. Twenty will import your emails and calendar events, and auto-create contacts from interactions. Using another provider? You can add mailboxes via SMTP or calendars via CalDAV from the same page. Start here — connecting a mailbox gives your team immediate value with real data before you customize anything else. ### 2. Shape your data model Go to **Settings → Data Model** to create custom objects and fields. A few things to know: * Custom objects and fields are **unlimited on all plans** — no upsell. * **People, Companies, and Opportunities** are the objects that show synced emails and meetings. Use them as your base and add fields to categorize (e.g., a `Person Type` field) rather than creating separate objects that won't have email history. * Two People can't share the same email. Two Companies can't share the same domain. * You can deactivate standard fields/objects you don't need, and hide fields from views without deleting them. [Data Model reference →](/user-guide/data-model/overview) ### 3. Import your data Use the Command Menu (`Cmd+K` / `Ctrl+K`) to import People, Companies, Opportunities, or any custom object via CSV. Download the sample file first to see the expected format. Limit files to 10k records and deduplicate emails/domains before importing. [Data Migration guide →](/user-guide/data-migration/overview) ## Next steps Sidebar, views, command menu, side panel. Automate your business processes. Table, kanban, calendar — filter and sort your data. Schema-per-tenant REST and GraphQL. # AI Agents Source: https://docs.twenty.com/user-guide/ai/capabilities/ai-agents Integrate AI capabilities directly into your automation workflows. ## Overview Integrate AI capabilities directly into your automation workflows for intelligent data processing and decision-making. ## Capabilities | Feature | Description | | - | - | | **AI actions** | Add AI-powered steps to any workflow | | **Data enrichment** | Automatically enhance records with external data | | **Classification** | Categorize records based on content analysis | | **Summarization** | Generate summaries from text fields | | **Custom prompts** | Define exactly how AI processes your data | ## Use Cases * **Lead scoring**: Automatically score and prioritize inbound leads * **Data cleanup**: Standardize company names and contact information * **Email drafts**: Generate follow-up emails based on meeting notes * **Record routing**: Assign records to the right team member based on content ## Related * [Workflows Overview](/user-guide/workflows/overview) — automation basics * [AI Permissions](/user-guide/ai/capabilities/permissions-access-control) — access control for AI agents # AI Chatbot Source: https://docs.twenty.com/user-guide/ai/capabilities/ai-chatbot An intelligent assistant that helps you interact with your CRM data using natural language. ## Overview Ask questions in natural language and the assistant retrieves and explains your CRM data for you. ## Capabilities | Feature | Description | | - | - | | **Natural language queries** | Ask questions in plain English instead of building filters | | **Full data access** | Query records, relationships, and metrics across your workspace | | **Page context** | Reference "this company" or "this opportunity" based on your current view | | **Conversational** | Follow-up questions maintain context from previous queries | ## Example Interactions ### Finding Records * "Show me all opportunities over \$50,000" * "Find contacts I haven't emailed in 2 weeks" * "List companies in the healthcare industry" ### Getting Insights * "What's my total pipeline value?" * "How many deals closed last month?" * "Which stage has the most stuck opportunities?" ### Using Page Context * "Summarize my interactions with this person" (on a contact page) * "What opportunities are linked to this company?" (on a company page) * "When was this deal last updated?" (on an opportunity page) # Permissions & Access Control Source: https://docs.twenty.com/user-guide/ai/capabilities/permissions-access-control Control what AI agents can access and modify in your workspace. ## Overview AI agents respect your existing permission structure. This is particularly important for teams who want to control exactly what automated AI processes can access or modify in their workspace. ## Assign a Role to an AI Agent 1. Go to **Settings → Members → Roles** 2. Click on the role you want to assign 3. Open the **Assignment** tab 4. Under **AI Agents**, click **+ Assign to AI agent** 5. Select the AI agent from the list 6. Confirm the assignment ## Why Assign Roles to AI Agents? | Benefit | Description | | - | - | | **Security** | Limit what data AI agents can access or modify | | **Compliance** | Ensure AI only processes the data it needs | | **Control** | Prevent unintended actions from AI automations | | **Auditability** | Track which actions were performed by which agent | For AI agents running within workflows, role assignment ensures the agent cannot access or modify data outside its intended scope—even if the workflow has broader permissions. ## Related * [Permissions](/user-guide/permissions-access/capabilities/permissions) — detailed information on creating and managing roles * [AI Agents](/user-guide/ai/capabilities/ai-agents) — AI capabilities in workflows # AI FAQ Source: https://docs.twenty.com/user-guide/ai/how-tos/ai-faq Frequently asked questions about AI features in Twenty. Two main capabilities of AI are: 1. **AI Chatbot**: A context-aware assistant that can access your Twenty data and help you with queries 2. **AI Agents in Workflows**: Intelligent automation that can process data, make decisions, and execute tasks within your workflows AI agents operate under the permission system. You can assign specific roles to AI agents under **Settings → Members → Roles**, giving you full control over what data they can access and what actions they can perform. AI actions consume workflow credits based on the complexity of the task and the AI model used. On cloud, the models run on Twenty's own provider accounts: you choose which ones your workspace uses under **Settings → AI**, and there is no way to plug in your own API key. On a self-hosted instance, the built-in providers (OpenAI, Anthropic, Google, Mistral, xAI) work on every plan, Free included. Set the matching API key (`OPENAI_API_KEY`, `ANTHROPIC_API_KEY`, `GOOGLE_API_KEY`, `MISTRAL_API_KEY`, `XAI_API_KEY`) in **Settings → Admin Panel → Configuration Variables**, or in your `.env` followed by a server restart. The models then appear under **Settings → Admin Panel → AI**. Custom providers (custom endpoints, private gateways, OpenAI-compatible or local models, extra regions), added under **Settings → Admin Panel → AI → Custom Providers**, are currently complimentary up to 25 seats. Above that, an Organization plan is required. The AI section of the admin panel states where your instance stands. By default, the Roles list is filtered to roles assignable to workspace members. If a role is assignable only to AI agents, you need to change the filter to include AI-agent roles. # AI Source: https://docs.twenty.com/user-guide/ai/overview AI-powered features in Twenty.

## Features Currently, Twenty offers: ### 1. AI Chatbot A conversational assistant that understands your context and has access to all your Twenty data. **Key capabilities:** * **Full data access**: Query any record, relationship, or metric in your workspace * **Page context awareness**: Reference "this company" or "this opportunity" based on where you are in Twenty * **Natural language**: Ask questions and get answers without navigating menus **Example prompts:** * "What opportunities are closing this month?" * "Which deals have been in Negotiation for more than 30 days?" * "Summarize my interactions with this person" ### 2. AI Agents in Workflows Extend your workflows with AI-powered actions and autonomous agents. **Key capabilities:** * **AI actions**: Use AI to enrich data, classify records, generate summaries, and more * **Autonomous agents**: Let agents execute multi-step tasks within a workflow * **Custom prompts**: Define exactly how AI should process your data **Use cases:** * Automatically categorize inbound leads * Enrich company data from public sources * Generate follow-up email drafts based on meeting notes * Score opportunities based on engagement patterns ## Permissions and Access Control AI agents are managed through the existing permissions system: 1. Go to **Settings → Members → Roles** 2. Configure which data each AI agent can access 3. Set read/write permissions per object This ensures AI agents respect your data governance policies and only access what they need. * Follow our [GitHub](https://github.com/twentyhq/twenty) for development updates * Join our [Discord](https://discord.gg/UfGNZJfAG6) to share feedback and feature requests # Calendar Source: https://docs.twenty.com/user-guide/calendar-emails/capabilities/calendar Understanding calendar integration features in Twenty. **Note**: To connect your calendar and configure sync settings, visit [Email & Calendar Setup](/user-guide/calendar-emails/overview). ## How Calendar Integration Works Twenty automatically syncs your calendar events and links them to the relevant CRM records, giving you a complete view of your meeting history with contacts and companies. ## Calendar Tab Next to the Emails tab on records, you'll find a `Calendar` tab that contains the history of meetings scheduled with the record. ### Available For * **People**: View all meetings scheduled with a specific contact * **Companies**: See all meetings related to a company and its employees * **Opportunities**: Access meeting history related to the company linked to the opportunity ### Viewing Meeting History 1. **Navigate to a Record**: Go to any Person, Company, or Opportunity record 2. **Select the Calendar Tab**: Click on the `Calendar` tab next to the Emails tab 3. **Browse Meeting History**: View all scheduled meetings and their details 4. **Access Meeting Context**: See meeting participants, times, and related information ## Visibility Settings Calendar data follows the same visibility settings as emails, ensuring consistent privacy controls across both communication channels. ## What Gets Synced * **External Meetings**: All meetings with contacts outside your organization * **Automatic Linking**: Meetings connect to existing People and Company records based on attendee email addresses * **Meeting Details**: Subject, time, duration, and participants * **Updates**: New calendar events sync automatically ## What Doesn't Get Synced * **Internal Meetings**: Meetings with only colleagues (same domain) remain private * **Private Events**: Events marked as private in your calendar # Mailbox Source: https://docs.twenty.com/user-guide/calendar-emails/capabilities/mailbox Understanding email integration features in Twenty. **Note**: To connect your email accounts and configure sync settings, visit [Email & Calendar Setup](/user-guide/calendar-emails/overview). ## How Email Integration Works Twenty automatically links emails from your connected mailboxes to the relevant CRM records, keeping all communication history in one place. ### Objects Where Emails Can Be Found Email conversations appear in three main objects: * **People**: View all emails exchanged with a specific contact * **Companies**: See all emails related to a company and its employees * **Opportunities**: Access email threads related to the company linked to the opportunity. Email threads from individual people on the opportunity are not shown yet. ### Viewing Email Threads 1. **Navigate to a Record**: Go to any Person, Company, or Opportunity record 2. **Select the Emails Tab**: Click on the `Emails` tab to view synced emails 3. **Open an Email Thread**: Click on any email to open and read the full conversation 4. **Browse History**: Scroll through the complete email history with that contact ## What You'll See ### Email Thread View When you open an email thread, you can: * **Read Full Conversations**: See the complete email exchange * **View Participants**: See all people involved in the email thread * **Check Timestamps**: Know exactly when each email was sent * **Access Context**: Understand the full communication history ### Email Visibility Depending on your mailbox settings, you might see: * **Full Content**: Complete email text and details * **Subject + Metadata**: Subject line, sender, recipient, and timestamp * **Metadata Only**: Basic information without email content ## Email Sync Behavior ### Sync Rate Twenty imports emails at approximately **400 messages per minute**. This rate is currently limited by Gmail API rate limiting (and applies similarly to other providers). For reference: * 1,000 emails → \~2.5 minutes * 10,000 emails → \~25 minutes * 50,000 emails → \~2 hours ### What Gets Synced * **External Emails**: All emails with contacts outside your organization * **Automatic Linking**: Emails connect to existing People and Company records * **Multiple Addresses**: Emails from any address link to the same contact record * **Updates**: New emails appear immediately ### What Doesn't Get Synced * **Internal Emails**: By default, emails between colleagues (same domain) remain private (configured in Settings → General → Security) * **Group Emails**: Distribution lists and group emails are excluded * **Excluded Folders**: Folders you've chosen not to sync (configured under Settings → Accounts → Email) ### Internal Emails Choose if internal emails are synchronized in Twenty: 1. Go to **Settings → General → Security** 2. Toggle **Sync Internal Emails** on/off ### Selective Folder Sync Control which email folders sync with Twenty: 1. Go to **Settings → Accounts** and select your connected email account 2. Configure folders under the Email section 3. Choose specific folders to include or exclude (Inbox, Sent, Archive, custom folders) ## Troubleshooting Email Sync ### Common Sync Issues * **Sync Delays**: Emails appear immediately, but initial imports take longer * **Missing Emails**: Check if: * Folders are excluded in Message Folder settings * Contact auto-creation is disabled (emails need existing Twenty records) * Email is from colleagues (same domain) or group lists * Mailbox is still completing initial sync ### Email Limitations * **System Folders**: Some email folders may not be available for sync * **Aliases**: Only true mailboxes can be connected (not email aliases) # Can I Book Meetings from Twenty? Source: https://docs.twenty.com/user-guide/calendar-emails/how-tos/can-i-book-meetings-from-twenty Information about booking meetings directly from Twenty. ## Current Status Yes. Twenty's calendar integration syncs and displays your existing events, and you can also create a new event straight from a record page. The event is created on your connected calendar, not just inside Twenty. ## How to create a meeting from Twenty Prerequisite: a connected Google, Microsoft or CalDAV account with calendar sync enabled 1. Open a Person, Company or Opportunity record 2. Click the **Create calendar event** action 3. Pick the calendar account to create the event on 4. Add guests, a title, a location and a description 5. Set the start and end (or toggle **All day**) and check the time zone 6. Toggle **Invitations** to email guests, and **Video call** to add a meeting link 7. Click **Create event** The record you started from is linked to the event automatically, so the meeting shows up on its timeline. The action is hidden if your role doesn't have the "Create calendar event" permission, and disabled if the record has no email address to invite. ## Scheduling Meetings via Workflows You can also create events automatically with workflows: 1. Create a new workflow 2. Select any trigger depending on your needs 3. Add the **Create Calendar Event** node 4. Configure all necessary data 5. Activate the workflow ## What You Can Do * **Create events** on your connected calendar from a record * **View meeting history** on People, Companies, and Opportunities records * **See upcoming meetings** with contacts in your CRM * **Track meeting context** alongside email communications * **Auto-create contacts** from meeting participants # Can I Send Emails from Twenty? Source: https://docs.twenty.com/user-guide/calendar-emails/how-tos/can-i-send-emails-from-twenty Information about sending emails directly from Twenty. ## Current Status Twenty's email integration is designed to **sync and display** your email history as well as compose and send emails. When you view an email thread on a record page and click **Reply**, you're able to directly compose and send an email. ## How to send a message from Twenty Prerequisite: a connected mail account with the ability to send emails 1. Open the Command menu with the **Ctrl+K** or **Cmd+K** shortcut 2. Click the "Compose email" option 3. Choose recipients, add subject, body and attachments to your email 4. Click the "Send" button to send the email ## What You Can Do Today * **View email history** on People, Companies, and Opportunities records * **Read full email threads** with contacts in your CRM * **Track communication context** alongside calendar events * **Auto-create contacts** from email interactions * **Reply via redirect** — click Reply to jump to your mailbox ## Sending Emails via Workflows You **can send emails automatically using workflows**. This is useful for: * Automated follow-ups * Notifications to contacts * Triggered communications based on record changes Emails sent via workflows go through your connected mailbox account. → Learn about the [Send Email action](/user-guide/workflows/capabilities/workflow-actions#send-email) ## Email Sequences and Newsletters For email sequences and newsletters, we recommend using workflows to connect Twenty to a dedicated email marketing tool. Mass emails should not be sent directly from your mailbox to protect your domain reputation. Use a dedicated tool for bulk communications. → See [How to send emails from workflows](/user-guide/workflows/capabilities/send-emails-from-workflows) for setup instructions ## Future Plans Native email composition from within Twenty is on our roadmap. Join our [GitHub discussions](https://github.com/twentyhq/twenty/discussions) to share your use case and help prioritize this feature. # Can I Track Email Activity on All Objects? Source: https://docs.twenty.com/user-guide/calendar-emails/how-tos/can-i-track-email-activity-on-all-objects Understanding email activity tracking across different objects. ## Supported Objects Email activity is currently available on **three standard objects**: | Object | What You See | | - | - | | **People** | All emails exchanged with that specific contact | | **Companies** | All emails with anyone from that company (based on email domain) | | **Opportunities** | Emails related to the company linked to the opportunity | ## Why Only These Objects? People, Companies, and Opportunities are the core relationship objects where email context adds the most value. Email threads are automatically linked based on: * **Email address** → matched to People records * **Email domain** → matched to Company records * **Company relation** → linked to Opportunities ## Custom Objects **Email tracking is not available on custom objects** at this time. If you need email context on a custom object, consider: * Using a relation field to link your custom object to People or Companies * Viewing email history on the linked People/Company record ## Future Plans Extending email visibility to custom objects is being considered. Share your use case on our [GitHub discussions](https://github.com/twentyhq/twenty/discussions) to help prioritize this feature. # Connect Several Mailboxes per User Source: https://docs.twenty.com/user-guide/calendar-emails/how-tos/connect-several-mailboxes-per-user Connect multiple email accounts for a single user. ## Overview Twenty supports **unlimited email accounts per user**. This is useful if you manage multiple inboxes, such as: * Personal work email + shared team inbox * Multiple client-facing email addresses * Different email accounts for different roles ## How to Add Multiple Mailboxes 1. Go to **Settings → Accounts** 2. Click **Add account** 3. Connect an additional Google or Microsoft account, or any other mail provider supporting IMAP/SMTP protocols 4. Configure sync settings for this mailbox 5. Repeat for each mailbox you want to connect ## Managing Multiple Accounts Each connected mailbox has its own settings: * **Email visibility**: Choose what teammates can see * **Contact auto-creation**: Enable/disable per mailbox * **Folder selection**: Choose which folders to sync ## How Emails Appear Emails from all your connected mailboxes are synced to Twenty and appear on: * **People records**: Based on the contact's email address * **Company records**: Based on the email domain * **Opportunities**: Based on the linked company Each email shows which mailbox it was sent from or received in, so you can track which account was used for each communication. ## Important Notes Only true mailboxes can be connected. Email aliases that forward to another mailbox cannot be connected separately — they'll sync through the main mailbox. # Forward a Shared Inbox from Any Email Provider Source: https://docs.twenty.com/user-guide/calendar-emails/how-tos/forward-a-shared-inbox-from-any-mail-provider Point a shared inbox at a Twenty email channel, whatever mail provider you use. Twenty receives shared inbox mail by having your provider send a copy of every incoming message to a private address that Twenty generates for you. Once that is in place, the inbox appears in your workspace. Microsoft 365 and Google Workspace each have their own guide: * [Microsoft 365](/user-guide/calendar-emails/how-tos/forward-a-shared-inbox-from-microsoft-365) * [Google Workspace](/user-guide/calendar-emails/how-tos/forward-a-shared-inbox-from-google-workspace) This page covers every other provider. ## Part 1: Create the channel in Twenty 1. Go to **Settings → Communication**. 2. Click **Add email channel**. 3. In **Source Email Address**, type the shared address you want to receive mail at, for example `contact@yourcompany.com`. 4. In **Display Name**, type the name recipients see. 5. Click **Save**. 6. Twenty now shows a **Forwarding address**. It ends in `@inbound.twenty.com`. Click **Copy**. Each channel gets its own forwarding address. Never point two mailboxes at the same one, or their mail will land in the same place. ## Part 2: Choose the right kind of forwarding Most providers offer more than one way to pass mail on, and only one of them works here. Twenty reads the `From` header of each message it receives to determine who wrote it. That is how a message is linked to the right person and company. * **Automatic forwarding on the mail server** leaves the original sender in place. Your customer remains the sender, the message is linked to their record, and replies go back to them. Some providers call this **Redirect**, others call it **Forwarding**. This is the option to use. * **Forwarding as an attachment**, or any rule that composes a new message, replaces the sender with your own address. Every conversation then appears to come from you, and no message is matched to a contact. Use the automatic forwarding setting in your mail account or on your mail server. Do not use a rule that resends the message as a new email. Also avoid rules that strip attachments or convert messages to plain text. Twenty stores each message exactly as it arrives. Where the option exists, choose the one that **keeps a copy** in the original mailbox, so your team can continue to use the inbox as before. ## Part 3: Find your provider Follow your provider's instructions, using the forwarding address you copied in Part 1 as the destination. | Provider | Their guide | | - | - | | Amazon SES | [Forward incoming email to an external destination](https://aws.amazon.com/blogs/messaging-and-targeting/forward-incoming-email-to-an-external-destination/) | | Amazon WorkMail | [Email rules](https://docs.aws.amazon.com/workmail/latest/userguide/email-rules.html) | | Bluehost | [Create account and domain forwarders](https://www.bluehost.com/help/article/create-account-and-domain-forwarders) | | cPanel | [Forwarders](https://docs.cpanel.net/cpanel/email/forwarders/) | | DreamHost | [Add a forward-only email address](https://help.dreamhost.com/hc/en-us/articles/215724207-Add-a-forward-only-email-address) | | Exchange (self-hosted) | [Configure email forwarding for a mailbox](https://learn.microsoft.com/en-us/exchange/recipients/user-mailboxes/email-forwarding) | | GoDaddy | [Forward incoming email to another address](https://www.godaddy.com/help/forward-incoming-email-to-another-email-address-32282) | | iCloud Mail | [Forward email on iCloud.com](https://support.apple.com/en-us/102376) | | Namecheap | [Set up free email forwarding](https://www.namecheap.com/support/knowledgebase/article.aspx/308/2214/how-to-set-up-free-email-forwarding) | | OVHcloud | [Email redirection](https://help.ovhcloud.com/csm/en-emails-redirection) | | Rackspace | [Set up Rackspace email forwarding](https://docs.rackspace.com/docs/set-up-rackspace-email-forwarding) | | Zoho Mail | [Email forwarding](https://www.zoho.com/mail/help/email-forwarding.html) | If your provider is not listed, you can still connect it. In almost every mail product the setting appears under a name such as **Forwarding**, **Redirect**, **Forwarders**, **Aliases**, **Rules** or **Filters**, in either the mailbox settings or the domain settings. ## Part 4: Test it Send an email from an outside address (a personal Gmail works) to `contact@yourcompany.com`. It should appear in Twenty within a minute or two. ## Troubleshooting Compare the forwarding address character for character with the one in Twenty. A single wrong character means the mail goes nowhere and is silently dropped. The rule is rebuilding the message rather than passing it along, so your address ends up in the `From` header. Switch to your provider's plain forwarding or redirect setting, and turn off any option that forwards as an attachment. Your provider blocks automatic forwarding to outside domains. Look for a security or anti-spam setting that allows external forwarding, and enable it for this mailbox only. The rule moves messages on rather than copying them. Change it to keep a copy, or add a second rule that delivers to the inbox. Receiving and sending are separate. Sending requires your domain to be verified under the channel's **Sending domain** section, which means adding the DNS records Twenty lists there. # Forward a Shared Inbox from Google Workspace Source: https://docs.twenty.com/user-guide/calendar-emails/how-tos/forward-a-shared-inbox-from-google-workspace Send mail from a Google Group into a Twenty email channel. An email channel gives your workspace a shared address, like `sales@yourcompany.com`. Mail sent to that address has to reach Twenty somehow. On Google Workspace that address is almost always a **Google Group**. You connect it by adding Twenty's private forwarding address as a member of the group. Every message the group receives is then copied to Twenty, and your team continues to receive it as before. This applies to new mail only. Twenty will not see messages the group received before you set this up. ## Before you start You need two things: * **Access**: you must own the group, or be a Super Admin or Groups Admin in Google Workspace. * **A group that accepts outside addresses**: Twenty's forwarding address is external, so the group has to accept external members and accept mail from outside your company. Part 2 covers both. ## Part 1: Create the channel in Twenty 1. Go to **Settings → Communication**. 2. Click **Add email channel**. 3. In **Source Email Address**, type the group address, for example `sales@yourcompany.com`. 4. In **Display Name**, type the name recipients see. 5. Click **Save**. 6. Twenty now shows a **Forwarding address**. It looks like `ch_2cd282d193b5@inbound.twenty.com`. Click **Copy**. Each channel gets its own forwarding address. Never point two groups at the same one, or their mail will land in the same place. ## Part 2: Check the group's settings Two settings decide whether this works at all. Set them correctly before you continue. 1. Open [Google Groups](https://groups.google.com) and click your group. 2. Click **Group settings** in the left sidebar. 3. Find **External members** and turn **Allow external members** on. Google turns this off for the whole organization by default, so expect it to be locked the first time. If you see the notice shown above, only a Workspace admin can unlock it, by allowing group owners to add external members across the organization. Ask them, then return here. 4. Scroll down to **Who can post** and drag the slider all the way to the right, onto the globe. That is **Anyone on the web**. Without this, mail from outside your company never reaches the group, so it never reaches Twenty either. This is also blocked across the organization by default, and again only an admin can change it. 5. Click **Save changes**. If the group carries Google's **Security** label, stop here. Google does not allow non-Google accounts in a security group, and the label is permanent once applied. Create a new group without it. ## Part 3: Add Twenty to the group 1. Click **Members** in the left sidebar. 2. Click **Add members**. 3. Paste the forwarding address you copied from Twenty into **Group members**. 4. Leave **Subscription** on **Each email**. This is what makes Google send every message through. 5. Leave **Directly add members** ticked, so Google adds the address rather than sending an invitation that cannot be accepted. 6. Click **Add members**. That completes the setup. Twenty is now a member of the group like any other. ## If you do not have a group yet 1. In [Google Groups](https://groups.google.com), click **Create group**. 2. Fill in the **Group name** and the **Group email** prefix. 3. Click **Next** twice, then **Create group**. 4. Now follow Part 2 and Part 3. ## Part 4: Test it Send an email from an outside address (a personal Gmail works) to `sales@yourcompany.com`. It should appear in Twenty within a minute or two. ## Troubleshooting The group does not accept external members. Return to Part 2, step 3. If the setting is locked, only a Workspace admin can unlock it. Open the member in the group and check its subscription is **Each email**, not **No email**, **Digest** or **Abridged**. **Who can post** is not set to **Anyone on the web**. See Part 2, step 4. Receiving and sending are separate. Sending requires your domain to be verified under the channel's **Sending domain** section, which means adding the DNS records Twenty lists there. Using a different provider? See [Microsoft 365](/user-guide/calendar-emails/how-tos/forward-a-shared-inbox-from-microsoft-365) or [any other mail provider](/user-guide/calendar-emails/how-tos/forward-a-shared-inbox-from-any-mail-provider). # Forward a Shared Inbox from Microsoft 365 Source: https://docs.twenty.com/user-guide/calendar-emails/how-tos/forward-a-shared-inbox-from-microsoft-365 Send mail from a Microsoft 365 shared mailbox into a Twenty email channel. An email channel gives your workspace a shared address, like `contact@yourcompany.com`. Mail sent to that address has to reach Twenty somehow. You do that by forwarding the mailbox to the private address Twenty gives you. Setup has two halves: create the channel in Twenty, then point Microsoft at it. ## Part 1: Create the channel in Twenty 1. Go to **Settings → Communication**. 2. Click **Add email channel**. 3. In **Source Email Address**, type the shared address you want to receive mail at, for example `contact@yourcompany.com`. 4. In **Display Name**, type the name recipients see, for example `Twenty Contact`. 5. Click **Save**. 6. Twenty now shows a **Forwarding address**. It looks like `ch_2cd282d193b5@inbound.twenty.com`. Click **Copy**. Each channel gets its own forwarding address. Never point two mailboxes at the same one, or their mail will land in the same place. ## Part 2: Create the shared mailbox Skip this part if `contact@yourcompany.com` already exists in Microsoft 365. 1. Open the [Exchange admin center](https://admin.cloud.microsoft/exchange). 2. Go to **Recipients → Mailboxes**. 3. Click **Add a shared mailbox**. 4. Fill in the **Display name**. 5. Fill in the **Email address** and pick your domain. 6. Click **Create**. It takes a minute to appear in the list. ## Part 3: Forward the mailbox to Twenty 1. In **Recipients → Mailboxes**, click the mailbox to open it. 2. Click **Email forwarding**. 3. Turn **Forward all emails sent to this mailbox** on. 4. Choose **Forward to an external email address** and paste the forwarding address you copied from Twenty. 5. Tick **Deliver message to both forwarding address and mailbox** so your team keeps a copy in Outlook. 6. Click **Save**. Microsoft says changes can take up to 5 minutes to apply. ## Part 4: Allow forwarding to external addresses This step is easy to miss. Without it, no mail reaches Twenty. By default, Microsoft 365 blocks automatic forwarding to addresses outside your organization. The mail is rejected and the original sender receives a bounce that reads: ``` 5.7.520 Access denied, Your organization does not allow external forwarding. ``` To allow it: 1. Open the [Microsoft Defender portal](https://security.microsoft.com). 2. Go to **Email & collaboration → Policies & rules → Threat policies → Anti-spam**. 3. Open your **Anti-spam outbound policy**, or create a new one that applies only to your shared mailboxes. 4. Click **Edit protection settings**. 5. Set **Automatic forwarding rules** to **On - Forwarding is enabled**. 6. Save. Turning this on for your whole tenant lets any compromised account forward mail out. Create a policy scoped to only the shared mailboxes you are connecting, rather than editing the default one. ## Part 5: Test it Send an email from an outside address (a personal Gmail works) to `contact@yourcompany.com`. It should appear in Twenty within a minute or two. ## Troubleshooting External forwarding is still blocked. Repeat Part 4 and confirm the policy you edited applies to this mailbox. Compare the forwarding address in Exchange character for character with the one in Twenty. A single wrong character means the mail is delivered nowhere useful and silently dropped. **Deliver message to both forwarding address and mailbox** was left unticked. Tick it and save. Receiving and sending are separate. Sending requires your domain to be verified under the channel's **Sending domain** section, which means adding the DNS records Twenty lists there. Using a different provider? See [Google Workspace](/user-guide/calendar-emails/how-tos/forward-a-shared-inbox-from-google-workspace) or [any other mail provider](/user-guide/calendar-emails/how-tos/forward-a-shared-inbox-from-any-mail-provider). # I Don't See Emails on Records Source: https://docs.twenty.com/user-guide/calendar-emails/how-tos/i-dont-see-emails-on-records Troubleshooting missing emails on records. ## Common Reasons ### 1. Initial Sync Still in Progress Email sync takes time, especially for large mailboxes. Twenty imports emails at approximately **400 messages per minute** (limited by Gmail API rate limiting). * **Calendar sync**: Completes in minutes * **Email sync**: Depends on mailbox size (e.g., 10,000 emails ≈ 25 minutes, 50,000 emails ≈ 2 hours) **Solution**: Wait for the initial import to complete. You can estimate timing based on your mailbox size. ### 2. Contact Doesn't Exist in Twenty Emails only appear on existing People records. If the contact wasn't created yet: * Enable **Contact Auto-Creation** in your mailbox settings * Or manually create the Person record first **Solution**: Go to **Settings → Accounts**, select your mailbox, and enable contact auto-creation. ### 3. Internal Emails Are Excluded Emails between colleagues (same email domain) are never synced to maintain privacy. **Solution**: This is expected behavior. Only external emails are synced. ### 4. Email Is from a Group or Distribution List Group emails and distribution lists are excluded from sync. **Solution**: This is expected behavior. ### 5. Folder Not Selected for Sync If you're using the Message Folder feature, some folders might be excluded. **Solution**: Go to **Settings → Accounts**, select your mailbox, and check folder sync settings. ### 6. Wrong Email Address on Record The Person record might have a different email address than the one used in the email. **Solution**: Add the correct email address to the Person record. ## Still Not Working? 1. Try disconnecting and reconnecting your mailbox 2. Contact support if issues persist # Limit Emails Imported Source: https://docs.twenty.com/user-guide/calendar-emails/how-tos/limit-emails-imported Control which emails are imported into Twenty. ## Overview By default, Twenty syncs all external emails from your connected mailbox. You can limit what gets imported using **folder selection** and **visibility settings**. ## Method 1: Folder Selection (Recommended) Control which email folders sync with Twenty: 1. Go to **Settings → Accounts** 2. Select your connected email account 3. Choose which folders to sync: | Folder | Description | | - | - | | **Inbox** | Primary incoming emails | | **Sent** | Outgoing emails you've sent | | **Archive** | Archived messages | | **Custom Folders** | Any specific folders you want | 4. Exclude folders you don't want synced (Spam, Trash, personal folders) This gives you precise control over which emails appear in your CRM without syncing everything. ## Method 2: Contact Auto-Creation Settings Control when contacts are created from emails: 1. Go to **Settings → Accounts** 2. Select your connected mailbox 3. Choose an option: * **Deactivated**: No contacts created, but emails still sync to existing contacts * **Sent & Received**: Create contacts from all external emails * **Sent Only**: Only create contacts from emails you send ## Internal Emails Messages between colleagues (same domain) can be synchronized in Twenty: 1. Go to **Settings → General → Security** 2. Toggle **Sync Internal Emails** on/off By default, this option is turned off. ## What's Always Excluded These emails are never synced, regardless of settings: * **Group emails**: Distribution lists and group messages * **Spam/Trash**: System folders are typically excluded ## Important Note We don't provide a CC email address for selective syncing yet. Use the folder selection feature above to achieve the same level of control. # Calendar & Emails Source: https://docs.twenty.com/user-guide/calendar-emails/overview Connect your email and calendar accounts to Twenty. ## Connection Options ### Google Account (Gmail & Google Calendar) 1. Go to **Settings → Accounts** 2. Click **Add account** 3. Select **Continue with Google** 4. Authorize Twenty to access your Gmail and Google Calendar 5. Configure email sync settings (visibility, auto-creation) → click **Next** 6. Configure calendar sync settings (visibility, auto-creation) → click **Add Account** 7. Your emails and calendar events will start syncing automatically ### Microsoft Account (Outlook & Microsoft Calendar) 1. Go to **Settings → Accounts** 2. Click **Add account** 3. Select **Continue with Microsoft** 4. Authorize Twenty to access your Outlook and Microsoft Calendar 5. Configure email sync settings (visibility, auto-creation) → click **Next** 6. Configure calendar sync settings (visibility, auto-creation) → click **Add Account** 7. Your emails and calendar events will start syncing automatically ### IMAP/SMTP/CalDAV Setup (Other Providers) For other email and calendar providers: 1. Go to **Settings → Accounts** 2. Configure IMAP settings to sync incoming email and SMTP settings to send email 3. Configure CalDAV settings for calendar 4. Test the connection **Self-hosting on an internal network**: By default, Twenty refuses outbound connections to private/internal IP addresses (SSRF protection). If your mail, calendar or identity provider server runs on a local/private IP (e.g. an on-premise server on a LAN), connections to it will be blocked. To allow them, list the hostnames or IP literals in the following environment variable on the server: ``` OUTBOUND_HTTP_ALLOWED_INTERNAL_HOSTS=mail.internal,keycloak,192.168.1.10 ``` Entries are matched on the hostname only (`keycloak`, not `http://keycloak:8080/realms/…`), without wildcards. Every other outbound request (HTTP workflow actions, webhooks, SSO and IMAP/SMTP/CalDAV connections) stays protected, and even an allowed host can never reach the cloud metadata address range. Set it to `*` to disable the protection entirely, which is only appropriate on trusted, isolated networks. If you previously set `OUTBOUND_HTTP_SAFE_MODE_ENABLED=false`, remove it: while it is set, the protection stays fully off and the list is ignored. ### Multiple Mailboxes * **Unlimited Accounts**: Connect multiple email accounts per user * **Account Management**: Switch between different mailboxes * **Sync Settings**: Configure different settings per mailbox Only true mailboxes can be connected (e.g., [support@domain.com](mailto:support@domain.com) with its own inbox). Email aliases that forward to another mailbox cannot be connected to Twenty. ## Email Configuration ### Message Visibility Choose different levels of visibility for your emails: * **Metadata Only**: Share only basic information (sender, recipient, date, time) * **Subject and Metadata**: Share subject line along with metadata * **All Email Content**: Share entire email content including attachments ### Contact Auto-Creation * **Deactivated**: No automatic contact creation * **For messages sent and received**: Create contacts for all external email interactions * **For messages sent only**: Create contacts only for emails you send * **Note**: By default, internal emails (where all participants share your domain) are not synced to protect privacy When enabled, contacts are automatically linked to their Company records based on their email domain. If the company doesn't exist yet, Twenty creates it for you. **Syncing internal emails**: The "internal emails not synced" behavior is the default, but it can be turned off. The toggle lives in advanced settings: 1. Open **Settings** and enable the **Advanced** toggle at the bottom of the settings page 2. Go to **General → Security** 3. Enable the **Sync Internal Emails** toggle to include emails where all participants share the same domain This is a workspace-wide setting (useful for universities or shared-domain organizations). ### Control which emails get synced with Message Folder Selection Control which email folders sync with Twenty: 1. Go to **Settings → Accounts** and select your connected email account 2. Choose which folders to sync: * **Inbox**: Primary incoming emails * **Sent**: Outgoing emails you've sent * **Custom Folders**: Any specific folders you want to include * **Exclude Folders**: Skip folders like Spam, Trash, or personal folders This gives you precise control over which emails appear in your CRM without syncing everything. **What Gets Synced:** * **External Emails**: All emails with external contacts from selected folders * **Internal Emails**: Not synced by default (same domain emails remain private). Enable the **Advanced** toggle at the bottom of **Settings**, then turn on **Sync Internal Emails** under **General → Security** to include them workspace-wide. * **Attachments**: Coming in H1 2026 **Note**: We don't provide a CC email address for selective syncing. Instead, use the Message Folder feature above to achieve the same level of control over which emails sync with Twenty. ## Calendar Configuration ### Event Visibility Choose what will be visible to other users in your workspace: * **Everything**: The whole event's details will be shared with your team * **Metadata**: Only date and participants will be shared with your team ### Contact Auto-Creation for Meetings * **Yes**: Automatically create contacts for meeting participants not in your CRM * **No**: Only link meetings to existing contacts When enabled, contacts are automatically linked to their Company records based on their email domain. If the company doesn't exist yet, Twenty creates it for you. ### Control which events get synced * **Meeting Import**: Automatically import calendar events * **Contact Linking**: Link meetings to People and Company records **What Gets Synced:** * **Meetings**: Calendar events with external participants * **Contact Linking**: Events automatically linked to CRM records * **Team Events**: Shared calendar visibility ## Sync Frequency **Updates every 5 minutes**: Both email and calendar data sync automatically every 5 minutes after the initial import. **Initial sync timing**: Calendar sync completes quickly (usually within minutes), while email sync takes longer for large mailboxes. Twenty imports emails at approximately **400 messages per minute** (limited by Gmail API rate limiting), so a mailbox with 10,000 emails takes about 25 minutes. Don't worry if you see contacts from calendar events appearing before your email contacts; this is normal behavior. ## Next Steps * [Mailbox capabilities](/user-guide/calendar-emails/capabilities/mailbox) * [Troubleshoot missing emails](/user-guide/calendar-emails/how-tos/i-dont-see-emails-on-records) # Error Handling & Validation Source: https://docs.twenty.com/user-guide/data-migration/capabilities/error-handling Review and fix import errors directly in the UI before confirming. ## Pre-Import Validation After uploading your file and mapping fields, Twenty validates your data **before** importing. This allows you to catch and fix errors without affecting your existing data. ## How It Works 1. **Upload** your CSV file 2. **Map** your columns to Twenty fields 3. **Review** the potential errors highlighted in yellow 4. **Fix errors** directly in the UI 5. **Confirm** the import ## Error Display Rows with issues are highlighted in **yellow**. You can: * **Edit the cell directly** to fix the error * **Remove the row** to skip it entirely This inline editing saves time — no need to go back to your spreadsheet, fix errors, and re-upload. ## Common Error Types ### Duplicate Values **Cause**: A unique field (email, domain) already exists in Twenty or appears twice in your file. **Fix**: * Edit the duplicate value in the import UI * Remove one of the duplicate rows See [Uniqueness Constraints](/user-guide/data-migration/capabilities/uniqueness-constraints) for more details on how uniqueness is enforced. ### Invalid Format **Cause**: Data doesn't match the expected format (e.g., invalid email, wrong date format). **Fix**: Edit the cell to use the correct format. See [Field Mapping](/user-guide/data-migration/capabilities/field-mapping) for the expected format of each field type. ### Missing Required Fields **Cause**: A required field is empty. **Fix**: Enter a value in the required field or remove the row. ### Relation Not Found **Cause**: The referenced record doesn't exist (e.g., a Company domain that wasn't imported). **Fix**: * Import the parent records first * Or correct the reference value See [Import Relations](/user-guide/data-migration/capabilities/import-relations) for the correct import order and how to link records. ## Tips for Fewer Errors 1. **Download the template** to see the expected format prior to importing your file 2. **Clean your data** in the spreadsheet first 3. **Import files in correct order** to import relations (Companies → People → Opportunities) 4. **Test with small batches** before full import 5. **Check for duplicates** before uploading 6. **Limit each file to 10,000 records** # Field Mapping Source: https://docs.twenty.com/user-guide/data-migration/capabilities/field-mapping How field mapping works during data import. ## How Field Mapping Works When you upload a file, Twenty analyzes your columns and attempts to match them to existing fields. ### Automatic Mapping Twenty tries to match columns based on: * Column header names (exact or similar matches) * Data type detection (dates, numbers, emails) * Common field patterns **Quick tip:** Export a few rows from the object you want to import. The exported file will have the exact column names Twenty expects, making automatic mapping seamless during import. ### Manual Mapping Options For each column, you can: * **Map to a field**: Select the matching Twenty field from a dropdown * **Do not map**: Skip the column entirely (data won't be imported) **Fields must exist before import.** The import creates records, not fields. Create custom fields under **Settings → Data Model** before importing. ## Field Type Compatibility All field types available in the Data Model are supported for import. You can also import `id` values to either assign a specific ID to new records or update existing ones. ## Data Format Requirements **Some fields have special syntax.** We recommend downloading the sample file before preparing your import to see the expected syntax for each field type. ### Address Fields Address is a nested field with multiple columns. Some can be left empty. * **Address / Address 1**: Street address line 1 * **Address / Address 2**: Street address line 2 * **Address / City**: City name * **Address / State**: State or province * **Address / Country**: Country name * **Address / Post Code**: Postal/ZIP code ### Array Fields Use the following format: ``` ["value1","value2"] ``` ### Boolean Fields Use `TRUE` or `FALSE` (uppercase) - not `true` or `false` ### Currency Fields Currency is a nested field with two columns that **both must be filled**: * **Amount / Amount**: The numeric value (e.g., `1234.56`) * **Amount / Currency**: The currency code (e.g., `USD`, `EUR`) ### Date Fields Supported formats: * `YYYY-MM-DD` (recommended) * `MM/DD/YYYY` * `DD/MM/YYYY` * ISO 8601 format ### Domain Fields * It is recommended to use the format `https://domain.com` to avoid creating duplicates, as this is the format used for Companies created by the mailbox and calendar synchronizations * A `Domain Label` and `Domain URL` can be filled: best practice is to fill `domain.com` in the label and `https://domain.com` in the url * Domains must be unique within the Companies object * **Domains must be unique within the file to import** ### Email Fields * Must be valid email format * Emails must be unique within the People object * **Emails must be unique within the file to import** * For additional emails: use **Emails / Primary Email** for the main email, and **Emails / Additional Emails** with this format: ``` ["jane@twenty.com","jane.doe@twenty.com"] ``` ### ID Fields Specifying an `id` during import is optional. Twenty auto-generates one if not provided. Use cases for mapping an `id` column: * **Set a specific ID**: Choose the UUID for newly created records * **Update existing records**: Match against existing records to update them instead of creating duplicates. In that case, it is recommended to not map the other unique fields: mapping only one unique field ensures a smoother import. If you provide an `id`, it must be in UUID format (e.g., `c776ee49-f608-4a77-8cc8-6fe96ae1e43f`). ### JSON Fields Use valid JSON format: ``` {"key":"value","key2":"value2"} ``` ### Links Fields Similar to Domain fields: * Fill both the label and URL columns: **Links / Link URL** and **Links / Link Label** * Use full URL format: `https://example.com` * For secondary links, use **Links / Secondary Links** column with this format: ``` [{"url":"https://twenty.com","label":"Twenty"}] ``` ### Multi-Select Fields Use the **API names** (not the display labels) in the following format: ``` ["VALUE1","VALUE2"] ``` See [here](#finding-api-names-for-select-fields) where to find the API names. New select options will not be created automatically by the import. They must be added under **Settings → Data Model** before importing. **Import overwrites; it does not add.** If a record already has `VALUE2` and `VALUE3` selected, and you import `["VALUE1"]`, the record will only have `VALUE1` after import. The previous selections are replaced, not merged. ### Number Fields * Numbers only * Decimals use period: `1234.56` * No thousands separators ### Phone Fields Phone is a nested field with multiple columns that **must be filled** * **Phones / Primary Phone Number**: The phone number (e.g., `4159095555`) * **Phones / Primary Phone Country Code**: Country code (e.g., `US`) * **Phones / Primary Phone Calling Code**: Dialing code (e.g., `+1`) ### Rating Fields Use the API name format: `RATING_1`, `RATING_2`, `RATING_3`, `RATING_4`, `RATING_5` ### Relation Fields Please see our dedicated article: [Import Relations Between Objects](/user-guide/data-migration/capabilities/import-relations) ### Select Fields Use the **API name** of the option (not the display label): ``` VALUE1 ``` See [here](#finding-api-names-for-select-fields) where to find the API names. New select options will not be created automatically by the import. They must be added under **Settings → Data Model** before importing. ### Text Fields * No special formatting required * Leading/trailing spaces are trimmed ## Finding API Names For Select, Multi-Select, and Array fields with predefined options, you must use the **API names**, not the display labels. ### How to Find API Names 1. Go to **Settings → Data Model** 2. Select the object and field 3. Enable **Advanced mode** (toggle at the bottom right of the settings page) 4. View the API name for each option # Supported File Formats Source: https://docs.twenty.com/user-guide/data-migration/capabilities/file-formats File formats supported for data import in Twenty. ## Supported Formats Twenty supports three file formats for import: | Format | Extension | Notes | | - | - | - | | **CSV** | .csv | Recommended, most compatible | | **Excel** | .xlsx | Modern Excel format | | **Excel (Legacy)** | .xls | Older Excel format | ## File Requirements | Requirement | Value | | - | - | | **Encoding** | UTF-8 recommended | | **Record limit** | 10,000 records per file | | **Structure** | First row must contain column headers | | **Content** | One object type per file | ## CSV Best Practices * **Delimiter**: Use comma (`,`) or semicolon (`;`) * **Text qualifier**: Use double quotes (`"`) for text containing commas * **Line endings**: Windows (CRLF) or Unix (LF) both supported * **Empty values**: Leave cells empty, don't use "NULL" or "N/A" ## Excel Best Practices When exporting from Excel: * Remove formulas (export values only) * Delete empty rows at the end * Ensure no merged cells * Use the first sheet only ## Large Datasets For datasets larger than 10,000 records: * Split into multiple files * Or use the [API import](/user-guide/data-migration/how-tos/import-data-via-api) for unlimited records For very large migrations (100,000+ records), the API is significantly faster and more reliable than CSV imports. # Import Relations Between Objects Source: https://docs.twenty.com/user-guide/data-migration/capabilities/import-relations Import relationships between records via CSV. ## Overview Twenty supports importing relationships between objects during CSV import. This allows you to link records (e.g., attach People to Companies) as part of your data migration. **Currently supported for import**: One-to-many relations pointing to a single object type on each side (e.g., People → Companies). Relations pointing to multiple object types are not yet supported in import/export. ## How Relations Work in Twenty ### One to Many / Many to One Twenty supports standard relations where one record links to many others: * **One Company → Many People**: A company can have multiple employees, but each person belongs to one company * **One Company → Many Opportunities**: A company can have multiple deals, but each opportunity belongs to one company ### Relations That Can Point to Multiple Object Types Some relations can connect to different types of objects. This works in two ways: **Pattern 1: Many records linking to one record each from different object types** Several Notes or Tasks can each be attached to multiple object types at once: * **Notes** can be linked to one Person, one Company, and one Opportunity simultaneously * **Tasks** can be linked to one Person, one Company, and one Opportunity simultaneously Here, the Notes/Tasks are on the "many" side. Each links to one record per object type. **Pattern 2: One record receiving links from many records of different object types** A Project can receive links from multiple records across different object types: * **A Project** can have many People linked to it, many Companies linked to it, and many Notes attached to it Here, the Project is on the "one" side. Multiple records from different objects can all link to the same Project. **Import/Export limitation**: Relations that point to multiple object types (like Notes → People/Companies/Opportunities) are **not yet supported** in CSV import or export. * **Import**: Only one-to-many relations pointing to a single object type on each side can be imported * **Export**: Columns for relations pointing to multiple object types are currently left empty This is on our roadmap. ### What's Not Supported Today **Many to Many relations** are not yet available. For example, you cannot currently create a relation where: * Many People are linked to many Projects Many to Many relations are planned for H2 2026. ## Linking Records During Import **Reminder**: Only one-to-many relations pointing to a single object type can be imported (e.g., People → Companies). Relations pointing to multiple object types (e.g., Notes → People/Companies/Opportunities) are not yet supported. ### Step 1: Identify the "One" and "Many" Sides First, determine which object is on the "one" side and which is on the "many" side of the relationship. **Example**: * **Company** is the "one" side (one company has many employees) * **People** is the "many" side (each person belongs to one company) ### Step 2: Ensure the "One" Side Records Exist Before importing the "many" side, the "one" side records must already exist in Twenty. * Import or create the "one" side records first (e.g., Companies) * Validate their unique identifier. This can be: * The `id` (Twenty's UUID) * A field set as unique (e.g., `domain` for Companies, or an external ID from your previous system) The import will fail if a reference is made to a record that does not exist. ### Step 3: Prepare Your CSV File Add a column in your "many" side CSV file that references the "one" side record. **Example**: For a People CSV file linking to Companies: ``` firstName,lastName,email,companyDomain John,Smith,john@acme.com,https://acme.com Jane,Doe,jane@widgets.co,https://widgets.co ``` **Important**: * The value must **exactly match** the unique field on the Company record * For domains, use the **Domain URL** (e.g., `https://acme.com`), not the Domain Label * Map only **one** unique identifier per relation: this leads to a smoother import ### Step 4: Ensure the Relation Field Exists Before uploading your file, make sure the relation field exists between your objects. If it doesn't exist: 1. Go to **Settings → Data Model** 2. Select your object (e.g., People) 3. Create a relation field pointing to the target object (e.g., Company) ### Step 5: Upload and Map the Relation 1. Upload your CSV file via the import UI 2. In the field mapping step, find your relation column (e.g., `companyDomain`) 3. Map it to the relation field (e.g., Company) 4. Twenty will automatically link each record to the matching parent ### Available Unique Fields for Relations | Object | Unique Fields Available | | - | - | | **Companies** | `id`, `domain`, any custom unique field | | **People** | `id`, `email`, any custom unique field | | **Workspace Members** | `id`, `email` (not name) | | **Other standard and custom objects** | `id`, any field marked as unique | **Linking to Workspace Members**: When the relation points to Workspace Members (your team logging into Twenty), reference them by their **email address**, not their name. We recommend using `domain` for Companies and `email` for People, as these are human-readable and easy to maintain in spreadsheets. **Reminder**: Soft-deleted records (visible under Command Menu → See deleted records) count toward uniqueness criteria. If you import a record with the same unique value as a deleted record, the deleted record will be restored. See [Uniqueness Constraints](/user-guide/data-migration/capabilities/uniqueness-constraints) for more details. ## Import Order Rule **Always import the "one" side first!** 1. **Companies** first (no dependencies) 2. **People** second (linked to Companies) 3. **Opportunities** third (linked to Companies/People) 4. **Custom objects** following their dependencies The parent record must exist before you can reference it. # Uniqueness Constraints Source: https://docs.twenty.com/user-guide/data-migration/capabilities/uniqueness-constraints How Twenty enforces data uniqueness during import. ## Overview Twenty enforces uniqueness on certain fields to prevent duplicate records and ensure data integrity. Understanding these constraints is essential for successful imports. ## Default Unique Fields | Object | Unique Fields | | - | - | | **People** | `id`, `email` | | **Companies** | `id`, `domain` | | **Custom objects** | `id` only (by default) | The `id` field is Twenty's internal identifier, auto-generated for each record. It uses UUID format (e.g., `c776ee49-f608-4a77-8cc8-6fe96ae1e43f`). ## Custom Unique Fields You can define additional unique fields under **Settings → Data Model**: 1. Go to **Settings → Data Model** 2. Select the object 3. Click on a field 4. Enable **Unique** in field settings ### Use Cases for Custom Unique Fields * **External IDs**: Store IDs from other systems (Salesforce ID, HubSpot ID) * **Business identifiers**: Employee numbers, customer codes * **Alternative contact info**: LinkedIn profile, phone number The field name `id` is reserved for Twenty's internal ID. Use a different name like `externalId` or `legacyId` for external identifiers. ## Import Behavior ### Creating New Records If a unique field value doesn't exist, a new record is created. ### Updating Existing Records If a unique field value matches an existing record, that record is **updated** with the new data. To **update existing records**, it is recommended to **only match one unique field**. ### Soft-Deleted Records **Deleted records count toward uniqueness.** Soft-deleted records (visible under Command Menu → See deleted records) are included in uniqueness checks. If you import a record with the same unique value as a deleted record, the deleted record will be **restored** with the new data. ## Duplicate Detection During Import During the validation phase: * Duplicates within your file are highlighted in yellow * You can edit or remove duplicate rows from the UI before starting the import ## Best Practices 1. **Remove duplicates** from your file before importing 2. **Check for existing records** in Twenty before importing 3. **Use external IDs** when migrating from other systems 4. **Include unique fields** if you want to update existing records # Export Your Data Source: https://docs.twenty.com/user-guide/data-migration/how-tos/export-your-data Complete step-by-step guide to exporting data from Twenty. ## Overview Export your workspace data to CSV for backups, reporting, or migration. **Use cases:** * **Regular backups** — keep copies of your data * **External reporting** — analyze data in Excel, Google Sheets, or BI tools * **Migration** — move data to another system * **Bulk updates** — export, edit, and re-import to update records ## What You Need to Know ### Export Limits * **Maximum 20,000 records** per export * Only **visible columns** are exported * Only **filtered records** are exported (based on your current view) For larger exports (20,000+ records), use filters to export in batches or use the [API](/developers/extend/api). ### Permissions You need the **"Export CSV"** permission to export data. Contact your workspace admin if you don't have this option. ## Step 1: Navigate to the Object Go to the object you want to export: * **People** — for contacts * **Companies** — for organizations * **Opportunities** — for deals * **Custom objects** — any object you've created ## Step 2: Configure Your View **Important:** The export includes only what's visible in your current view. ### Add/Remove Columns 1. Click **Options → Fields** (or the **+** at the end of columns) 2. Check the fields you want to export 3. Uncheck fields you don't need ### Filter Records (Optional) If you only need a subset of data: 1. Click **Filter** 2. Add filter conditions (e.g., "Created date > January 1, 2024") 3. Only matching records will be exported ### Sort Records (Optional) 1. Click a column header to sort 2. The export will follow your sort order **Create a dedicated export view.** Save a view specifically configured for exports so you don't need to reconfigure each time. ## Step 3: Export the Data 1. Click the **⋮** icon on the top right of the table 2. Select **Export view** 3. Choose where to save the CSV file 4. Wait for the download to complete ## What Gets Exported | Included | Not Included | | - | - | | All visible columns | Hidden columns | | Records matching current filters | Filtered-out records | | Custom field values | Fields not in the view | | Record IDs | File attachments | | Relation IDs | Images | ### Relation Fields Relation IDs are only exported on the **"many" side** of a relationship: * **People export** includes a `companyId` column (People → Company relation) * **Companies export** does NOT include `peopleIds` (Companies is the "one" side) This means you can use the People export to re-import and maintain the Company link, but you'll need to re-import People after Companies to recreate the relationships. ## Exporting for Specific Purposes ### For Backups 1. Create a view with **all fields** visible 2. Remove all filters to include all records 3. Export each object type separately 4. Store exports in a secure location 5. Set a recurring reminder (weekly/monthly) ### For External Reporting 1. Include only the fields you need for analysis 2. Apply filters to focus on relevant data 3. Consider sorting by the field you'll analyze ### For Bulk Updates 1. Export the records you want to update 2. Include the unique identifier (`email`, `domain`, or `id`) 3. Edit the exported file 4. Re-import to update records See: [How to Update Existing Records](/user-guide/data-migration/how-tos/update-existing-records-via-import) ### For Migration If you're exporting to migrate to another system: 1. **Export each object separately** — People, Companies, Opportunities, etc. 2. **Include ID fields** — these help maintain relationships 3. **Document field mappings** — note how Twenty fields map to your target system ## Handling Large Datasets (20,000+ Records) The export limit is 20,000 records. For larger datasets: ### Option 1: Export in Batches 1. Add a filter (e.g., "Created date" ranges) 2. Export the first batch 3. Change the filter 4. Export the next batch 5. Combine files in your spreadsheet **Example filters for batching:** * By date range (January, February, March...) * By owner (Team member A, Team member B...) * By status (Active, Inactive...) ### Option 2: Use the API The API has no record limit: 1. Get your API key from **Settings → Developers** 2. Use the GraphQL API to query records 3. Process results in your application See: [API Documentation](/developers/extend/api) ## Tips and Best Practices ### Create Export Views Save views configured specifically for exports: 1. Configure columns and filters 2. Click **View options** → **Save as new view** 3. Name it "Export - \[Purpose]" ### Secure Your Exports Exported files may contain sensitive data: * Store in secure locations * Delete old exports when no longer needed * Be careful sharing export files ### Check Before Exporting Correct columns are visible Filters are set correctly (or removed for full export) You have Export permission ## FAQ Only visible columns are exported. Add the columns you need via **Options → Fields** before exporting. Check your filters. The export only includes records matching your current view filters. Remove filters to export all records. Not in a single export. Use filters to export in batches, or use the API for larger datasets. CSV (Comma Separated Values). Opens in Excel, Google Sheets, or any spreadsheet application. Yes, but only on the "many" side of relationships. For example, a People export includes `companyId`, but a Companies export does not include people IDs. Not directly through the UI. Use the API to build automated export workflows. ## Next Steps * [How to Update Existing Records](/user-guide/data-migration/how-tos/update-existing-records-via-import) — edit and re-import your export * [How to Import Data via API](/user-guide/data-migration/how-tos/import-data-via-api) — for large datasets * [API Documentation](/developers/extend/api) — build custom export workflows # Fix Import Errors Source: https://docs.twenty.com/user-guide/data-migration/how-tos/fix-import-errors Complete troubleshooting guide for resolving CSV import errors. ## Overview Import not working? This guide helps you identify and fix common import errors step by step. ## How Import Validation Works After uploading your file and mapping columns, Twenty validates your data: 1. **Validation runs** — Twenty checks each row for errors 2. **Errors are highlighted** — problematic rows appear in **yellow** 3. **You can fix in-place** — edit cells directly in the import UI 4. **Or remove rows** — skip problematic records entirely **Fix errors in the UI.** You don't need to go back to your spreadsheet. Edit cells directly during import to save time. ## Step-by-Step Troubleshooting ### Step 1: Identify the Error Type Click on a highlighted row to see the specific error message. Common error types: | Error Message | What It Means | | - | - | | Duplicate values highlighted in yellow | Value already exists in Twenty or appears twice in your file | | `{field} is not a valid {type}` (hover on yellow cell) | Data doesn't match expected format | | Required field highlighted | A required field is empty | | `Can't connect to {object}. No unique record found...` (import fails) | Referenced record doesn't exist | | `Too many records. Up to 10000 allowed` (upload blocked) | File has more than 10,000 records | ### Step 2: Fix the Error Follow the specific instructions below for each error type. *** ## Error: Duplicate Value ### What You'll See Rows with duplicate values are **highlighted in yellow** in the import UI before the import starts. ### What It Means A unique field (email, domain) either: * Already exists in Twenty * Appears twice in your file ### How to Fix **Option 1: Edit the duplicate value** 1. Click the cell with the error 2. Change to a unique value 3. Continue with import **Option 2: Remove the duplicate row** 1. Click the X next to the row 2. The row will be skipped during import **Option 3: Let Twenty update the existing record** 1. Ensure your file includes a unique identifier (`email`, `domain`, or `id`) 2. Map the unique identifier field 3. Twenty will update the existing record instead of creating a duplicate **You can update unique fields too.** * If you keep the `id` but change the `email` → the email will be updated * If you keep the `email` but change the `id` → the id will be updated As long as one unique identifier matches, Twenty updates the record. ### How to Prevent This Error Before importing: 1. Sort your spreadsheet by the unique field 2. Remove duplicate rows 3. Check if records already exist in Twenty **Soft-deleted records count toward uniqueness.** Check Command Menu → See deleted records. Records there still enforce uniqueness. Permanently delete them or restore and update. For more details: [Uniqueness Constraints](/user-guide/data-migration/capabilities/uniqueness-constraints) *** ## Error: Invalid Format ### What You'll See The cell value is highlighted in yellow. Hover over it to see the error message: ``` {field name} is not a valid {field type} ``` ### What It Means The data doesn't match the expected format for that field type. ### How to Fix — By Field Type #### Email **Problem:** Invalid email format **Solution:** Use format `name@domain.com` ``` ❌ john.smith@ ❌ john smith@acme.com ✓ john.smith@acme.com ``` #### Domain **Problem:** Inconsistent format may cause duplicates **Solution:** Use `https://domain.com` format (recommended) ``` ⚠️ acme.com (valid, but not recommended) ⚠️ www.acme.com (valid, but not recommended) ✅ https://acme.com (recommended) ``` All formats are valid, but `https://domain.com` is recommended because it matches the format used by email/calendar sync. Using other formats may create duplicate companies. #### Date **Problem:** Unrecognized date format **Solution:** Use `YYYY-MM-DD` format consistently throughout file ``` ✓ 2024-03-15 (YYYY-MM-DD) ❌ 03/15/2024 (MM/DD/YYYY) ❌ 15/03/2024 (DD/MM/YYYY) ``` #### Phone **Problem:** Missing required columns **Solution:** Include all phone columns | Column | Example | | - | - | | **Phones / Primary Phone Number** | `4159095555` | | **Phones / Primary Phone Country Code** | `US` | | **Phones / Primary Phone Calling Code** | `+1` | #### Boolean **Problem:** Wrong boolean value **Solution:** Use uppercase `TRUE` or `FALSE` ``` ❌ true ❌ yes ❌ 1 ✓ TRUE ✓ FALSE ``` #### Select / Multi-Select **Problem:** Value doesn't match existing options **Solution:** Use **API names**, not display labels How to find API names: 1. Go to **Settings → Data Model** 2. Select the object and field 3. Enable **Advanced mode** (toggle at bottom right) 4. Use the API name (e.g., `OPTION_1`, not "Option 1") ``` ❌ High Priority ✓ HIGH_PRIORITY ``` #### Currency **Problem:** Missing amount or currency code **Solution:** Fill both columns | Column | Example | | - | - | | **Amount / Amount** | `1234.56` | | **Amount / Currency** | `USD` | #### Number **Problem:** Non-numeric characters **Solution:** Numbers only, period for decimals ``` ❌ $1,234.56 ❌ 1,234.56 ✓ 1234.56 ``` For complete format reference: [Field Mapping](/user-guide/data-migration/capabilities/field-mapping) *** ## Error: Required Field Missing ### What You'll See The row is highlighted in yellow with the required field cell marked. ### What It Means A required field is empty for this row. ### How to Fix **Option 1: Enter a value** 1. Click the empty cell 2. Enter a value 3. Continue with import **Option 2: Remove the row** 1. If you don't have the data, click X to skip the row ### How to Prevent This Error Before importing, identify required fields: 1. Go to **Settings → Data Model** 2. Select your object 3. Check which fields are marked as required *** ## Error: Relation Not Found ### What You'll See This error appears **after the import starts** — the import fails with a message like: ``` Can't connect to company. No unique record found with condition: id = 7776ee49-f608-4a77-8cc8-6fe96ae1e43f ``` This means there is no Company in Twenty with that specific identifier. Unlike other errors, this one is not caught during the data review step. The import will start and then fail when it encounters the missing relation. ### What It Means You're trying to link to a record that doesn't exist in Twenty. ### How to Fix **Option 1: Import parent records first** 1. Cancel the current import 2. Import the parent records (e.g., Companies) 3. Then import the child records (e.g., People) **Option 2: Fix the reference value** 1. Check the reference value in your file 2. Ensure it exactly matches an existing record 3. Verify format: domains should be `https://domain.com` **Option 3: Remove the relation** 1. Clear the cell to import without the relation 2. Add the relation manually later ### How to Prevent This Error 1. **Import in the correct order:** * Companies first * People second (with company references) * Opportunities third 2. **Verify reference values:** * Export parent records to get exact identifiers * Use domain format `https://domain.com` * Check for typos and case sensitivity **Import will fail if a reference is made to a non-existent record.** Always import parent objects before child objects. For more details: [Import Relations](/user-guide/data-migration/capabilities/import-relations) *** ## Error: File Too Large ### What You'll See This error appears **when uploading your file** — the upload is blocked entirely: ``` Too many records. Up to 10000 allowed ``` You won't be able to proceed to the data review step until you reduce the file size. ### What It Means Your file has more than 10,000 records. ### How to Fix **Option 1: Split into multiple files** 1. Divide your data into files of 10,000 records or fewer 2. Import each file separately 3. Maintain import order (Companies before People) **Option 2: Use API import** For very large datasets, use the API which has no record limit. See: [How to Import Data via API](/user-guide/data-migration/how-tos/import-data-via-api) *** ## Error: Field Not Recognized ### What It Means A column in your file can't be mapped because the field doesn't exist in Twenty. ### How to Fix 1. Go to **Settings → Data Model** 2. Select the object you're importing 3. Click **+ Add field** 4. Create the custom field with the appropriate type 5. Re-upload your file The CSV import creates records, not fields. All fields must exist before importing. *** ## Error: User Relation Empty ### What It Means You're trying to assign a record to a user (Owner, Assignee) but the relation isn't being mapped. ### Common Causes 1. **User hasn't accepted their invitation** — the user doesn't exist in Twenty yet 2. **Using user ID from old system** — Twenty can't match IDs from another system 3. **Wrong email format** — the email doesn't match the user's Twenty account ### How to Fix 1. Ensure all users have **accepted their invitation** to your Twenty workspace 2. Use the user's **email address** (not their name or old system ID) 3. Use the same email they used to join Twenty **Users must accept invitations before importing.** If a user hasn't accepted their invitation, records referencing them will have empty user relations. *** ## Pre-Import Checklist Avoid errors by checking these before importing: ### File Requirements File is CSV, XLSX, or XLS format File has fewer than 10,000 records File uses UTF-8 encoding ### Data Quality No duplicate emails (for People) No duplicate domains (for Companies) All dates use consistent format All domains use `https://domain.com` format ### Field Formats Boolean fields use `TRUE` or `FALSE` (uppercase) Select fields use API names, not display labels Phone fields have all required columns Currency fields have both Amount and Currency Code ### Relations Parent records imported before child records Relation columns reference existing records Domain format matches Twenty's format exactly ### Data Model All custom fields exist in Settings → Data Model Select options exist before importing *** ## Still Having Issues? If you've tried the above solutions: 1. **Download the sample file** — see the exact format Twenty expects 2. **Export existing records** — compare your file to working data 3. **Test with a small batch** — try 5-10 rows first 4. **Check the reference articles:** * [Field Mapping](/user-guide/data-migration/capabilities/field-mapping) * [Uniqueness Constraints](/user-guide/data-migration/capabilities/uniqueness-constraints) * [Import Relations](/user-guide/data-migration/capabilities/import-relations) * [Error Handling](/user-guide/data-migration/capabilities/error-handling) # Import Companies via CSV Source: https://docs.twenty.com/user-guide/data-migration/how-tos/import-companies-via-csv Complete step-by-step guide to importing companies into Twenty. ## Overview This guide walks you through importing your companies into Twenty. **Companies should be imported first** because People and Opportunities link to Companies. ## Before You Start ### Prerequisites Checklist Your file is CSV, XLSX, or XLS format File has fewer than 10,000 records No duplicate domains in your file All custom fields exist in **Settings → Data Model** Need to import more than 10,000 companies? Split into multiple files or use the [API import](/user-guide/data-migration/how-tos/import-data-via-api). ## Step 1: Prepare Your Company Data ### Required and Recommended Fields | Field | Required? | Format | Notes | | - | - | - | - | | **Name** | Recommended | Text | Company display name | | **Domain** | Recommended | `https://domain.com` | Unique identifier | | **Address** | Optional | Multiple columns | See below | | **Employees** | Optional | Number | Employee count | | **Custom fields** | Optional | Varies | Must exist in Data Model | ### Domain Format **Use the format `https://domain.com` for domains.** This matches the format used when Companies are auto-created from email/calendar sync, preventing duplicates later. **Domain columns:** * **Domain / Domain Label**: `acme.com` * **Domain / Domain URL**: `https://acme.com` ### Address Format Address is a nested field with multiple columns: ``` Address / Address 1,Address / City,Address / State,Address / Country,Address / Post Code 123 Main Street,San Francisco,CA,USA,94105 ``` ### Sample CSV Structure ```csv theme={null} name,Domain / Domain URL,Domain / Domain Label,Address / City,Address / Country,employees Acme Corp,https://acme.com,acme.com,San Francisco,USA,250 Widget Co,https://widgets.co,widgets.co,New York,USA,50 ``` **Pro tip:** Click **Download sample file** during import to see the exact column names Twenty expects. ## Step 2: Access the Import Feature **Option 1: From the Companies View** 1. Navigate to **Companies** in the left sidebar 2. Click the **⋮** icon on the top right 3. Select **Import records** **Option 2: Using Command Menu** 1. Press `Cmd + K` (Mac) or `Ctrl + K` (Windows) 2. Type "import" 3. Select **Import records** 4. Choose **Companies** ## Step 3: Upload Your File 1. Click **Select file** 2. Choose your CSV, XLSX, or XLS file 3. Wait for Twenty to analyze your file ## Step 4: Map Your Columns Twenty automatically tries to match your columns to fields. Review and adjust: 1. **Check automatic mappings** — verify they're correct 2. **Fix incorrect mappings** — click the dropdown to select the right field 3. **Skip columns** — select **Do not map** for columns you don't want to import ### Important Mapping Rules * **Domain**: Map to **Domain / Domain URL** (not Domain Label) * **Address**: Map each part to its specific column (City, State, etc.) * **Select fields**: Values must match existing options (or you'll map them in the next step) ## Step 5: Map Select Field Values If you have Select or Multi-Select fields: 1. Twenty shows your values alongside existing options 2. Match each value in your file to a Twenty option 3. Or create new options if needed Select options use **API names**, not display labels. Check **Settings → Data Model** → Enable **Advanced mode** to see API names. ## Step 6: Review and Fix Errors Before completing the import, Twenty validates your data: 1. Click **Next Steps** 2. Rows with errors are highlighted in **yellow** 3. **Fix errors directly** — click a cell and edit the value 4. **Remove problematic rows** — click the X to skip that row ### Common Company Import Errors | Error | Cause | Solution | | - | - | - | | **Duplicate domain** | Domain already exists in Twenty | Remove from file or update existing record | | **Invalid domain format** | Wrong format | Use `https://domain.com` | | **Missing required field** | Required field is empty | Fill in the value or remove the row | ## Step 7: Complete the Import 1. Review the import summary 2. Click **Confirm** to import 3. Wait for the import to complete 4. Verify by checking a few records ## After Importing Companies Now you can import records that link to Companies: 1. **[Import People](/user-guide/data-migration/how-tos/import-contacts-via-csv)** — link them to Companies using the domain 2. **Import Opportunities** — link them to Companies 3. **Verify the import** — spot-check a few records to ensure data is correct ## Updating Existing Companies To update companies instead of creating new ones: 1. Include the `domain` or `id` column in your file 2. Twenty matches records by this unique identifier 3. Existing companies are updated; new ones are created See [How to Update Existing Records](/user-guide/data-migration/how-tos/update-existing-records-via-import) for details. ## FAQ Domain is a unique identifier in Twenty. This prevents duplicate companies and ensures email sync correctly links emails to the right company. You can leave the domain empty. However, we recommend adding domains when possible for better data quality and automatic email linking. Yes! You can import companies first, then import People later and link them using the company domain. If you include a unique identifier (domain or id) that matches an existing company, Twenty updates that company instead of creating a duplicate. Either remove the duplicate from your file, or include the company's `id` to update the existing record instead. ## Troubleshooting Having issues? Check: * [How to Fix Import Errors](/user-guide/data-migration/how-tos/fix-import-errors) * [Field Mapping Reference](/user-guide/data-migration/capabilities/field-mapping) * [Uniqueness Constraints](/user-guide/data-migration/capabilities/uniqueness-constraints) # Import Contacts via CSV Source: https://docs.twenty.com/user-guide/data-migration/how-tos/import-contacts-via-csv Complete step-by-step guide to importing people/contacts into Twenty. ## Overview This guide walks you through importing your contacts (People) into Twenty. ## Before You Start ### Prerequisites Checklist Your file is CSV, XLSX, or XLS format File has fewer than 10,000 records No duplicate email addresses in your file **Companies imported first** (if linking People to Companies) All custom fields exist in **Settings → Data Model** **Import Companies Before People** If you want to link People to Companies, import Companies first. The Company must exist before you can reference it. ## Step 1: Prepare Your Contact Data ### Required and Recommended Fields | Field | Required? | Format | Notes | | - | - | - | - | | **Email** | Recommended | `name@domain.com` | Must be unique | | **First Name** | Recommended | Text | | | **Last Name** | Recommended | Text | | | **Company** | Optional | Domain or ID | Links to existing Company | | **Phone** | Optional | Multiple columns | See below | | **Job Title** | Optional | Text | | | **Custom fields** | Optional | Varies | Must exist in Data Model | ### Email Format * Must be valid email format: `name@domain.com` * **Must be unique** — no duplicates in your file or in Twenty * For additional emails, use the **Emails / Additional Emails** column: ``` ["jane@twenty.com","jane.doe@twenty.com"] ``` ### Phone Format Phone is a **nested field** requiring multiple columns: | Column | Example | | - | - | | **Phones / Primary Phone Number** | `4159095555` | | **Phones / Primary Phone Country Code** | `US` | | **Phones / Primary Phone Calling Code** | `+1` | ### Linking to Companies Add a column with the Company's unique identifier: | Column Name | Format | Example | | - | - | - | | `companyDomain` | URL format | `https://acme.com` | | `companyId` | UUID | `c776ee49-f608-4a77-8cc8-6fe96ae1e43f` | **Use Domain URL format** (`https://acme.com`), not the label. This matches how Companies are stored in Twenty. ### Sample CSV Structure ```csv theme={null} firstName,lastName,email,jobTitle,companyDomain,Phones / Primary Phone Number,Phones / Primary Phone Country Code John,Smith,john@acme.com,CEO,https://acme.com,4159095555,US Jane,Doe,jane@widgets.co,CTO,https://widgets.co,2125551234,US ``` **Pro tip:** Click **Download sample file** during import or export a few existing People to see the exact column names Twenty expects. ## Step 2: Access the Import Feature **Option 1: From the People View** 1. Navigate to **People** in the left sidebar 2. Click the **⋮** icon on the top right 3. Select **Import records** **Option 2: Using Command Menu** 1. Press `Cmd + K` (Mac) or `Ctrl + K` (Windows) 2. Type "import" 3. Select **Import records** 4. Choose **People** ## Step 3: Upload Your File 1. Click **Select file** 2. Choose your CSV, XLSX, or XLS file 3. Wait for Twenty to analyze your file ## Step 4: Map Your Columns Twenty automatically tries to match your columns to fields. Review and adjust: 1. **Check automatic mappings** — verify they're correct 2. **Fix incorrect mappings** — click the dropdown to select the right field 3. **Skip columns** — select **Do not map** for columns you don't want to import ### Important Mapping Rules | Column Type | Map To | Notes | | - | - | - | | Company reference | **Company** relation field | Use domain OR id, not both | | Email | **Email** | Primary email address | | Additional emails | **Emails / Additional Emails** | Array format | | Phone | Separate columns | Number, Country Code, Calling Code | ### Mapping the Company Relation When mapping the company column: 1. Find your company reference column (e.g., `companyDomain`) 2. Map it to the **Company** relation field 3. Twenty will link each Person to the matching Company **Map only ONE unique identifier for relations.** Don't map both `companyId` AND `companyDomain`. Choose one—preferably domain since it's human-readable. ## Step 5: Map Select Field Values If you have Select or Multi-Select fields (like Lead Source): 1. Twenty shows your values alongside existing options 2. Match each value in your file to a Twenty option 3. Or create new options if needed Select options use **API names**, not display labels. Check **Settings → Data Model** → Enable **Advanced mode** to see API names. ## Step 6: Review and Fix Errors Before completing the import, Twenty validates your data: 1. Click **Next Steps** 2. Rows with errors are highlighted in **yellow** 3. **Fix errors directly** — click a cell and edit the value 4. **Remove problematic rows** — click the X to skip that row ### Common Contact Import Errors | Error | Cause | Solution | | - | - | - | | **Duplicate email** | Email already exists in Twenty or file | Remove duplicate or update existing record | | **Invalid email format** | Email format incorrect | Fix to `name@domain.com` | | **Relation not found** | Company doesn't exist | Import Companies first or fix the reference | | **Missing required field** | Required field is empty | Fill in the value or remove the row | ## Step 7: Complete the Import 1. Review the import summary 2. Click **Confirm** to import 3. Wait for the import to complete 4. Verify by checking a few records and their Company links ## After Importing Contacts Your contacts are now in Twenty! Next steps: 1. **Verify Company links** — open a few People records to confirm they're linked to the right Company 2. **Import Opportunities** — if needed, link them to People and Companies 3. **Set up email sync** — connect your mailbox to see email history on contact records ## Updating Existing Contacts To update contacts instead of creating new ones: 1. Include the `email` or `id` column in your file 2. Twenty matches records by this unique identifier 3. Existing contacts are updated; new ones are created See [How to Update Existing Records](/user-guide/data-migration/how-tos/update-existing-records-via-import) for details. ## FAQ Email is a unique identifier in Twenty. This prevents duplicate contacts and ensures email sync correctly links emails to the right person. You can leave the email empty. However, we recommend adding emails when possible for better data quality and email sync functionality. Add a column with the Company's domain (e.g., `https://acme.com`) or ID. During mapping, connect this column to the Company relation field. Import Companies first, then import People. The Company must exist before you can reference it. Yes! Create a custom field marked as "unique" in your data model to store the external ID. Note: the field name `id` is reserved for Twenty's internal ID. The Company you're referencing doesn't exist. Either import the Company first, or check that the domain/ID exactly matches an existing Company. ## Troubleshooting Having issues? Check: * [How to Fix Import Errors](/user-guide/data-migration/how-tos/fix-import-errors) * [How to Import Relations](/user-guide/data-migration/how-tos/import-relations-between-objects-via-csv) * [Field Mapping Reference](/user-guide/data-migration/capabilities/field-mapping) # Import Data via API Source: https://docs.twenty.com/user-guide/data-migration/how-tos/import-data-via-api When and how to use Twenty's APIs for large-scale data imports. ## Overview Twenty provides both **GraphQL** and **REST APIs** for programmatic data import. Use the API when CSV import isn't practical for your data volume or when you need automated, recurring imports. ## When to Use API Import | Scenario | Recommended Method | | - | - | | Under 10,000 records | CSV Import | | 10,000 - 50,000 records | CSV Import (split into files) | | **50,000+ records** | **API Import** | | One-time migration | Either (based on volume) | | **Recurring imports** | **API Import** | | **Real-time sync** | **API Import** | | **Integration with other systems** | **API Import** | For datasets in the hundreds of thousands, the API is significantly faster and more reliable than multiple CSV imports. ## API Rate Limits Twenty enforces rate limits to ensure system stability: | Limit | Value | | - | - | | **Requests per minute** | 100 | | **Records per batch call** | 60 | | **Maximum throughput** | \~6,000 records/minute | **Plan your import around these limits.** For 100,000 records at maximum throughput, expect approximately 17 minutes of import time. Add buffer time for error handling and retries. ## Getting Started ### Step 1: Get Your API Key 1. Go to **Settings → Developers** 2. Click **+ Create API key** 3. Give your key a descriptive name 4. Copy the API key immediately (it won't be shown again) 5. Store it securely **Keep your API key secret.** Anyone with your API key can access and modify your workspace data. Never commit it to code repositories or share it publicly. ### Step 2: Choose Your API Twenty supports two API types: | API | Best For | Documentation | | - | - | - | | **GraphQL** | Flexible queries, fetching related data, complex operations | [API Docs](/developers/extend/api) | | **REST** | Simple CRUD operations, familiar REST patterns | [API Docs](/developers/extend/api) | Both APIs support: * Creating, reading, updating, and deleting records * **Batch operations** — create or update up to 60 records per call **For imports, use batch operations** to maximize throughput within rate limits. ### Step 3: Plan Your Import Order Just like CSV imports, **order matters** for relations: 1. **Companies** first (no dependencies) 2. **People** second (can link to Companies) 3. **Opportunities** third (can link to Companies and People) 4. **Tasks/Notes** (can link to any of the above) 5. **Custom objects** (following their dependencies) ## Best Practices ### Batch Your Requests * Don't send records one at a time * Group up to **60 records per API call** * This maximizes throughput within rate limits ### Handle Rate Limits * Implement delays between requests (600ms minimum for sustained imports) * Use exponential backoff when you hit limits * Monitor for 429 (Too Many Requests) responses ### Validate Data First * Clean and validate your data before importing * Check required fields are populated * Verify formats match Twenty's requirements (see [Field Mapping](/user-guide/data-migration/capabilities/field-mapping)) ### Log Everything * Log every record imported (including IDs) * Log errors with full context * This helps debug issues and verify completion ### Test First * Test with a small batch (10-20 records) * Verify data appears correctly in Twenty * Then run the full import ### Upsert to Avoid Duplicates The GraphQL API supports **batch upsert** — update if the record exists, create if not. This prevents duplicates when re-running imports. ## Finding Object and Field Names To see available objects and fields: 1. Go to **Settings → API and Webhooks** 2. Browse the **Metadata API** 3. View all standard and custom objects with their fields The documentation shows all standard and custom objects, their fields, and the expected data types. ## Professional Services For complex API migrations, our partners can help: | Service | What's Included | | - | - | | **Data Model Design** | design your optimal data structure | | **Migration Scripts** | write and run the import scripts | | **Data Transformation** | handle complex mapping and cleanup | | **Validation & QA** | verify the migration is complete | **Best for:** * Migrations of 100,000+ records * Complex data transformations * Tight timelines * Teams without developer resources Contact us at [contact@twenty.com](mailto:contact@twenty.com) or explore our [Implementation Services](/user-guide/getting-started/capabilities/implementation-services). ## FAQ GraphQL lets you request exactly the data you need in a single query and is better for complex operations. REST uses standard HTTP methods (GET, POST, PUT, DELETE) and may be more familiar if you've worked with traditional APIs. Yes! Use update mutations (GraphQL) or PUT/PATCH requests (REST) with the record's `id`. Query for existing records first using unique identifiers (email, domain). Update if exists, create if not. Yes, use delete mutations (GraphQL) or DELETE requests (REST). Not currently, but both APIs work with any HTTP client in any language. ## API Documentation For full implementation details, code examples, and schema reference: * [API Documentation](/developers/extend/api) # Import Relations Between Objects via CSV Source: https://docs.twenty.com/user-guide/data-migration/how-tos/import-relations-between-objects-via-csv Complete step-by-step guide to linking records during CSV import. ## Overview This guide walks you through importing relations between objects—for example, linking People to Companies, or Opportunities to People. **What can be imported:** Only one-to-many relations pointing to a single object type. Relations pointing to multiple object types (like Notes linking to People AND Companies) are not yet supported for import. ## Understanding Relations ### What is a "One-to-Many" Relation? In a one-to-many relation: * **One** Company has **many** People (employees) * **One** Company has **many** Opportunities * **One** Person has **many** Tasks The "one" side is the **parent**. The "many" side is the **child**. ### Common Relations in Twenty | Relation | "One" Side (Parent) | "Many" Side (Child) | | - | - | - | | Companies → People | Company | People | | Companies → Opportunities | Company | Opportunities | | People → Tasks | Person | Tasks | | People → Notes | Person | Notes | ## Step 1: Identify the "One" and "Many" Sides Before importing, determine which object is the parent and which is the child. **Ask yourself:** "Does ONE \[Object A] have MANY \[Object B]?" * One Company → Many People ✓ (Company is parent) * One Person → Many Companies ✗ (This is wrong—a person belongs to one company) ## Step 2: Import the Parent Records First The parent ("one" side) must exist in Twenty before you can reference it. **Import order:** 1. **Companies** first (no dependencies) 2. **People** second (link to Companies) 3. **Opportunities** third (link to Companies and/or People) 4. **Tasks/Notes** (link to any of the above) **If the parent record doesn't exist, the import will fail.** Always verify that Companies are imported before importing People with company references. ## Step 3: Note the Parent's Unique Identifier You need to reference the parent record using a **unique identifier**. Available options: | Parent Object | Available Unique Identifiers | | - | - | | **Companies** | `id` (UUID), `domain` (recommended), or any custom unique field | | **People** | `id` (UUID), `email`, or any custom unique field | | **Workspace Members** | `id` (UUID), `email` (not name) | | **Custom Objects** | `id` (UUID), or any field marked as unique | **Recommended:** Use `domain` for Companies and `email` for People. These are human-readable and easy to verify in your spreadsheet. ### Finding the Identifier If you need the `id`: 1. Export the parent records from Twenty 2. The export includes the `id` column 3. Use these IDs in your child records file ## Step 4: Verify the Relation Field Exists Before importing, ensure the relation field exists between your objects. **To check or create:** 1. Go to **Settings → Data Model** 2. Select your child object (e.g., People) 3. Look for a relation field pointing to the parent (e.g., Company) 4. If it doesn't exist, create it: * Click **+ Add field** * Select **Relation** type * Choose the parent object ## Step 5: Prepare Your CSV File Add a column to your child CSV that references the parent using its unique identifier. ### Example: People Linking to Companies **Your People CSV:** ```csv theme={null} firstName,lastName,email,jobTitle,companyDomain John,Smith,john@acme.com,CEO,https://acme.com Jane,Doe,jane@widgets.co,CTO,https://widgets.co Bob,Johnson,bob@techstart.io,Developer,https://techstart.io ``` The `companyDomain` column references the Company's domain. ### Format Requirements | Identifier | Format | Example | | - | - | - | | Domain | URL format | `https://acme.com` | | Email | Standard email | `john@acme.com` | | ID | UUID | `c776ee49-f608-4a77-8cc8-6fe96ae1e43f` | **Domain format matters!** Use `https://domain.com` (not just `domain.com`). This matches how Twenty stores Company domains and prevents matching errors. ### Important Rules 1. **Exact match required** — the value must exactly match the parent record 2. **Map only ONE unique identifier** — don't include both `companyId` AND `companyDomain` 3. **Case sensitive** — `Acme.com` ≠ `acme.com` ## Step 6: Upload and Map the Relation 1. Navigate to the child object (e.g., People) 2. Click **⋮** → **Import records** 3. Upload your CSV file 4. In the field mapping step: * Find your relation column (e.g., `companyDomain`) * Map it to the **Company** relation field 5. Complete the remaining mapping 6. Review errors and confirm Twenty will automatically link each child record to the matching parent. ## Step 7: Verify the Import After importing: 1. Open a few child records (e.g., People) 2. Verify the relation field shows the correct parent (e.g., Company) 3. Open a parent record and check the related records section ## Common Mistakes to Avoid | Mistake | Problem | Solution | | - | - | - | | **Wrong import order** | Importing People before Companies | Always import parents first, then children | | **Wrong domain format** | Using `acme.com` instead of `https://acme.com` | Use full URL format with `https://` | | **Multiple unique fields** | Mapping both `companyId` AND `companyDomain` | Map only ONE unique identifier | | **Missing relation field** | The relation field doesn't exist in the data model | Create it in **Settings → Data Model** before importing | | **Non-existent records** | The parent record doesn't exist in Twenty | Import parent records first, or check for typos | | **Case mismatch** | `Acme.com` in file but `acme.com` in Twenty | Ensure exact case matching | ## Linking to Workspace Members When linking to Workspace Members (your team): * Use their **email address**, not their name * Example: `owner@yourcompany.com`, not "John Smith" ```csv theme={null} taskName,assignedTo Follow up with client,john@yourcompany.com Review proposal,jane@yourcompany.com ``` ## FAQ You have two options: 1. Use the Twenty `id` (export parent records to get their IDs) 2. Create a custom unique field in your data model to store an external ID from your previous system Yes! Include the child record's unique identifier (e.g., `email` for People) and the new relation value. The import will update the relation. Many-to-Many relations are not yet supported for import. This is planned for H1 2026. Relations pointing to multiple object types are not yet supported for import/export. This is on our roadmap. The import will show an error for that row. You can either: * Import the parent record first, then re-import * Fix the reference value * Remove the row from import Common causes: * Wrong format (use `https://domain.com` for domains) * Case mismatch (check exact spelling) * Parent doesn't exist (import parents first) * Mapping multiple identifiers (use only one) **Remember: Soft-deleted records count toward uniqueness.** If you're getting "not found" errors but the record seems to exist, check Command Menu → See deleted records. The parent may have been soft-deleted. ## Troubleshooting Having issues? Check: * [How to Fix Import Errors](/user-guide/data-migration/how-tos/fix-import-errors) * [Import Relations Capabilities](/user-guide/data-migration/capabilities/import-relations) * [Uniqueness Constraints](/user-guide/data-migration/capabilities/uniqueness-constraints) # Migrating from Other CRMs Source: https://docs.twenty.com/user-guide/data-migration/how-tos/migrating-from-other-crms Step-by-step guide to migrate your data from any CRM to Twenty. ## Overview This guide walks you through migrating your data from any CRM to Twenty. The process involves auditing your data, preparing your Twenty workspace, exporting from your current system, and importing into Twenty. Views, workflows, and permissions must be recreated manually after migration. Plan time for this configuration work. ## Step 1: Audit Your Current Data Migration is an opportunity for a fresh start. Don't bring over clutter. **What to keep:** * Active contacts and companies * Open opportunities and deals * Important notes and activities * Custom fields you actually use **What to leave behind:** * Outdated contacts (no activity in 2+ years) * Duplicate records * Test data * Unused custom fields ## Step 2: Map Your Data Model Create a mapping document between your current CRM and Twenty: | Your CRM | Twenty | | - | - | | Account / Organization | **Company** | | Contact / Person | **People** | | Deal / Opportunity | **Opportunity** | | Activity | **Task** or **Note** | | Custom Object | **Custom Object** | **For each field, document:** * The source field name * The target Twenty field * Any format transformations needed (dates, phone numbers, etc.) Keep this mapping document handy during import—you'll reference it when mapping columns. ## Step 3: Set Up Your Twenty Workspace Before importing data, prepare your Twenty workspace: ### Create Custom Objects and Fields 1. Go to **Settings → Data Model** 2. Create any custom objects you need 3. Add custom fields to standard and custom objects 4. Configure field settings (unique, required, select options, etc.) **Fields must exist before import.** The CSV import creates records, not fields. Create all custom fields in Settings → Data Model before importing. ### Invite Your Team **Invite users BEFORE importing data.** If your data includes user references (Account Owner, Assignee, etc.), those users must exist in Twenty before import. Otherwise, those relations cannot be mapped. 1. Go to **Settings → Members** 2. Invite all team members 3. **Wait for everyone to accept** their invitation 4. Verify all users appear in your Members list ## Step 4: Export from Your Current CRM Export your data from your current CRM: 1. Look for an **Export** function (usually under Settings, Data Management, or Admin) 2. Export to **CSV format** when possible 3. Export each object type separately (Companies, Contacts, Deals, etc.) 4. Include all fields you want to migrate **Export these objects (in this order for reference):** 1. Companies / Accounts / Organizations 2. Contacts / People 3. Deals / Opportunities 4. Notes and Activities 5. Custom objects ## Step 5: Clean and Format Your Data Open each exported CSV in a spreadsheet application and prepare it for Twenty. ### Remove Duplicates 1. Sort by the unique field (email for People, domain for Companies) 2. Remove or merge duplicate rows 3. Verify no duplicates exist in Twenty already ### Format Fields Correctly | Field Type | Required Format | | - | - | | **Domain** | `https://domain.com` | | **Email** | `name@domain.com` (must be unique) | | **Date** | `YYYY-MM-DD` | | **Phone** | Three columns: Number, Country Code, Calling Code | | **Boolean** | `TRUE` or `FALSE` (uppercase) | | **Select fields** | Use API names, not display labels | **Domain format is critical.** Use `https://domain.com` (not `domain.com` or `www.domain.com`). This matches Twenty's format and prevents duplicates when you connect email/calendar sync. See [How to Prepare Your CSV Files](/user-guide/data-migration/how-tos/prepare-your-csv-files) for complete formatting requirements for all field types. ### Add Relation Columns To link records (e.g., People to Companies), add a column with the parent's unique identifier. **Example: People CSV with Company link** ```csv theme={null} firstName,lastName,email,companyDomain John,Smith,john@acme.com,https://acme.com Jane,Doe,jane@widgets.co,https://widgets.co ``` See [How to Import Relations](/user-guide/data-migration/how-tos/import-relations-between-objects-via-csv) for detailed instructions on linking records. ### Update User References If your data includes user assignments (Owner, Assignee): 1. Add a column with the **user's email** (not just their ID from the old system) 2. Use the same email addresses that users used to join your Twenty workspace See [How to Prepare Your CSV Files](/user-guide/data-migration/how-tos/prepare-your-csv-files) for complete formatting guide. ## Step 6: Import to Twenty **Import Order Matters!** Always import in this order: 1. **Companies** first (no dependencies) 2. **People** second (link to Companies) 3. **Opportunities** third (link to Companies/People) 4. **Notes and Tasks** (link to records) 5. **Custom objects** following their dependencies The parent record must exist before you can reference it. ### Import Each Object For each CSV file, in order: 1. Navigate to the object in Twenty 2. Click **⋮ → Import records** 3. Upload the CSV file 4. Map columns to fields: * Map user email columns to the appropriate relation fields * Map relation columns (like `companyDomain`) to relation fields 5. Review and fix any errors in the UI 6. Confirm the import 7. Verify a few records before proceeding to the next file **Detailed guides:** * [How to Import Companies](/user-guide/data-migration/how-tos/import-companies-via-csv) * [How to Import Contacts](/user-guide/data-migration/how-tos/import-contacts-via-csv) * [How to Import Relations](/user-guide/data-migration/how-tos/import-relations-between-objects-via-csv) ## Step 7: Large Migrations (50,000+ Records) For large migrations: | Volume | Recommended Approach | | - | - | | Under 10,000 records | Single CSV import | | 10,000 - 50,000 records | Split into multiple CSV files | | 50,000+ records | Use the API | **For API imports:** * Faster and more reliable for large datasets * Supports batch operations (up to 60 records per call) * See [How to Import Data via API](/user-guide/data-migration/how-tos/import-data-via-api) ## Step 8: Post-Migration Setup After importing data, complete your workspace configuration: ### Recreate Views * Set up saved views with filters, sorts, and column configurations * Create any kanban or calendar views you need ### Recreate Workflows * Rebuild your automations in **Settings → Workflows** * Start with the most critical workflows * Test each one before relying on it ### Configure Roles and Permissions * Set up roles in **Settings → Members → Roles** * Assign users to appropriate roles ### Connect Email and Calendar * Each user connects their own account in **Settings → Accounts** * Twenty will start syncing emails to contact records * See [Email & Calendar](/user-guide/calendar-emails/overview) ### Train Your Team * Walk through the new interface together * Document any team-specific processes ## Common Issues and Solutions | Issue | Cause | Solution | | - | - | - | | **Duplicate errors** | Email/domain already exists | Remove duplicates from file, or include unique identifier to update existing records | | **Relation not found** | Parent record doesn't exist | Import parent objects first (Companies before People) | | **Missing fields** | Custom field doesn't exist | Create field in Settings → Data Model before importing | | **Select field errors** | Using display labels | Use API names (enable Advanced mode in Settings to find them) | | **User relation empty** | User hasn't accepted invite | Ensure all users accept invitations before importing | See [How to Fix Import Errors](/user-guide/data-migration/how-tos/fix-import-errors) for detailed troubleshooting steps. ## Post-Migration Checklist ### Data Integrity All records imported (compare counts with source system) Relations working correctly (People linked to Companies) User assignments mapped correctly (Owner, Assignee) Custom fields populated No unexpected duplicates ### Configuration Views recreated Workflows recreated and tested Roles and permissions configured Email/calendar sync connected ### Team Readiness Team trained on new system Old CRM access plan decided (keep for reference? When to disable?) ## FAQ Not currently. Workflows must be recreated manually in Twenty. File attachments are not included in CSV exports. You'll need to re-upload them manually, migrate via API, or contact our team for assistance. Yes, we recommend keeping your old CRM running until you've verified the migration is complete. Just be careful not to create new data in both places. Depends on data volume and complexity. Small migrations (under 10,000 records) can be done in a few hours. Large migrations may take several days including data cleanup and testing. ## Need Help? Want help with your migration? [Find a certified Twenty partner](https://twenty.com/partners/list?categories=SOLUTIONING\&ref=docs-migrate-crm) to move your data, pipelines, and users end-to-end. # Migrating from Self-Hosted to Cloud Source: https://docs.twenty.com/user-guide/data-migration/how-tos/migrating-from-self-hosted-to-cloud Step-by-step guide to migrate your Twenty self-hosted instance to Twenty Cloud. ## Overview This guide walks you through migrating your data from a Twenty self-hosted instance to Twenty Cloud. The process involves setting up your cloud workspace, exporting your data, and re-importing it. Views, workflows, and roles must be recreated manually after migration. Plan time for this configuration work. ## Step 1: Create Your Cloud Workspace 1. Go to [app.twenty.com](https://app.twenty.com) and create a new workspace 2. Complete the initial setup wizard 3. Note your new workspace URL ## Step 2: Recreate Your Data Model Before importing data, recreate your custom objects and fields: 1. Go to **Settings → Data Model** in your cloud instance 2. Create custom objects that match your self-hosted setup 3. Add custom fields to standard and custom objects 4. Configure field settings (unique, required, etc.) Take screenshots of your self-hosted data model for reference, or keep both instances open side by side. ## Step 3: Invite All Users **Critical: Invite users BEFORE importing data.** Users must accept their invitations before you import any records that reference them (like Account Owner fields). If users don't exist yet, those relations cannot be mapped. 1. Go to **Settings → Members** in your cloud instance 2. Invite all team members who had accounts on self-hosted 3. **Wait for everyone to accept** their invitation 4. Verify all users appear in your Members list ## Step 4: Export Data from Self-Hosted Export each object from your self-hosted instance: 1. Navigate to each object (Companies, People, Opportunities, etc.) 2. Configure the view to show **all columns** you want to migrate 3. Click **⋮ → Export view** 4. Save each CSV file with a clear name (e.g., `companies-export.csv`) **Export in this order** (for reference when importing): 1. Companies 2. People 3. Opportunities 4. Custom objects (following their dependencies) 5. Tasks, Notes ## Step 5: Update Workspace Member References The exported CSVs contain user IDs from your self-hosted instance. These IDs won't match your cloud instance, so you need to replace them with emails. **For each CSV file with user references (Owner, Assignee, etc.):** 1. Open the CSV in a spreadsheet application 2. Add a new column next to each user ID column (e.g., `accountOwnerEmail` next to `accountOwnerId`) 3. Fill in the **email address** of each user 4. You can delete the old ID column or leave it (it will be skipped during import) **Example:** Before: ```csv theme={null} name,domain,accountOwnerId Acme Corp,https://acme.com,old-uuid-123 ``` After: ```csv theme={null} name,domain,accountOwnerEmail Acme Corp,https://acme.com,john@yourcompany.com ``` Use the same email addresses that users used to accept their cloud workspace invitation. ## Step 6: Plan Your Import Order Import files in the correct order to maintain relationships: 1. **Companies** first (no dependencies) 2. **People** second (link to Companies) 3. **Opportunities** third (link to Companies and People) 4. **Custom objects** (following their dependencies) 5. **Tasks and Notes** last (link to other records) See [How to Import Relations](/user-guide/data-migration/how-tos/import-relations-between-objects-via-csv) for details on maintaining relationships. ## Step 7: Import to Cloud For each CSV file, in order: 1. Navigate to the object in your cloud instance 2. Click **⋮ → Import records** 3. Upload the CSV file 4. Map columns to fields: * Map user email columns to the appropriate relation fields * Map other columns as usual 5. Review and fix any errors 6. Confirm the import 7. Verify a few records before proceeding to the next file ## Step 8: Recreate Configuration After importing data, manually recreate: ### Views * Recreate saved views with filters, sorts, and column configurations * Set up any kanban or calendar views ### Workflows * Recreate automations in **Settings → Workflows** * Test each workflow before relying on it ### Roles and Permissions * Configure roles in **Settings → Members → Roles** * Assign users to appropriate roles ### Integrations * Reconnect email and calendar sync for each user * Reconfigure any API integrations with new API keys ## Post-Migration Checklist All data imported successfully Relations between objects working correctly User assignments (Owner, Assignee) mapped correctly Views recreated Workflows recreated and tested Roles and permissions configured Email/calendar sync reconnected API integrations updated with new keys ## FAQ Not currently. Workflows must be recreated manually in your cloud instance. File attachments are not included in CSV exports. You'll need to re-upload any attachments manually, migrate them via API or contact our team for assistance with large migrations. Yes, we recommend keeping your self-hosted instance running until you've verified the cloud migration is complete. Just be careful not to create new data in both places. Records referencing that user will fail to import or the relation will be empty. Ensure all users accept invitations before importing data. ## Need Help? Migrating a large or complex workspace? [Get a certified Twenty partner](https://twenty.com/partners/list?categories=HOSTING\&ref=docs-migrate-cloud) to handle the move end-to-end. *(Or loop in our team: [contact@twenty.com](mailto:contact@twenty.com).)* # Prepare Your CSV Files Source: https://docs.twenty.com/user-guide/data-migration/how-tos/prepare-your-csv-files Complete step-by-step guide to format your data for import into Twenty. ## Overview This guide walks you through preparing your CSV file for a successful import. Follow these steps in order to avoid errors. ## Step 1: Check File Requirements Before you start, ensure your file meets these requirements: | Requirement | Details | | - | - | | **Format** | CSV, XLSX, or XLS | | **Size limit** | 10,000 records per file | | **Encoding** | UTF-8 recommended | | **Structure** | One object type per file | For datasets larger than 10,000 records, split into multiple files or use the [API import](/user-guide/data-migration/how-tos/import-data-via-api). ## Step 2: Download the Sample File **This is the most important step.** The sample file shows you the exact column names and format Twenty expects. 1. Go to the object view (People, Companies, etc.) 2. Click **⋮** → **Import records** 3. Click **Download sample file** 4. Use this file as your template **Pro tip:** Export a few existing records instead. This gives you real examples of how data should be formatted, and the column names will map automatically during import. ## Step 3: Remove Duplicate Values Twenty enforces uniqueness on certain fields. Duplicates will cause import errors. | Object | Unique Fields | | - | - | | **People** | `id`, `email` | | **Companies** | `id`, `domain` | | **Custom objects** | `id`, plus any field you marked as unique | **Before importing:** 1. Sort your spreadsheet by the unique field (email or domain) 2. Remove or merge duplicate rows 3. Check for duplicates that already exist in Twenty **Soft-deleted records count toward uniqueness.** Records in Command Menu → See deleted records will cause duplicate errors. Delete them permanently or restore and update them. ## Step 4: Format Each Field Type Correctly Different field types require specific formats. Here's the complete reference: ### Text Fields * No special formatting required * Leading/trailing spaces are automatically trimmed ### Email Fields * Must be valid email format: `name@domain.com` * Must be unique (no duplicates in file or in Twenty) * For additional emails, use this format in the **Emails / Additional Emails** column: ``` ["jane@twenty.com","jane.doe@twenty.com"] ``` ### Domain Fields * **Recommended format**: `https://domain.com` * This matches the format used by mailbox/calendar sync (prevents duplicates) * Fill both columns: * **Domain / Domain Label**: `domain.com` * **Domain / Domain URL**: `https://domain.com` * Must be unique within your file and in Twenty ### Phone Fields Phone is a **nested field** requiring multiple columns: | Column | Example | | - | - | | **Phones / Primary Phone Number** | `4159095555` | | **Phones / Primary Phone Country Code** | `US` | | **Phones / Primary Phone Calling Code** | `+1` | ### Address Fields Address is a **nested field** with multiple columns (some can be left empty): * **Address / Address 1**: Street address line 1 * **Address / Address 2**: Street address line 2 (optional) * **Address / City**: City name * **Address / State**: State or province * **Address / Country**: Country name * **Address / Post Code**: Postal/ZIP code ### Date Fields Use consistent formatting throughout your file: * `YYYY-MM-DD` (recommended): `2024-03-15` * ISO 8601: `2024-03-15T10:30:00Z` ### Number Fields * Numbers only (no text) * Use period for decimals: `1234.56` * No thousands separators (not `1,234.56`) ### Currency Fields Currency is a **nested field** requiring two columns that **both must be filled**: | Column | Example | | - | - | | **Amount / Amount** | `1234.56` | | **Amount / Currency** | `USD` | ### Boolean Fields Use uppercase: `TRUE` or `FALSE` Lowercase `true` or `false` will not work. ### Select Fields Use the **API name** of the option, not the display label. **How to find API names:** 1. Go to **Settings → Data Model** 2. Select the object and field 3. Enable **Advanced mode** (toggle at bottom right) 4. Copy the API name (e.g., `OPTION_1`, not "Option 1") New select options are not created automatically. Add them in **Settings → Data Model** before importing. ### Multi-Select Fields Use API names in array format: ``` ["VALUE1","VALUE2"] ``` ### Array Fields Use JSON array format: ``` ["value1","value2"] ``` ### Rating Fields Use the format: `RATING_1`, `RATING_2`, `RATING_3`, `RATING_4`, or `RATING_5` ### Links/URL Fields Fill both columns: * **Links / Link Label**: `Twenty` * **Links / Link URL**: `https://twenty.com` For secondary links, use the **Links / Secondary Links** column: ``` [{"url":"https://twenty.com","label":"Twenty"}] ``` ### JSON Fields Use valid JSON format: ``` {"key":"value","key2":"value2"} ``` ### ID Fields * **Optional**: Twenty auto-generates IDs if not provided * **Format**: UUID (e.g., `c776ee49-f608-4a77-8cc8-6fe96ae1e43f`) * **Use case**: Include ID to update existing records instead of creating new ones ## Step 5: Add Relation Columns (If Linking Records) To link records to other objects (e.g., People to Companies), add a column with the unique identifier of the related record. **Example**: Linking People to Companies Add a column to your People CSV: ``` firstName,lastName,email,companyDomain John,Smith,john@acme.com,https://acme.com Jane,Doe,jane@widgets.co,https://widgets.co ``` **Important rules for relations:** * The parent record must already exist in Twenty * Use the **Domain URL** format (`https://domain.com`), not the label * Map only ONE unique identifier (don't include both `companyId` AND `companyDomain`) * For Workspace Members, use their **email** (not name) **Import Order Matters!** Import the "one" side before the "many" side: 1. **Companies** first 2. **People** second (with company reference) 3. **Opportunities** third The parent record must exist before you can reference it. See [How to Import Relations](/user-guide/data-migration/how-tos/import-relations-between-objects-via-csv) for detailed instructions. ## Step 6: Ensure Fields Exist in Twenty The import creates **records**, not **fields**. All fields you want to import must already exist in your data model. **Before importing:** 1. Go to **Settings → Data Model** 2. Select your object 3. Create any custom fields you need 4. Note the exact field names (they must match your column headers) ## Step 7: Final Checklist Before uploading your file, verify: File is CSV, XLSX, or XLS format File has fewer than 10,000 records Encoding is UTF-8 No duplicate emails (for People) or domains (for Companies) Dates use consistent format throughout Domains use `https://domain.com` format Boolean fields use `TRUE` or `FALSE` (uppercase) Select fields use API names, not display labels All custom fields exist in Settings → Data Model Parent records imported before child records Relation columns reference existing records ## Common Mistakes to Avoid | Mistake | Solution | | - | - | | Using `true` instead of `TRUE` | Boolean values must be uppercase | | Using display labels for Select fields | Find and use API names in Settings | | Importing People before Companies | Always import parent objects first | | Missing currency code for Currency fields | Fill both Amount and Currency columns | | Wrong domain format | Use `https://domain.com` consistently | | Mapping multiple unique fields for relations | Map only ONE (domain OR id, not both) | ## Next Steps Your file is ready! Now: * [Import Companies](/user-guide/data-migration/how-tos/import-companies-via-csv) (import these first) * [Import Contacts](/user-guide/data-migration/how-tos/import-contacts-via-csv) * [Fix any import errors](/user-guide/data-migration/how-tos/fix-import-errors) # Update Existing Records via Import Source: https://docs.twenty.com/user-guide/data-migration/how-tos/update-existing-records-via-import Complete step-by-step guide to bulk updating records using CSV import. ## Overview Need to update many records at once? Instead of editing them one by one, use the CSV import to bulk update existing records. **Use cases:** * Update job titles for multiple people * Change company information in bulk * Add data to new custom fields * Correct data errors across many records ## How It Works When you import a file containing a **unique identifier** that matches an existing record, Twenty updates that record instead of creating a duplicate. | If unique identifier... | Twenty will... | | - | - | | Matches an existing record | **Update** the existing record | | Doesn't match any record | **Create** a new record | | Is missing from your file | **Create** a new record (with auto-generated ID) | **Multi-Select fields are overwritten, not merged.** If a record has `Option A` and `Option B` selected, and you import `["Option C"]`, the record will only have `Option C` after import. The import replaces all previous selections—it does not add to them. To keep existing values, include them all in your import: `["Option A","Option B","Option C"]` ## Step 1: Export Your Current Data First, export the records you want to update: 1. Navigate to the object (People, Companies, etc.) 2. **Add the columns you need** — click **Options → Fields** to show the fields you want to update 3. **Filter if needed** — narrow down to only the records you want to update 4. Click **⋮** → **Export view** 5. Save the CSV file **Why export first?** The exported file has the correct format, includes unique identifiers, and maps automatically during import. ### What Gets Exported * All visible columns in your current view * The record's unique identifiers (`id`, `email`, `domain`) * Current field values you can modify ## Step 2: Edit the CSV File Open the exported file in your spreadsheet application (Excel, Google Sheets, etc.): 1. **Keep the unique identifier column** — don't delete `id`, `email`, or `domain` 2. **Update the values** in the columns you want to change 3. **Remove columns you don't need to update** (optional, but cleaner) 4. **Don't change unique identifier values** — or Twenty will create new records ### Example: Updating Job Titles **Exported file:** ```csv theme={null} id,email,firstName,lastName,jobTitle 550e8400-e29b-41d4-a716-446655440001,john@acme.com,John,Smith,Sales Rep 550e8400-e29b-41d4-a716-446655440002,jane@acme.com,Jane,Doe,Sales Rep 550e8400-e29b-41d4-a716-446655440003,bob@acme.com,Bob,Johnson,Sales Rep ``` **After your edits:** ```csv theme={null} id,email,firstName,lastName,jobTitle 550e8400-e29b-41d4-a716-446655440001,john@acme.com,John,Smith,Account Executive 550e8400-e29b-41d4-a716-446655440002,jane@acme.com,Jane,Doe,Senior Account Executive 550e8400-e29b-41d4-a716-446655440003,bob@acme.com,Bob,Johnson,Account Executive ``` **Don't change the unique identifier values.** If you change `john@acme.com` to `john.smith@acme.com`, Twenty will create a new record instead of updating the existing one. ## Step 3: Import the Updated File 1. Navigate to the object 2. Click **⋮** → **Import records** 3. Upload your edited CSV file 4. **Ensure the unique identifier is mapped** — verify `email`, `domain`, or `id` is mapped correctly 5. Review the field mappings 6. Check for errors 7. Click **Confirm** Twenty matches records by the unique identifier and updates them with new values. ## Choosing the Right Unique Identifier | Object | Recommended | Alternative | Notes | | - | - | - | - | | **People** | `email` | `id` | Email is human-readable | | **Companies** | `domain` | `id` | Domain is human-readable | | **Custom objects** | Any unique field | `id` | Use your custom unique field | **Use only ONE unique identifier.** Don't map both `email` AND `id`. This can cause confusion and errors. ### Using Custom Unique Fields If you have a custom field marked as unique (like an external ID from another system): 1. Include that field in your export and import 2. Map it during import 3. Twenty will match on that field ## Step 4: Verify the Updates After importing: 1. Open a few updated records 2. Verify the changes were applied 3. Check that no duplicate records were created ## What About Fields Not in Your File? **Fields not included in your import file remain unchanged.** | Your file includes... | Result | | - | - | | `email`, `jobTitle` | Only `jobTitle` is updated; other fields stay the same | | `email`, `jobTitle`, `phone` | `jobTitle` and `phone` are updated | This means you only need to include the fields you want to change (plus the unique identifier). ## Combining Updates and New Records You can update existing records AND create new ones in the same import: ```csv theme={null} email,firstName,lastName,jobTitle john@acme.com,John,Smith,Senior Manager ← Updates existing (email matches) newperson@acme.com,New,Person,Analyst ← Creates new (email doesn't match) ``` ## Common Mistakes to Avoid | Mistake | Problem | Result | Solution | | - | - | - | - | | **Changing unique identifier** | Changed `john@acme.com` to `john.smith@acme.com` | Creates new record instead of updating | Keep unique identifiers unchanged | | **Multiple unique fields** | Mapping both `email` AND `id` | Potential matching conflicts | Map only ONE unique identifier | | **No unique identifier** | File only has `firstName`, `lastName`, `jobTitle` | All rows create new records | Always include `email`, `domain`, or `id` | | **Case mismatch** | File has `John@acme.com` but Twenty has `john@acme.com` | Creates new record | Export from Twenty to get exact values | ## FAQ Records with unique identifiers that don't match existing records will be created as new records. This lets you update and create in the same import. Yes, leave the cell empty in your CSV. The import will clear that field's value on the existing record. Fields not in your import file remain unchanged on existing records. Only fields you include are updated. Yes! Include the relation's unique identifier (e.g., `companyDomain`) and map it to the relation field. The relation will be updated. During the import review step, Twenty shows you how many records will be updated vs. created based on unique identifier matches. There's no automatic undo. We recommend exporting your data as a backup before making bulk updates. ## Best Practices 1. **Export first** — always start from an export to ensure correct format 2. **Backup before updating** — export your data before making bulk changes 3. **Test with a few records** — try updating 5-10 records first before doing a large batch 4. **Use human-readable identifiers** — `email` and `domain` are easier to verify than `id` 5. **Only include necessary columns** — fewer columns means less chance for errors ## Troubleshooting Having issues? Check: * [How to Fix Import Errors](/user-guide/data-migration/how-tos/fix-import-errors) * [Uniqueness Constraints](/user-guide/data-migration/capabilities/uniqueness-constraints) * [Field Mapping Reference](/user-guide/data-migration/capabilities/field-mapping) # Data Migration Source: https://docs.twenty.com/user-guide/data-migration/overview Import and export your CRM data via CSV files or API. ## Import Methods Twenty supports two main methods for importing data: | Method | Best For | Volume Limit | | - | - | - | | **CSV Import** | Standard migrations, regular updates | 10,000 records per file | | **API Import** | Large-scale migrations, automation | Unlimited | For very large datasets (hundreds of thousands of records), use the API. Our [implementation partners](/user-guide/getting-started/capabilities/implementation-services) can help run these scripts if needed. ## CSV Import Basics You can import data for any object using CSV, XLSX, or XLS files. Each file should contain **only one type of object** (e.g., only People records). **Fields must exist before import.** Uploading a CSV creates records but does not create fields. If you need custom fields, create them first under **Settings → Data Model**. ### Steps 1. Navigate to the object where you want to import data 2. Click the **⋮** icon on the top right (this is the Command Menu) and click on **Import records** 3. Download the template file to ensure your data is in the expected format 4. Upload your formatted CSV file 5. Map your columns to Twenty fields 6. Review errors (highlighted in yellow) and fix them, directly editing in the UI 7. Confirm the import ### Importing Relations Between Objects You can import relations between objects using the CSV import function. You need to reference the related object using a unique field from this object: the `id`, the `email` for People and Workspace Members, the `domain` for companies, any other field set as unique in the data model for any other object. **Deleted records count toward uniqueness.** Soft-deleted records (visible under Command Menu → See deleted records) are included in uniqueness checks. If you import a record with the same unique value as a deleted record, the deleted record will be restored. **Import Order Matters!** When importing related objects, upload files in this order: 1. **Companies** first (the "one" side of relationships) 2. **People** second (linked to Companies via companyId) 3. **Opportunities** third (linked to Companies/People) 4. **Custom objects** with relations last Why? The "one" side of a one-to-many relationship must exist before you can reference it. For example, the Company record must exist before you import a Person with that company's ID. Please refer to [this article](/user-guide/data-migration/how-tos/import-relations-between-objects-via-csv) for a step-by-step guide on how to proceed. ## Export Data Export your workspace data for backups, reporting, or migration. ### Steps 1. Navigate to the object you want to export 2. Configure the view with the columns you need 3. Click **⋮** → **Export view** 4. Save the CSV file **Only visible columns are exported.** The CSV file will only contain the columns displayed in your current view. Add or hide columns before exporting to control what data is included. **Export limits**: Up to 20,000 records per export. ## Permissions Data import and export require specific permissions: * **Import**: Requires "Import CSV" permission * **Export**: Requires "Export CSV" permission Contact your workspace admin if you don't have these permissions. ## Next Steps * [Prepare your CSV files](/user-guide/data-migration/how-tos/prepare-your-csv-files) * [Import relations between objects](/user-guide/data-migration/how-tos/import-relations-between-objects-via-csv) * [Import via API for large datasets](/user-guide/data-migration/how-tos/import-data-via-api) # Fields Source: https://docs.twenty.com/user-guide/data-model/capabilities/fields Understand the role of fields and how to manage them. ## About Fields Fields are like columns in a spreadsheet. They store different types of data like text, numbers, or dates. Fields can be standard (built-in) or custom (the ones you create). ### Standard Fields Standard fields come built-in with Twenty to handle common business needs. For example, `First Name` and `Last Name` are standard fields in the `People` object. They store text data for individual names. You cannot delete standard fields, but you can deactivate them if you don't need them. You can also customize the options of the standard `SELECT` type fields, for example the options for the `Stage` on Opportunities. ### Custom Fields Custom fields can be added to any object. You can store text, numbers, dates, dropdown selections, and more. Use custom fields to track information that's specific to your business. For instance, a custom field for SpaceX could be `Rocket Active Status`, indicating if a rocket is operational. ## Field Types Twenty supports various field types: | Type | Description | Example | | - | - | - | | Address | Structured address with street, city, state, country, postal code | Office Address | | Array | List of text values | Tags | | Boolean | True/false checkbox | Is Active | | Currency | Monetary value with currency code | Deal Amount (USD) | | Date | Date values | Close Date | | Date & Time | Date with time | Meeting Time | | Domain | Website domain (used for Companies) | acme.com | | Email | Email addresses (with primary + additional) | Contact Email | | JSON | Structured JSON data | Custom metadata | | Links | URLs with labels (primary + secondary) | Website, LinkedIn | | Long Text | Multi-line text | Description, Notes | | Multi-Select | Multiple choices from a predefined list | Tags, Categories | | Number | Numeric values (integers or decimals) | Quantity, Score | | Phone | Phone numbers with country code | Work Phone | | Rating | Star rating (1-5) | Priority, Score | | Relation | Links to records in other objects | Company → People | | Select | Single choice from a predefined list | Stage, Status | | Text | Single line of text | Name, Title | ## Create a Custom Field To add a custom field to any object, follow these steps: 1. Go to `Settings` in the left sidebar. 2. Go to `Data Model`, then select the object you wish to customize. 3. Proceed by clicking on `+ New Field`. 4. Choose a field name and type that suits your requirements. Consider adding a field description for better understanding. Your newly created field is now available within the application's fields. To display it on a specific view, click on the options menu, then select `Fields`. **Quick way:** Click the **+** button at the top right of any object table, then select `Customize fields`. This takes you directly to the Data Model settings. ## Deactivate a Field You can deactivate a field to hide it from the app without losing your data. Think of it as hiding the field rather than deleting it. Here's how you can do it: 1. Find the field you want to deactivate in your object settings. 2. Click the three dots `⋮` next to the field to open the menu. 3. Select `Deactivate` from the dropdown. What happens when you deactivate a field? 1. **In the app:** The field disappears and you can't add new values to it. 2. **Existing relationships:** If it's a relation field, existing connections stay, but you can't create new ones. 3. **API access:** You can still access the field and its data through the API. You can reactivate Standard and Custom Fields or have the option to permanently delete them. ## Make Fields Unique Make a field unique to ensure distinct records cannot have the same value. For example, email addresses are unique for each person. If you get an error when setting uniqueness, check for duplicate values in your data (including deleted records). ## Indexes (Advanced) Database indexes are managed automatically — adding your own is rarely necessary and easy to get wrong. With Advanced mode on, each object has an **Indexes** section under `Settings → Data Model →

Hello from my app!