Skip to main content
Twenty is an open-source CRM for managing companies, people, opportunities, and custom objects. The Twenty destination creates or updates records in your Twenty workspace through its REST API. The connector writes to a single Twenty object per destination, selected through the Mode setting:
  • People - creates or updates people (contacts).
  • Companies - creates or updates companies.
  • Opportunities - creates or updates opportunities.
  • Notes - creates or updates notes.
  • Tasks - creates or updates tasks.
  • Custom object - creates or updates records of a custom object you define.
To send data to more than one object, create one destination per object.

​
1. Add your Twenty access

  1. In the Destinations tab, click on the “Add destination” button located on the top right of your screen. Then, select the Twenty option from the list of connectors.
  2. Click Next and you’ll be prompted to add your access:
    • API Key: Your workspace-scoped Twenty API key (Bearer token). Generate it in Twenty under Settings → API & Webhooks.
    • Mode: Select the object you want to write to (People, Companies, Opportunities, Notes, Tasks, or a custom object).
    • API URL (advanced): Base URL of your Twenty instance, without the trailing /rest. Defaults to https://api.twenty.com for Twenty Cloud. Set your own host when self-hosting.
    • Custom object (advanced): The REST path segment of your custom object (plural camelCase, e.g. myCustomObjects). Only used when Mode is set to Custom object.
    • Upsert (advanced): When enabled, the connector creates a record or updates it when a matching record already exists, matched on a unique field such as email. Recommended to avoid duplicates on recurring syncs.
    • Enable partial success (advanced): Whether the connector should continue trying to sync records after one fails.
  3. Click Next.

​
2. Select your data to send

  1. The next step is letting us know which data you want to send. Select the layer and then the desired table.
    Tip: The table can be found more easily by typing its name.
  2. Click Next.

​
3. Map your columns

Map the columns from your input table to the corresponding Twenty fields. Use the exact API name of each Twenty field as the destination.

​
Create vs. update behavior

With Upsert enabled, the connector sends each record to POST /rest/{object}?upsert=true: Twenty creates the record if it does not exist, or updates it when a matching record is found on a unique field (for example, email). This is the recommended behavior for recurring syncs. If you map a column to the id destination field, the connector instead performs an update (PATCH) on the existing record with that Twenty ID.

​
Composite fields

Several Twenty fields are composite (objects with sub-fields). Map to a sub-field using dot-notation in the destination field name:
Composite fieldExample destination
Full namename.firstName, name.lastName
Emailsemails.primaryEmail
LinkslinkedinLink.primaryLinkUrl
Phonesphones.primaryPhoneNumber
CurrencyannualRecurringRevenue.amountMicros
Currency fields are stored in micros (the amount multiplied by 1,000,000). Map your monetary column to the amountMicros sub-field (e.g. totalRevenue.amountMicros) and the connector converts the value for you, so 49.99 is sent as 49990000.

​
Transforms

Each mapping accepts an optional ordered list of value transforms, applied before sending:
TransformDescription
uppercaseConvert to upper case. Use for Select fields whose options are upper case (e.g. active → ACTIVE).
lowercaseConvert to lower case. Useful for normalizing email keys.
trimRemove surrounding whitespace.
round_intRound a decimal to the nearest integer (e.g. 7.22 → 7).
to_stringCast the value to text. Use for an integer id going to a text field.
yesno_to_boolConvert Yes/No to true/false.
null_if:<x>Drop the value when it equals <x> (e.g. null_if:-).
only_if:<x>Keep the value only when it equals <x>, otherwise leave the field blank.
Empty and null values are skipped, so existing data in Twenty is preserved when a column has no value. Example input table (People):
emailfirst_namecompany_sizerevenue
ada@example.comAda501250000.00
alan@example.comAlan12300000.00
Column mapping: email → emails.primaryEmail (transform lowercase), first_name → name.firstName, company_size → employees, revenue → annualRecurringRevenue.amountMicros.

​
4. Configure your Twenty data destination

  1. Describe your destination for easy identification within your organization. You can inform things like what data it brings, to which team it belongs, etc.
  2. To define your Trigger, consider how frequently you need to have the data updated on the destination (every day, once a week, only at specific times, etc.).
  3. Click Done.

​
Check your new destination!

  1. Once completed, you’ll receive confirmation that your new destination is set up!
  2. You can view your new destination on the Destinations page. Now, for you to be able to see it on Twenty, you have to wait for the pipeline to run. You can monitor it on the Destinations page to see its execution and completion. If needed, manually trigger the pipeline by clicking on the refresh icon. Once executed, your data should be seen on Twenty.
If you encounter any issues, reach out to us via Slack, and we’ll gladly assist you!