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

# How to import contacts from a CSV

> Bring in many contacts at once from a spreadsheet saved as CSV and check how many were created.

## What it is for

You have a spreadsheet of customers and want to put them all in **Contacts** at once. The import only accepts a **.csv** file. The system matches each row by phone: whoever already exists is updated, with no duplicates. To also bring in pipeline, tags and owners from another system, use the wizard [How to bring contacts from another system](https://docs.stchat.app/en/subcontas/trazer-contatos-de-outro-sistema.md).

## Who can do it

* By default, every role except Operator.
* An Operator can only import if the Admin turns on that ability for them.
* For the owner column to count, you must be Owner, Admin or Supervisor. For the others, the column is ignored.

## Where to click

In **Contacts**, click the **Import contacts via CSV** icon (next to **New contact**). If the organization has no contacts yet, use the **Import .csv** button in the middle of the screen.

## Step by step

**1. Prepare the spreadsheet**

Save the spreadsheet as CSV. The first row is the header and must have at least **name** or **phone**. To see the format, click **Download CSV template** (file `modelo-contatos.csv`).

**2. Choose the file**

Click **Drop the .csv here or click to choose**. Any other file type is refused: **Only .csv files. Save the sheet as CSV and choose it again.**

**3. Check the mapping**

The system recognizes the columns by the header name: name, last name, phone, email, company, notes (or observation), tags, owner, CPF/CNPJ (or document) and the consent column ("Aceita receber", with "Data do aceite" for the opt-in date). In the table you see the first 100 rows and the totals: **valid**, **repeated (will update)** and **ignored**. 

**4. Adjust the warnings**

In the **tags** column, separate several with a semicolon, like `vip;financeiro`. New tags are created and the screen tells you how many. If there is consent, choose the channel under **Applies to channel**. To change the file, click **Change**.

**5. Import**

Click **Import N contacts**. Follow **Importing X/Y…** until it finishes.

## What happens next

The **Import complete** window (or **Import complete with warnings**) opens with the file name and the rows read. The numbers are:

* **created**: new contacts.
* **updated**: contacts that already existed and were updated with the spreadsheet data.
* **not imported**: rows with an error.

In the **Phones** section you can see numbers adjusted to +55 area code (only the format changes), contacts that already existed with the same number with or without the 9th digit, and numbers that were not recognized. For these, use **Download list (.csv)**, fix it and import again. Then click **View imported contacts** or **Close**.

**Where the record is kept.** On the card of each imported contact there is the **IMPORTED** block, with the file, the date, who imported it and the spreadsheet **row**. When the **View import** link appears, it opens the **Imports** screen, with **Date**, **Source**, **Who did it · numbers** and **Status**, plus **Download errors** and **Undo** when available. Dates appear in your browser's time zone.

## Common errors

* **Couldn't identify the columns.** The header needs **name** or **phone**.
* **Row with no name and no phone.**
* **Invalid phone: use area code + number (at least 10 digits) or +country code.**
* **Invalid email.** Fix the email in the row.
* **Owner not found: ...** The name or email in the column does not match any member of the organization.
* **Phone repeated in the file: this row updates the same contact, no duplicate.** It is only a warning.
* **Failed to import contacts.** The screen shows the message about the problem. Check the file and try again.
* **Invalid session. Reload the page.**

## Next step

* [Contacts](https://docs.stchat.app/en/subcontas/contatos.md)
* [How to bring contacts from another system](https://docs.stchat.app/en/subcontas/trazer-contatos-de-outro-sistema.md)
* [Contact card](https://docs.stchat.app/en/subcontas/ficha-do-contato.md)
* [Lists and segments](https://docs.stchat.app/en/subcontas/listas-e-segmentos.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.