---
title: Field Mapping
description: How field mapping works during data import.
---
import { VimeoEmbed } from '/snippets/vimeo-embed.mdx';
## 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`
### Champs de relation
Please see our dedicated article: [Import Relations Between Objects](/l/fr/user-guide/data-migration/capabilities/import-relations)
### Champs de sélection
Use the **API name** of the option (not the display label):
```
VALUE1
```
Voir [ici](#finding-api-names-for-select-fields) où trouver les noms d'API.
Les nouvelles options de sélection ne seront pas créées automatiquement par l'importation. Elles doivent être ajoutées sous **Paramètres → Modèle de données** avant l'importation.
### Champs de texte
* Aucun formatage particulier requis
* Les espaces au début et à la fin sont supprimés
## Recherche des noms d'API
Pour les champs Select, Multi-Select et Array avec des options prédéfinies, vous devez utiliser les **noms d'API**, et non les libellés affichés.
### Comment trouver les noms d'API
1. Allez dans **Paramètres → Modèle de données**
2. Sélectionnez l'objet et le champ
3. Activez le **mode avancé** (bouton à bascule en bas à droite de la page des paramètres)
4. Affichez le nom d'API pour chaque option