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

# Upload and manage contacts in Chatbase

> Import contacts in bulk from a file, add single contacts, delete contacts, and define custom attributes for your AI agent.

Bulk contact import lets you upload up to 1,000 contacts at once from a `.csv` or `.xlsx` file, through a guided import flow on your AI agent's **Contacts** page. This page also covers adding a single contact, deleting contacts, and defining custom attributes. Contacts are available on the Basic plan or higher. See [Contacts overview](https://chatbase.co/docs/user-guides/chatbot/contacts/contacts-overview.md) for how contacts are used.

You can use this to:

* Quickly add new contacts
* Update existing contacts by External ID
* Import custom attributes in bulk

***

## Import contacts

Click **Import** on the **Contacts** page. The import flow consists of four steps.

### Upload file

Upload a `.csv` or `.xlsx` file by dragging it into the upload area or clicking to select a file.

> **Limits**
>
> * Maximum file size: **5 MB**
> * Maximum rows per upload: **1,000**

#### File format

* **CSV:** columns must be separated by commas. Semicolon-separated files won't split into columns. Fields in quotes are allowed. Save the file as UTF-8 so accented and non-Latin characters import correctly.
* **Excel (.xlsx):** only the first sheet is read.
* **Headers:** the first row must hold the column headers.

#### CSV template

Click **Download CSV template** to get `contacts-template.csv` with the correct headers. The template's columns are:

* **External ID**, **Name**, **Email**, and **Phone Number**
* One column per custom attribute defined for the AI agent, headed with the attribute's Label (or its Name if it has no Label)

The template includes a sample row. For example:

```csv theme={null}
External ID,Name,Email,Phone Number
user-001,John Doe,john@example.com,+15555555555
```

***

### Map columns

After uploading your file, Chatbase automatically matches your file headers to contact fields. Headers are matched to a field's key or label, ignoring upper and lower case.

Supported fields include:

* External ID
* Name
* Email
* Phone
* Custom attributes

You can manually adjust mappings using the dropdown menus.

> **Important**
>
> External ID is required. You must map a column to **External ID** before continuing.

#### Mapping rules

* Each CSV header can only be mapped to one field
* Custom attributes appear automatically during mapping
* Unmapped columns are ignored during import

#### Value formats

| Field type | What to enter |
| - | - |
| Phone | Include the country code, for example `+15555555555`. The number is saved exactly as typed. |
| Boolean attribute | `true`, `1`, or `yes` for true, and `false`, `0`, or `no` for false (any case). Other values are stored as text. |
| Number attribute | A number. Other values are stored as text. |
| Date attribute | Use `YYYY-MM-DD`, for example `2025-01-01`, the format the template uses. Other formats may be saved as plain text instead of a date. |

> [!TIP]
>
> Phone numbers in `+15555555555` form also help Chatbase match people who message your AI agent on WhatsApp to their contact.

***

### Review and confirm

Before importing, Chatbase displays a paginated preview table with all mapped rows.

Each row is validated against existing contacts and duplicate values.

#### Duplicate handling

| Condition | Result |
| - | - |
| Duplicate External ID in the file | Row is blocked |
| Duplicate email or phone in the file | Row is blocked |
| Email or phone already exists in another contact | Row is blocked |
| External ID already exists | Row is marked as **Update** to update the existing contact |
| Missing External ID | Row is automatically excluded |

Rows marked as **Update** will update the existing contact with the same External ID.

You can hover over warning icons or the **Update** badge to see more details, including which fields will change.

> **Note**
>
> Phone numbers are normalized to E.164 format before duplicate checks are performed. The number itself is saved as you typed it.

#### Row selection

You can:

* Select individual rows
* Deselect rows you do not want to import
* Use the **Select all** checkbox

***

### Completing the Import

After the import completes, Chatbase displays the import results: how many contacts were imported and how many failed, for example "98 imported, 2 failed".

Failed rows are listed in a table with the **Row**, **External ID**, and **Error** for each one. Example error:

```text theme={null}
A contact with this email already exists
```

To fix failed rows:

1. Click **Download failed rows** to save `failed-contacts.csv`. It lists the row number, External ID, and error for each failed row, but no contact data.
2. Correct those rows in your original file.
3. Import a file with just the corrected rows.

***

## Import errors

| Message | When it appears | What to do |
| - | - | - |
| "File is too large. Maximum size is 5 MB." | Choosing the file | Split the file into smaller files. |
| "File has {n} rows. Maximum is 1000 per upload." | Choosing the file | Split the file into files of 1,000 rows or fewer. |
| "Unsupported file type. Please upload a .csv or .xlsx file." | Choosing the file | Save the file as `.csv` or `.xlsx`. |
| "File is empty or has no data rows." | Choosing the file | Add at least one row below the header row. |
| "No headers found in the file." | Choosing the file | Put the column headers in the first row. |
| "Failed to parse CSV file." | Choosing the file | Check the file is a comma-separated CSV. |
| "The file has no sheets." or "Failed to read the file. Make sure it is a valid Excel (.xlsx) file." | Choosing the file | Re-save the workbook as `.xlsx`. |
| "Duplicate External ID in file", "Duplicate email in file", or "Duplicate phone in file" | Review | Keep one row per External ID, email, and phone number. |
| "Email already exists" or "Phone already exists" | Review | Another contact already uses that value. Change it, or update that contact instead. |
| "{n} missing External ID" | Review | Fill in the External ID for those rows. |
| "{n} row(s) could not be parsed and will be skipped" | Review | Check those rows for formatting problems. |
| "No valid contacts to import" | Review | Fix the flagged rows, then try again. |
| "A contact with this email already exists" or "A contact with this value already exists" | Results | Another contact already uses that email or value. |
| "Failed to import row" | Results | Download the failed rows, fix them, and import them again. |

"Will update existing contact" in the review step isn't an error. It means the row's External ID matches an existing contact.

***

## Add a single contact

Contacts can also be added individually.

Go to **Contacts** and click **Add contact**.

The form includes:

* External ID
* Name
* Email
* Phone
* Any Custom attributes

> **Important**
>
> External ID is required when creating a contact manually.

***

## Delete contacts

Contacts are deleted from the **Contacts** page in the dashboard. There is no cap on how many you can remove at once.

**1. Select the contacts**

Tick individual rows, or use the checkbox in the table header to select every contact on the current page. A banner then confirms what you have, such as **All 20 contacts on this page are selected**, next to a **Select all N contacts** button that widens the selection to every contact across every page.

**2. Delete them**

A toolbar appears at the bottom of the page with the number of contacts selected and a **Delete** button. The **×** beside it clears the selection without deleting anything.

> [!TIP]
>
> **Rows per page**, at the bottom left of the table, sets how many contacts are shown at a time, which is also how many the header checkbox covers. Raise it to select more per page, or use **Select all N contacts** to ignore paging entirely.

> [!WARNING]
>
> Deleting a contact is permanent: "They are removed from this agent immediately and cannot be restored." Contacts can't be exported from the dashboard, so if you need a copy, fetch them first with the [list contacts API](https://chatbase.co/docs/api-reference/v1/contacts/get-contacts-for-a-chatbot.md) (up to 1,000 per page).

***

## Custom attributes

Custom attributes allow you to store additional information about contacts.

Manage them from **Contacts > Manage attributes**.

### Supported attribute types

* Text
* Number
* Boolean
* Date

### Naming rules

Each attribute has a **Name** and an optional **Label**:

* **Name** is the identifier for the attribute. It must start with a letter or underscore and can only contain letters, numbers, underscores, and hyphens. Spaces are turned into underscores as you type.
* **Label** is the name shown in the contacts table and used as the attribute's column header in the CSV template.

For example, an attribute named `loyalty_tier` with the label **Loyalty tier**.

### Behavior

* Custom attributes appear during import mapping
* Custom attributes appear in the contacts table
* Archived attributes are hidden from forms
* Archived attribute data is preserved

***

## Frequently asked questions

> [accordion] How many contacts can I import at once?
>
> Up to 1,000 rows and 5 MB per file. For more, split your list into several files. There's no limit on the total number of contacts per AI agent.

> [accordion] Can I export contacts to a CSV?
>
> Not from the dashboard. Use the [list contacts API](https://chatbase.co/docs/api-reference/v1/contacts/get-contacts-for-a-chatbot.md), which returns up to 1,000 contacts per page.

> [accordion] How do I retry rows that failed to import?
>
> Click **Download failed rows** on the results screen to see each failed row and its error. Fix those rows in your original file and import them again.

> [accordion] Do phone numbers need a country code?
>
> The import accepts numbers without one and saves them as typed. Including the country code, such as `+15555555555`, is recommended so WhatsApp messages can be matched to the contact.

> [accordion] Why are my columns not splitting correctly?
>
> The CSV must be comma-separated. Files that use semicolons, which some spreadsheet apps export by default, are read as one column. Re-export as a comma-separated CSV in UTF-8.

> [accordion] What format should dates be in?
>
> Use `YYYY-MM-DD`, such as `2025-01-01`, the format the CSV template uses. Other formats may not be read as dates.


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