Articles on: Contacts & CRM

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 → best for one-time migrations and bulk updates
Existing contact updates → useful when importing the same profiles again
REST API → best for backend imports and synchronization
Integrations and 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, then open Contacts → Actions → Import Contact Profiles.

Import contact profiles action in Crisp Contacts

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

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

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.

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 for the full $crisp method reference.

Updated on: 03/05/2026

Was this article helpful?

Thank you!