> For the complete documentation index, see [llms.txt](https://help.usejimo.com/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://help.usejimo.com/docs/analyze/users-and-segments/data-management/imports.md).
# Imports
**Dashboard path:** [Users & Segments > Data Management > Imports](https://i.usejimo.com/users/imports)
## Import Segments via CSV
Importing lets you create or update users in bulk from a CSV file, without waiting for them to show up in your product. Use it to seed a project before installation, to enrich your base with data that lives in another system, or to build an audience from a list someone handed you.
The import flow validates your file before it writes anything. You choose how Jimo matches users, map each column, then confirm the import.
{% hint style="info" %}
An import is a **snapshot**, not a sync. It writes what the file contains, once. Nothing keeps updating afterwards. For a live connection, see [Data Management](/docs/analyze/users-and-segments/data-management.md) and the [integrations](/docs/integrations/integrations-list.md).
{% endhint %}
***
### Prepare your CSV file
**Headers**
The only required structure for your CSV file is to use the **first row as headers**, with each header representing the **name of the user attribute** you want to import or use for matching.
* Each column should have a **header (`attribute name`)** followed by the **corresponding value for each user**.
* The column name **does not need to match exactly** an existing attribute name in Jimo, you can manually choose which one it corresponds to. If the attribute does not exist yet, it can be **created automatically** during import.
* While **not mandatory**, it is **recommended** to use `id` or `email` as the **first column** to make user matching easier. Make sure the values in this column are **unique** (one row per user).
**Format**
Double-check that your file is saved in the CSV format (`.csv`).
{% code title="Example.csv" fullWidth="false" %}
```csv
id,email,plan,creation_date
1,johndoe@example.com,Basic,2023-01-15
2,janedoe@example.com,Premium,2023-02-20
3,bobjohnson@example.com,Standard,2023-03-10
4,alicemiller@example.com,Basic,2023-04-05
5,charlesbrown@example.com,Premium,2023-05-25
```
{% endcode %}
***
### The imports list
Every import you start is listed here, finished or not.
| Column | What it shows |
| ----------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Creation date** | When the import was started, and by which teammate |
| **Name** | The import name you gave it |
| **Description** | Your optional note |
| **Row detected** | How many rows Jimo read in the file |
| **Row processed** | How many were actually written |
| **Status** |
Draft for an import started but never completed
Pending while the CSV import is running
Done once the import is completed
|
{% hint style="info" %}
A **Draft** import has consumed nothing and changed nothing. If you left the flow before the final Import click, the file was analyzed but no user was created or updated.
{% endhint %}
**Import users from CSV**, top-right, starts a new one. The flow has three numbered steps.
***
{% stepper %}
{% step %}
### Import CSV file
**Choose CSV file** uploads your prepared file. Then:
| Field | |
| -------------------------- | --------------------------------------------------------- |
| **Import name** | Required. This is what shows in the list. |
| **Description** (optional) | What this import was for, so the next person understands. |
**Next** unlocks step 2.
{% endstep %}
{% step %}
### Identification
This step decides **how rows in your file are matched against users already in Jimo**, and what happens on each side of that match.
**Three switches**
| Switch | What it does |
| ------------------------- | ---------------------------------------------------------------- |
| **Add new users** | If a row cannot be matched to an existing user, create that user |
| **Update existing users** | If a row is matched, update that user with the file's values |
| **Create a segment** | Create a segment containing all users identified in the CSV |
Both first switches are on by default: the normal case is create-or-update.
* Turn off **Add new users** to enrich only people Jimo already knows.
* Turn off **Update existing users** to avoid overwriting values already in place.
{% hint style="success" %}
**Create a segment** is the shortcut worth knowing. It turns a flat list into a targetable audience in one move, no rule to write. Useful when the list is exactly the audience: a beta cohort, an event's attendees, accounts flagged by your sales team.
{% endhint %}
**Choosing the matching field**
Two selectors face each other: on the left, the identifier Jimo uses (**Id used in your app (identify)**), on the right, the **identifier column in your csv file**. You are declaring which column holds the same value.
If your project already identifies users, a banner reminds you to pick **the same type of ID** your app uses, and lists the identifiers currently in use so you can compare against your file. If your app identifies by email, point at your email column. If it identifies by an internal ID, point at that one.
{% hint style="warning" %}
If you **don't Add new users** but **only Update existing users** and/or **Create a segment**, it allows you to match the CSV list with the native **Jimo email** field instead of the user id.
But you can't base the matching on a [**custom attribute**](/docs/analyze/users-and-segments/data-management/attributes.md#custom-attributes).
{% endhint %}
{% hint style="danger" %}
**Matching on the wrong field creates duplicates instead of updating.** If your app identifies users by internal ID but you match on email, no row matches, and every line is created as a brand-new user. The identifiers listed in the banner are there for exactly this check: compare them to your column before continuing.
{% endhint %}
{% endstep %}
{% step %}
### Map fields
Each column in your file gets a card, showing its name, how many rows were found, and the first value so you can confirm you are looking at the right data.
For each card, the **checkbox** decides whether the column is imported at all, and **Map to attribute** decides where it lands:
* **Field use for Identification**: the column you chose in step 2, used for matching rather than written as data
* **Add as a new attribute**: creates a custom attribute from this column
* An **existing attribute**: writes into one you already have
{% hint style="info" %}
This is the moment an import creates [attributes](/docs/analyze/users-and-segments/data-management/attributes.md). A column mapped to **Add as a new attribute** becomes a real custom attribute in your project, Active immediately since it arrives with values.
{% endhint %}
Uncheck the columns you do not need. A CSV exported from another tool often carries a dozen columns you will never segment on.
**Import** runs it.
{% endstep %}
{% endstepper %}
***
### Import done
A green banner reports what happened, in three numbers:
* **users were added**: rows that matched nobody and became new users
* **users were updated**: rows that matched an existing user
* **users couldn't been processed**: rows Jimo could not handle
Read them against your expectations. An import of 500 known customers that reports 500 added and 0 updated means the matching field was wrong: you have just duplicated your base rather than enriched it.
***
### Common issues and troubleshooting
**Error: Invalid CSV Format**
* **Solution**: Ensure your CSV file is properly formatted with the correct headers.
**Error: Mapping Issues**
* **Solution**: Double-check that all fields are correctly mapped and that there are no empty columns.
**Error: Validation Failed**
* **Solution**: Review the error messages provided during validation and correct any issues in your CSV file.
***
### Related pages
* [Exports](/docs/analyze/users-and-segments/data-management/exports.md): the same operation, in reverse
* [Data Management](/docs/analyze/users-and-segments/data-management.md): when an import is the right inlet, and when it is not
* [Attributes](/docs/analyze/users-and-segments/data-management/attributes.md): what happens to the custom attributes an import creates
* [Segments](/docs/analyze/users-and-segments/audience/segments.md): what the Create a segment switch produces
* [Users](/docs/analyze/users-and-segments/audience/users.md): where the imported users land