> ## Knowledge Base Index
> Fetch the complete knowledge base index at: https://help.crisp.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

---

# ${color}[#0080dd](Import contacts with a CSV file)

#### ${color}[#445055](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.

#### ${color}[#445055](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/-/8/7/a/e/87ae2703583ac800/cleanshot-2026-02-02-at-114702_1yhshdc.png =1000xauto)

#### ${color}[#445055](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`

#### ${color}[#445055](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/87ae2703583ac800/cleanshot-2025-03-03-at-113411_1np9lry.png =1000xauto)

__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`

|| 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/87ae2703583ac800/cleanshot-2025-03-03-at-113440_1ofzes.png =1000xauto)

#### ${color}[#445055](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.

#### ${color}[#445055](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

---

# ${color}[#0080dd](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

---

# ${color}[#0080dd](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.

#### ${color}[#445055](Create a contact profile)

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

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

```json
{
  "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"
  ]
}
```

#### ${color}[#445055](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}`

```json
{
  "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.

#### ${color}[#445055](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/).

---

# ${color}[#0080dd](Keep contacts synchronized with integrations and the Web SDK)

#### ${color}[#445055](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.

#### ${color}[#445055](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.

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

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

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

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

```javascript
$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.