> ## Documentation Index
> Fetch the complete documentation index at: https://docs.nekt.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Twenty as a destination

> Send your data from Nekt to Twenty CRM.

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](https://app.nekt.ai/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 field | Example destination                   |
| :-------------- | :------------------------------------ |
| Full name       | `name.firstName`, `name.lastName`     |
| Emails          | `emails.primaryEmail`                 |
| Links           | `linkedinLink.primaryLinkUrl`         |
| Phones          | `phones.primaryPhoneNumber`           |
| Currency        | `annualRecurringRevenue.amountMicros` |

<Note>
  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`.
</Note>

### Transforms

Each mapping accepts an optional ordered list of value transforms, applied before sending:

| Transform       | Description                                                                                           |
| :-------------- | :---------------------------------------------------------------------------------------------------- |
| `uppercase`     | Convert to upper case. Use for Select fields whose options are upper case (e.g. `active` → `ACTIVE`). |
| `lowercase`     | Convert to lower case. Useful for normalizing email keys.                                             |
| `trim`          | Remove surrounding whitespace.                                                                        |
| `round_int`     | Round a decimal to the nearest integer (e.g. `7.22` → `7`).                                           |
| `to_string`     | Cast the value to text. Use for an integer id going to a text field.                                  |
| `yesno_to_bool` | Convert `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):**

| email                                       | first\_name | company\_size | revenue    |
| :------------------------------------------ | :---------- | :------------ | :--------- |
| [ada@example.com](mailto:ada@example.com)   | Ada         | 50            | 1250000.00 |
| [alan@example.com](mailto:alan@example.com) | Alan        | 12            | 300000.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](https://docs.nekt.com/get-started/core-concepts/triggers), 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](https://app.nekt.ai/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](https://app.nekt.ai/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!