> ## Knowledge Base Index
> Fetch the complete knowledge base index at: https://help.chrisp.chat/sitemap.xml
> Use this file to discover available pages before exploring further.
> Pure-Markdown content can be obtained by appending a '.md' suffix to the content URLs listed in the sitemap (without the trailing slash).

# How to import Contact profiles

__Learn how to import contacts into Crisp using CSV files, API routes, the Web SDK, native integrations, or automation tools.__

The fastest option for most migrations is a CSV import from the ****Contacts**** section. For ongoing synchronization, use the ****REST API****, ****Web SDK****, or integrations so Crisp stays aligned with your own product, store, or CRM.

__You can import or update contacts in several ways:__

* [CSV import](#1-import-contacts-with-a-csv-file) → best for one-time migrations and bulk updates
* [Existing contact updates](#1-update-existing-contacts-from-an-import) → useful when importing the same profiles again
* [REST API](#1-import-or-update-contacts-with-the-rest-api) → best for backend imports and synchronization
* [Integrations and Web SDK](#1-keep-contacts-synchronized-with-integrations-and-the-web-sdk) → best for ongoing product, CRM, or website updates

---

# Import contacts with a CSV file

#### Prepare your CSV

Start by gathering your contacts in a CSV file. Your column names do not need to match Crisp fields exactly, as you will map them during the import.

| Crisp lets you map your CSV columns to Crisp fields during the import, so you can keep your original export format as long as the values themselves are valid.

#### Open the import tool

Go to [**Crisp**](https://app.crisp.chat), then open ****Contacts → Actions → Import Contact Profiles****.

![Import contact profiles action in Crisp Contacts](https://storage.crisp.chat/users/helpdesk/website/-/f/6/8/4/f68417e2a1c45000/2887519b-6909-48ca-adf8-dabfef_hvgrjv.png)

#### Upload and map your data

Upload your CSV, then map each column to the matching Crisp field.

|| If your CSV does not contain a header row with field names such as `` `email` ``, `` `name` ``, `` `ip` ``, or `` `company` ``, enable ****Skip header**** before continuing.

By default, Crisp uses a comma as the CSV separator. Make sure the separator selected during import matches the separator used in your file.

__Required and recommended formats:__

* ****Email**** → required
* ****First name and last name****, or ****Full name**** → strongly recommended; otherwise, contact names may be inferred from email addresses
* ****Segments**** → separate multiple values with a pipe (`` `|` ``), comma (`` `,` ``), or space (` `)
* ****Country**** → use a country code, such as `` `US` ``, not a country name
* ****City**** → use the full city name
* ****Creation date**** and ****Last Active date**** → use ISO 8601, such as `` `2020-08-14T14:09:10-02:00` ``, or a UNIX timestamp in seconds or milliseconds, such as `` `1694070416` `` or `` `1694070416000` ``

#### Map custom data

Crisp includes predefined fields such as ****Email****, ****Username****, ****Segments****, and ****Company****. You can also import your own fields, such as `` `user_id` ``, `` `subscription_plan` ``, or other internal variables.

| If a CSV column is named `` `data.my_key` ``, Crisp automatically imports it as custom data named `` `my_key` ``.

To create a custom data key manually, click the custom data key button during mapping.

![Create a custom data key during contact import](https://storage.crisp.chat/users/helpdesk/website/-/b/a/3/d/ba3d166581a93000/85d08523-6167-47ba-aabb-795047_y7vgix.png)

__Good custom data keys are short, simple, and easy to reuse:__

* `` `${color}[#33c620](✔)` `` `` `user_id` ``
* `` `${color}[#33c620](✔)` `` `` `lifetime_value` ``
* `` `${color}[#33c620](✔)` `` `` `ltv` ``
* `` `${color}[#33c620](✔)` `` `` `app_version_code` ``

__Avoid keys that contain spaces or special characters:__

* `` `${color}[#ec491a](✘)` `` `` `Company Name` ``
* `` `${color}[#ec491a](✘)` `` `` `$ltv` ``
* `` `${color}[#ec491a](✘)` `` `` `is_subscribed?` ``
* `` `${color}[#ec491a](✘)` `` [`` `user.name` ``](https://user.name)

|| Prefer lowercase keys. Avoid spaces and special characters, except underscores (`` `_` ``) and dashes (`` `-` ``).

After creating the key, assign your CSV column to it.

![Assign a custom data key during contact import](https://storage.crisp.chat/users/helpdesk/website/-/2/d/4/a/2d4a929eb7b54800/1c9b31fb-2baf-4428-8f1c-b27aca_1lcrqno.png)

#### Run the import safely

Small imports usually complete quickly. Larger imports, such as 20,000+ profiles, can take a few minutes.

||| Before importing a large list, run a test import with 1 or 2 contacts. This helps you confirm that fields, segments, companies, and custom data are mapped exactly as expected.

#### Troubleshoot import errors

Most import issues come from file formatting, missing required values, or temporary limits.

__If the import fails, check the following first:__

* ****CSV separator**** → confirm that the selected separator matches your file
* ****Headers**** → enable ****Skip header**** only when the first row is not a header row
* ****Required fields**** → confirm that every contact has an email address
* ****File size**** → split large files into smaller batches when needed; files must stay below 10 MB each
* ****Browser network errors**** → open your browser developer tools and check the ****Network**** tab for failed requests, such as `` `400` `` errors
* ****Temporary rate limits**** → if you are updating many existing contacts, wait and try again, or split the import into smaller batches

---

# Update existing contacts from an import

If you import a profile that already exists with the same email address, Crisp updates that profile instead of simply creating a duplicate.

__When an imported contact already exists:__

* ****Existing custom data**** → updated when the import provides a new value; leave the value empty to explicitly clear an existing custom data value
* ****New custom data**** → added to the profile
* ****New segments**** → added to the existing segments; segments cannot be explicitly deleted from a CSV import
* ****Employment information**** → merged
* ****Company information**** → merged
* ****Nickname, avatar, and similar profile fields**** → overwritten by the imported value

---

# Import or update contacts with the REST API

Use the ****REST API**** when you want to create or update contacts from your backend, synchronize another system with Crisp, or automate a larger import process.

#### Create a contact profile

Use ****Add New People Profile**** to create a profile.

****Endpoint****: `` `POST /v1/website/{website_id}/people/profile` ``

```
{  "email": "camille@crisp.chat",  "company": {    "name": "Crisp"  },  "person": {    "locales": [      "en-GB",      "fr-FR"    ],    "profiles": [],    "geolocation": {      "country": "FR",      "region": "CVL",      "city": "Nantes"    },    "nickname": "Camille",    "timezone": -120,    "avatar": "https://crisp-sandbox.netlify.app/images/avatars/harkos.png"  },  "segments": [    "crispy",    "lead"  ]}
```

#### Update contact custom data

Use ****Update People Data**** when you want to merge new custom data keys with the contact data that already exists.

****Endpoint****: `` `PATCH /v1/website/{website_id}/people/data/{people_id}` ``

```
{  "data": {    "subscription": "Essentials",    "newsletter": "marketing",    "order_id": "TX00075643ZA"  }}
```

||| ****Save People Data**** replaces the full contact data object. Use ****Update People Data**** when you only want to merge new keys without replacing everything else.

#### API implementation checklist

Before sending requests, make sure your integration is authenticated, has the right ****website ID****, and sends contact data in the expected request body format.

You can find the full route details in the [Crisp REST API reference](https://docs.crisp.chat/references/rest-api/v1/).

---

# Keep contacts synchronized with integrations and the Web SDK

#### Native integrations and automation tools

Some native integrations include contact synchronization options. Depending on your stack, this can help you keep Crisp aligned with tools such as ****Pipedrive****, ****HubSpot****, ****Zoho****, ****Salesforce****, ****Shopify****, ****WooCommerce****, or ****PrestaShop****.

You can also use automation tools such as ****Zapier****, ****Make****, or ****n8n**** to create or update Crisp contacts when another app triggers an event.

#### Web SDK updates for authenticated visitors

Use the ****Crisp Web SDK**** when your website already knows the authenticated visitor and you want to attach identity or company data to their current Crisp session.

```
$crisp.push(["set", "user:email", ["john.doe@crisp.chat"]]);
```

```
$crisp.push(["set", "user:phone", ["+14152370800"]]);
```

```
$crisp.push(["set", "user:nickname", ["John Doe"]]);
```

```
$crisp.push(["set", "user:avatar", ["https://example.com/avatar.jpg"]]);
```

```
$crisp.push(["set", "user:company", ["Crisp", {  url: "https://crisp.chat/",  description: "Crisp company",  employment: ["CTO", "Engineer"],  geolocation: ["FR", "Nantes"]}]]);
```

The Web SDK is best for updating the current visitor while they are using your website. For backend synchronization or bulk imports, use the ****REST API**** instead.

| Want to go deeper? Read the [Crisp Web SDK guide](https://docs.crisp.chat/guides/chatbox-sdks/web-sdk/dollar-crisp/) for the full `` `$crisp` `` method reference.