Twenty User Guide

Twenty is an open-source CRM you can reshape as your business evolves. Instead of choosing between software that's easy to start but impossible to change and software that's flexible but takes months to set up, Twenty gives you a production-ready CRM with custom objects, views, workflows, and AI agents — all of which you can extend like the rest of your stack.

This guide walks you through everything you can do with Twenty as a user: signing up, shaping your data, building views and pipelines, automating work with workflows, syncing email and calendar, using AI, importing and exporting data, and managing your workspace. Architecture, deployment, configuration internals, and the developer API live in the companion Admin Guide.

Note

Twenty is offered both as a managed cloud service at twenty.com and as a self-hosted application you run yourself. This guide applies to both. Where a feature depends on how your instance is configured (for example, AI or billing), it's called out inline.

1. Quick Start

The fastest way to start is Twenty Cloud. Self-hosting is covered in the Admin Guide.

1.1 Create your account

1. Go to app.twenty.com.
2. Sign up with Google, Microsoft, or email and password.
3. Choose a trial: 30 days (with a card) or 7 days (without a card). Both include full access — unlimited contacts, email integration, custom objects, and API. You can change plan or billing interval at any time.
4. After payment confirmation through Stripe, set your workspace name and user profile.

Tip

You can cancel at any time during the trial. Picking the card-backed 30-day trial simply gives you more runway to evaluate; it does not commit you to a paid plan.

1.2 The three setup steps

Once you're in, three steps make Twenty yours. Do them in this order — connecting a mailbox first gives your team immediate value with real data before you customize anything.

1. Connect your mailbox — go to Settings → Accounts and connect Google or Microsoft. Twenty imports your emails and calendar events and auto-creates contacts from your interactions. Using another provider? Add mailboxes over SMTP or calendars over CalDAV from the same page.
2. Shape your data model — go to Settings → Data Model to create custom objects and fields. Custom objects and fields are unlimited on every plan.
3. Import your data — press Cmd+K (Mac) or Ctrl+K (Windows) to open the Command Menu, then import People, Companies, Opportunities, or any custom object via CSV.

Important

Two People cannot share the same email address, and two Companies cannot share the same domain. Deduplicate your data on these fields before importing.

Each of these steps is covered in depth later: Calendar & Email, Data Model, and Data Import & Export.

2. Core Concepts

Twenty is built on a small set of concepts. Understanding them makes everything else fall into place.

Note

A full glossary appears in the Reference section at the end of this guide.

2.1 How Twenty is different

Most CRMs give you a fixed set of objects and fields and a configuration panel. Twenty treats your data model as something you own and reshape. Custom objects get exactly the same first-class treatment as built-in ones — their own API endpoints, views, permissions, and workflow triggers. Nothing about a custom object is second-class.

3. The Data Model

Everything in Twenty is built around objects and fields.

3.1 Standard objects

Twenty ships with these objects out of the box:

Tip

People, Companies, and Opportunities are the objects that display synced emails and meetings. Use them as your base and add fields to categorize records (for example, a Person Type select field) rather than creating separate objects that won't have email history attached.

3.2 Custom objects

Create custom objects for anything your business needs — projects, support tickets, products, contracts, deliverables. Go to Settings → Data Model → New Object and define a singular and plural name (for example, Project / Projects).

You can also deactivate standard objects and fields you don't need, and hide fields from views without deleting them.

3.3 Field types

Fields are the properties on each object. Twenty supports a wide range of types:

Every object also gets automatic system fields:

3.4 Relations

Objects connect to each other through relation fields. A Company has many People; an Opportunity belongs to a Company. You can create custom relations between any two objects, including many-to-many relationships.

To create one, open the source object in Settings → Data Model, add a field of type Relation, pick the target object, and choose the relation type (one-to-many or many-to-many).

Important

Because custom objects are first-class, a relation you create between two custom objects behaves exactly like the built-in Company ↔ People relation — it shows up in views, the API, and workflow triggers automatically.

3.5 Common data-model tasks

• Create a custom field: Settings → Data Model → open an object → New Field → choose a type → Save.
• Create a custom object: Settings → Data Model → New Object.
• Hide a field from a view without deleting it: open the view's field settings (see Views & Pipelines).
• Deactivate a standard field you don't use: open the field in Settings → Data Model and toggle it inactive.

4. The Layout — Navigating Twenty

The Twenty interface has a consistent layout across every object.

4.1 The main area

The center of the screen is where your records live — people, companies, opportunities, tasks, notes, dashboards, workflows, and any custom objects. You view, edit, delete, and create records here, and you create new views here.

4.2 The navigation bar (left sidebar)

Drag items to reorder them, create folders to group related objects, and hide what you don't use.

4.3 The Command Menu

Press Cmd+K (Mac) or Ctrl+K (Windows) — or click the three dots in the top right — to open the Command Menu. From here you can:

• Create new records
• Import and export data via CSV
• Create new views
• Access deleted records (Twenty supports both soft and hard deletes)
• See keyboard shortcuts for navigating your workspace

Tip

The Command Menu is the fastest path to almost everything. Learn Cmd+K / Ctrl+K first — it replaces dozens of clicks.

4.4 Search

Search is available three ways: through the Command Menu, at the top of the navigation bar, or by pressing /. It works across every object in your workspace.

4.5 The side panel

Click any record to open the side panel on the right — a quick overview of the record's key information without leaving the page. Click Open to go to the full record page.

4.6 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, which you can customize once and apply to every record of that type.

5. Views & Pipelines

Every object supports multiple views — unlimited per object. Use the dropdown at the top left of an object to switch between them. Each view saves its own filters, sorting, and field visibility independently.

5.1 View types

5.2 Table views

Table views show records as rows. You can:

• Edit inline — click a cell to edit without opening the record.
• Customize columns — show, hide, and reorder fields. Each column maps to a field.
• Group — collapse records into groups by a Select field, a date, or a relation.
• Resize and reorder columns to taste.

Note

Some community reports note that the Move Left / Move Right column buttons can behave inconsistently in certain builds. If a column doesn't move as expected, drag the column header directly instead. See Troubleshooting.

5.3 Kanban views

Kanban views organize records as cards in columns, where each column is a value of a Select field (for example, an Opportunity's Stage: New → Negotiation → Won → Lost). Drag a card between columns to update that field. This is the natural way to run a sales pipeline.

5.4 Calendar views

Calendar views plot records on a calendar by a Date field — useful for tasks due, scheduled events, or close dates.

5.5 Filters and sorting

Each view carries its own filters and sort order:

• Filters support AND/OR logic, so you can build conditions like "Stage is Negotiation AND Amount > 10,000".
• Sorting can be applied on one or multiple fields.
• Field visibility is per-view — hide fields you don't need in this context without affecting other views.

5.6 Saving, sharing, and favoriting views

• Save a view to keep its filters, sorting, and visible fields.
• Share a view with your whole workspace, or keep it private.
• Favorite a view to pin it in the sidebar for fast access.

5.7 Recipe: Set up a sales pipeline

1. Open Opportunities.
2. Create a Kanban view.
3. Group by the Stage Select field.
4. Add or rename stages to match your sales process (for example, Lead, Qualified, Proposal, Negotiation, Closed Won, Closed Lost).
5. Drag opportunities between stages as deals progress.
6. Optionally add a filter (for example, owned by you) and Favorite the view.

Tip

To show the expected revenue in your pipeline, surface the Opportunity's Amount (Currency) field as a card field on the Kanban view, and create a Table view grouped by Stage with a sum aggregation to see total value per stage.

6. Workflows & Automation

Workflows let you automate repetitive tasks and connect Twenty to external tools — without writing code, though you can drop into code when you need to.

6.1 Anatomy of a workflow

Every workflow has three parts:

1. Trigger — what starts the workflow.
2. Steps — one or more actions that run in sequence.
3. Variables — data that flows from one step to the next.

Build workflows from the Workflows entry in the navigation bar, using a visual builder.

6.2 Triggers

6.3 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 that split the workflow path
• Iterator — loop over an array of items, running the following steps for each
• AI Agent — let an AI agent process data autonomously (if AI is enabled on your instance)
• Delay — wait before continuing
• Form — collect user input mid-workflow

6.4 Versions and runs

• Versions — a workflow keeps versions so you can edit safely and roll back. You activate the version you want to run.
• Runs — each execution is recorded as a run, with its status and step-by-step logs, so you can see exactly what happened and debug failures.

6.5 Branches and the iterator

• Branches evaluate a condition and send the workflow down one of two paths — use them to handle "if the deal is over $50k, notify the VP; otherwise notify the rep".
• The Iterator loops over an array (for example, every line item on an order) and runs its child steps once per element. When handling arrays inside Code actions, return the array shape the next step expects.

6.6 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
• Notify teammates when a note needs review
• Send email alerts for tasks that are due

Note

Workflows that run code or AI steps may consume workflow credits, and some actions depend on your instance having logic functions or AI enabled. See Billing & Credits and the Admin Guide.

6.7 Recipe: Detect stale opportunities

1. Create a workflow with a Schedule trigger (for example, daily).
2. Add a Find Records action: Opportunities where Stage is not Closed and updatedAt is older than 14 days.
3. Add an Iterator over the results.
4. Inside the loop, add a Send Email (or Slack via HTTP request) action notifying the opportunity's owner.

Warning

Long-running scheduled workflows tied to record events can, in rare cases, stop firing after extended periods until the workflow is toggled off and on again. If a scheduled or event workflow goes quiet, deactivate and reactivate it. See Troubleshooting.

7. Calendar & Email

Twenty connects to your existing email and calendar so your CRM stays current without manual data entry.

7.1 Connecting a mailbox

Go to Settings → Accounts and connect a Google Workspace or Microsoft 365 account. Once connected:

• Emails are automatically linked to the matching Company and People records.
• Full email threads appear on each record's timeline.
• You can send emails directly from Twenty.
• Multiple mailboxes per user are supported — connect several from the same page.

Using another provider? Add mailboxes over SMTP or calendars over CalDAV from the same Accounts page.

7.2 Calendar sync

Calendar events sync automatically from your connected account and appear on the relevant CRM records, giving you a complete picture of every interaction with a contact or company.

7.3 Controlling what gets imported

You control what's pulled in — filter by date range or sender to avoid importing irrelevant email. This is set when you connect or configure the account.

7.4 Common questions

Q: Can I send emails from Twenty? Yes — once a mailbox is connected, you can compose and send from any record, and use the Send Email workflow action.

Q: Can I book meetings from Twenty? Calendar events sync from your connected provider so meetings appear on records; scheduling is driven from your connected calendar.

Q: Can I track email activity on all objects? Email and calendar history attach to People, Companies, and Opportunities — the objects designed to hold interaction history.

Q: Why don't I see emails on a record? Emails link by matching addresses. If a Person record has no email or a different address than the thread, the email won't attach. See Troubleshooting.

Caution

If you connect a mailbox but contacts aren't being auto-created from received emails, your auto-creation settings or sync may need attention — this is a known area; see Troubleshooting.

7.5 Other integration paths

Beyond email and calendar, Twenty connects to external tools through:

8. Data Import & Export

You own your data and can move it in and out at any time — there is no lock-in.

8.1 Importing from CSV

1. Open the Command Menu (Cmd+K / Ctrl+K) — or the object's import action.
2. Choose Import and the target object (People, Companies, Opportunities, or any custom object).
3. Download the sample file first to see the expected format.
4. Map your CSV columns to Twenty fields (field mapping).
5. Review duplicate detection and error handling, then import.

Important

Limit each file to 10,000 records, and deduplicate emails (People) and domains (Companies) before importing — these fields are unique and duplicates will be rejected.

8.2 Preparing your CSV

• Use UTF-8 encoding.
• Put one record per row, with a header row matching your field names where possible.
• Clean and normalize key fields (emails, domains) ahead of time.
• For relations, include the value Twenty uses to match the related record (see below).

8.3 Importing relations

You can import relationships between objects via CSV — for example, linking People to their Companies — by including a column that identifies the related record. To create many-to-many relations or link across custom objects, import the records first, then import the relation mapping.

8.4 Updating existing records

Re-importing can update existing records rather than create duplicates, when the import matches on a unique field (such as a Person's email). This is how you do bulk updates from a spreadsheet.

8.5 Importing via the API

For large or recurring imports, use the REST or GraphQL API instead of CSV. Both support batch operations. This is documented in full in the Admin Guide and in your workspace's interactive API playground (Settings → API & Webhooks).

8.6 Fixing import errors

When an import reports errors, Twenty tells you which rows failed and why (commonly: duplicate unique field, wrong field type, or unmapped required field). Fix those rows in your CSV and re-import only the failed rows.

8.7 Exporting your data

Export records to CSV from the Command Menu or an object's export action. Because the export reflects your live schema, custom fields and objects are included.

8.8 Migrating from another CRM

Export from your existing CRM to CSV, then map fields into Twenty's objects. Bring Companies and People first (so relations can resolve), then Opportunities and custom objects. If you're moving from a self-hosted Twenty instance to Twenty Cloud, you can migrate your data across as well.

9. AI

Twenty integrates AI directly into your CRM — working within your data model and permission system, not bolted on beside it.

Note

AI features depend on your instance having an AI provider configured. On self-hosted instances, an admin must enable AI (see the Admin Guide). If you don't see AI features, they may not be enabled for your workspace.

9.1 AI Chatbot

Ask questions about your data in natural language. The chatbot can query your CRM records, summarize information, and help you find what you need without building complex filters — for example, "Which opportunities in negotiation haven't been touched this week?"

9.2 AI Agents

Agents go beyond chat — they 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 inside workflows, so you can combine AI with manual approvals, conditional branches, and external API calls. You can add an AI Agent step to any workflow.

9.3 MCP

Twenty exposes its data to AI tooling through MCP (Model Context Protocol), letting compatible AI clients operate on your CRM through a standard interface.

9.4 Permissions & safety

AI in Twenty respects your permission model. An agent can only access the objects and fields that the user — or the role the agent runs as — is permitted to view. Sensitive data stays protected even when AI is involved.

Important

Because agents act with real permissions, scope the role an agent runs under to exactly what it needs. Over-permissioned agents can read or change more than you intend.

10. Dashboards & Reporting

Dashboards give you real-time visibility into your business metrics — pipeline health, team performance, revenue trends, and anything else you track.

10.1 Widgets

Each dashboard is made of widgets. A widget is a single chart or metric tied to your CRM data. Configure:

• Chart type — bar, line, pie, number, and more
• Data source — any object in your data model (standard or custom)
• Filters — narrow to specific records, date ranges, or segments
• Aggregation — count, sum, average, min, or max on any numeric field
• Grouping — break down by Select fields, dates, or relations

10.2 What you can track

• Pipeline value by stage
• Deals closed over time
• Average deal size by source
• Task completion rates
• Any custom metric on any object

10.3 Building and sharing

Dashboards are workspace-level — everyone on your team sees them. Arrange widgets on a grid layout and resize them to build the view your team needs. Add a dashboard as you would any record, then add widgets to it.

11. Billing & Credits

Note

Billing applies to Twenty Cloud and to self-hosted instances that have billing enabled. Many self-hosted deployments run without billing at all.

11.1 Trials and plans

• 30-day trial with a card, or 7-day trial without a card. Both include full access.
• You can change plan or billing interval at any time, and cancel at any time.
• Custom objects and custom fields are unlimited on all plans — there is no upsell on data-model size.

11.2 Workflow credits

Workflow executions that use metered capabilities (such as AI agent steps) consume workflow credits. Trials include a credit allowance so you can evaluate automations before committing. When credits run low, workflow steps that require them won't run until credits are replenished.

12. Permissions, Access & Settings

12.1 Roles and permissions

Twenty provides role-based access control at every level — objects, fields, and individual records. Configure roles under Settings → Members → Roles, then assign members (and API keys) to roles. A role determines what a member can see and do.

12.2 SSO

Configure Single Sign-On with SAML or OIDC so your team logs in through your identity provider. SSO is set up under Settings → Security (the exact path depends on your instance).

12.3 Members

Invite teammates under Settings → Members. Members can be assigned as record owners and as workflow or task assignees. Manage who has access and remove members who leave.

12.4 Workspace and profile settings

Tip

Many advanced features (like webhooks) live behind an Advanced toggle at the bottom left of the Settings screen. Enable it to reveal developer-oriented settings.

13. Troubleshooting

This section lists issues that users actually hit, with causes and fixes. Many are drawn from community reports.

Issue: Contacts aren't auto-created from received emails (IMAP)

Cause: Auto-creation of contacts from inbound mail depends on sync settings and the connection type; some IMAP-connected mailboxes don't auto-create contacts the way Google/Microsoft connections do. Solution: Confirm the mailbox is fully connected under Settings → Accounts and that contact auto-creation is enabled for it. Re-sync the account. Prevention: Prefer the native Google Workspace or Microsoft 365 connection when you want full auto-creation behavior.

Issue: Emails don't appear on a record

Cause: Emails attach by matching the email address on the thread to a Person or Company record. A record with no email, or a different address, won't receive the thread. Solution: Add the correct email address to the Person record, then re-sync. Prevention: Keep email fields populated and deduplicated.

Issue: A scheduled or record-event workflow silently stops firing

Cause: In some builds, a long-lived workflow tied to a database event can stop triggering after running for a while. Solution: Open the workflow, deactivate it, then reactivate it. Check the workflow's runs for the last successful execution. Prevention: Monitor critical workflows via their run history.

Issue: "Move Left" / "Move Right" column buttons don't reorder reliably

Cause: A known inconsistency with the column-move buttons in table views. Solution: Drag the column header directly to reposition it instead of using the buttons.

Issue: A filter on a custom object errors with "object doesn't have any '…' field"

Cause: A view filter references a field that doesn't exist on the (custom) object being filtered — often after a relation or field was renamed or removed. Solution: Edit the view's filters and remove or repoint the broken condition to an existing field. Prevention: When you rename or delete fields, review views that filtered on them.

Issue: Can't create or delete People (or another object) records

Cause: Usually a permissions restriction on your role, or a unique-constraint conflict (duplicate email/domain). Solution: Check your role's permissions for that object under Settings → Members → Roles, and confirm you're not violating a uniqueness rule.

Issue: I can't change my own email

Cause: Email changes for a member can be restricted by workspace configuration. Solution: Ask a workspace admin to update the email, or change it through your identity provider if you log in via SSO.

Issue: The home page always opens the wrong object

Cause: In some builds the home redirect lands on the first object alphabetically rather than your last-visited one. Solution: Favorite the view you want as your starting point so it's one click away in the sidebar.

14. FAQ

Q: Is Twenty really free and open source? The core is open source and self-hostable. You can run it yourself at no license cost, or use the managed cloud with a subscription.

Q: How many custom objects and fields can I create? Unlimited, on every plan.

Q: Can two people share an email address? No. People are unique by email and Companies are unique by domain.

Q: What's the difference between soft and hard delete? A soft-deleted record is moved to a recoverable state (accessible from the Command Menu's deleted-records view); a hard delete removes it permanently.

Q: Can I use Twenty's API with my custom objects? Yes — custom objects automatically get REST and GraphQL endpoints identical to built-in objects. See the Admin Guide.

Q: Do I need to connect email to use Twenty? No, but connecting a mailbox is the single highest-value setup step — it populates your CRM with real interactions immediately.

Q: Can I send and receive email entirely inside Twenty? You can send from connected accounts and see synced threads on records. Twenty is a CRM layer over your mailbox, not a full email client replacement.

Q: How do I automate a repetitive task? Build a workflow: pick a trigger and chain actions. No code required, though Code actions are available.

Q: What keyboard shortcut opens the Command Menu? Cmd+K on Mac, Ctrl+K on Windows. Press / to jump straight to search.

Q: Can AI agents see data I can't? No. Agents run under a role and only access what that role permits.

Q: How do I move off Twenty if I want to? Export everything to CSV (or via the API) at any time. There is no lock-in.

Q: Can I self-host? Yes — with a single Docker Compose setup. See the Admin Guide for full deployment, configuration, and operations.

15. Reference

15.1 Keyboard shortcuts

(See the full, current shortcut list inside the Command Menu.)

15.2 Glossary

API — An interface that lets you connect Twenty with other software and build custom integrations. Apps — Code-level extensions that define data models and logic, deployable across workspaces (developer feature). Code Actions — Workflow steps that run custom JavaScript for logic beyond the built-in actions. Command Menu — Quick-access interface (Cmd+K / Ctrl+K) for actions, record creation, and navigation. Company & People — The two fundamental record types: organizations and individuals. Custom Fields — Fields you create to capture business-specific information. Data Model — The structure of your CRM: what objects exist, their fields, and how they relate. Favorites — Records or views marked for quick sidebar access. Field — A specific property where data is stored on a record. Iterator — A workflow action that loops over an array, running following steps per item. Kanban — A card-and-column view for tracking records through stages. Object — A data structure representing a type of entity; standard or custom. Opportunities — Potential deals or sales. Record — A single instance of an object. Relation Fields — Fields that link records across objects. Standard Fields — Built-in fields that ship with objects by default. Tasks — Assigned activities related to contacts, accounts, or opportunities. Triggers — The event that starts a workflow. Upsert — Update a record if a match exists, otherwise create it. Views — Customized displays of records with their own filters, layout, and sorting. Webhooks — Automated messages Twenty sends to other apps when events occur. Workflows — Automated processes that run actions based on triggers. Workspace — Your company's instance of Twenty; holds all records and members. Workspace Members — Teammates with access to your workspace.

15.3 The technology behind Twenty

You don't need to know this to use Twenty, but it helps explain its flexibility. Twenty is built in TypeScript as an Nx monorepo. The backend uses NestJS with PostgreSQL and Redis; the frontend is React. Because the data model is dynamic, every custom object you create instantly gains its own API, views, permissions, and workflow triggers. Full architecture and self-hosting details are in the Admin Guide.