Import Guide - Relaticle Documentation                 [ Skip to main content ](#main-content)= 768) mobileMenu = false">  [                                                         ](https://relaticle.com)

  [ Features ](https://relaticle.com/#features) [ Pricing ](https://relaticle.com/pricing) [ Documentation ](https://relaticle.com/docs) [  Discord  ](https://relaticle.com/discord)  [ Sign In ](https://relaticle.com/login) [ Start for free ](https://relaticle.com/register)

  [                                                         ](https://relaticle.com)

  [ Features ](https://relaticle.com/#features) [ Pricing ](https://relaticle.com/pricing) [ Contact ](https://relaticle.com/contact) [ Docs ](https://relaticle.com/docs)

  [ Sign In ](https://relaticle.com/login) [ Start for free ](https://relaticle.com/register)

    Documentation
-----------------

 [ Getting Started ](https://relaticle.com/docs/getting-started) [ Import Guide ](https://relaticle.com/docs/import) [ Developer Guide ](https://relaticle.com/docs/developer) [ Self-Hosting Guide ](https://relaticle.com/docs/self-hosting) [ MCP Server ](https://relaticle.com/docs/mcp) [ API Reference ](https://relaticle.com/docs/api)

  [\#](#import-guide "Permalink")Import Guide
===========================================

Relaticle's import wizard lets you bulk import data from CSV files into your CRM.

[\#](#supported-entities "Permalink")Supported Entities
-------------------------------------------------------

- **Companies** - Organizations and accounts
- **People** - Contacts linked to companies
- **Opportunities** - Deals and sales pipeline
- **Tasks** - Action items and to-dos
- **Notes** - Meeting notes and observations

---

[\#](#quick-start "Permalink")Quick Start
-----------------------------------------

### [\#](#file-requirements "Permalink")File Requirements

RequirementValueFormatCSV (comma-separated values)EncodingUTF-8Max Rows10,000 per fileMax Size10MBHeadersRequired in first row**Tip**: In Excel, use "Save As" → "CSV UTF-8 (Comma delimited)".

### [\#](#required-fields "Permalink")Required Fields

EntityRequiredCompaniesNamePeopleNameOpportunitiesNameTasksTitleNotesTitle---

[\#](#the-4-step-process "Permalink")The 4-Step Process
-------------------------------------------------------

### [\#](#step-1-upload "Permalink")Step 1: Upload

1. Navigate to the entity list (Companies, People, etc.)
2. Click **Import**
3. Select your CSV file
4. Review file info (columns found, row count)

### [\#](#step-2-map-columns "Permalink")Step 2: Map Columns

The wizard automatically matches CSV columns to Relaticle fields by comparing column names.

**Auto-Mapping Examples**:

- "company\_name", "Company", "Organization" → Company Name
- "email", "Email Address", "contact\_email" → Email
- "custom\_fields\_industry" → Industry custom field

**Manual Adjustment**: Click any dropdown to change the mapping or select "Don't Import" to skip a column.

**Linking Related Records**: When mapping a column to a relationship (like Company or Contact), a submenu appears where you choose the match method — by Record ID, Domain, Email, or Name.

### [\#](#step-3-review-values "Permalink")Step 3: Review Values

The wizard analyzes your data and flags validation issues.

**Actions You Can Take**:

- **Fix**: Enter a corrected value to apply to all rows with that value
- **Skip**: Click the skip icon to exclude a value. The row will still be imported, but this field will be empty
- **Change Date Format**: For date columns, select the correct format if auto-detection is uncertain

### [\#](#step-4-preview--import "Permalink")Step 4: Preview & Import

Review what will happen:

- **New**: Records that will be created
- **Update**: Existing records that will be modified

Click **Start Import** when ready. Large imports process in the background.

---

[\#](#date-format-detection "Permalink")Date Format Detection
-------------------------------------------------------------

The import wizard automatically detects date formats in your CSV and handles three common formats:

### [\#](#supported-formats "Permalink")Supported Formats

FormatPatternExample**ISO**YYYY-MM-DD2024-05-15**European**DD/MM/YYYY or DD-MM-YYYY15/05/2024, 15 May 2024**American**MM/DD/YYYY or MM-DD-YYYY05/15/2024, May 15th 2024### [\#](#how-detection-works "Permalink")How Detection Works

The wizard analyzes your date values to determine the format:

1. **Unambiguous dates**: When the day is > 12, the format is clear

    - `31/01/2024` → Must be European (DD/MM)
    - `01/31/2024` → Must be American (MM/DD)
2. **Ambiguous dates**: When both positions are ≤ 12

    - `01/02/2024` → Could be Jan 2 or Feb 1
    - You'll see a warning and can select the correct format
3. **ISO dates**: Always unambiguous

    - `2024-01-15` → Clearly January 15

### [\#](#selecting-date-format "Permalink")Selecting Date Format

In Step 3 (Review Values), date columns show a format dropdown:

- **High confidence**: Format auto-selected, dropdown shows detected format
- **Low confidence**: Warning icon appears, select the correct format manually

**Example**: If your CSV has `01/02/2024` and you know it means February 1st (European), select "European" from the dropdown.

---

[\#](#matching-existing-records "Permalink")Matching Existing Records
---------------------------------------------------------------------

When you map a field that uniquely identifies records (like email or domain), the wizard automatically finds matches in your existing data. How matching works depends on the match method you choose in Step 2.

### [\#](#match-methods "Permalink")Match Methods

MethodBehaviorAvailable For**Record ID**Updates the exact record. Skips if ID not found.All entities**Domain**Finds existing company by domain, or creates new.Companies**Email**Finds existing person by email, or creates new.People**Phone**Finds existing person by phone, or creates new.People**Name**Always creates a new record (names aren't unique).Companies, People### [\#](#what-happens-in-preview "Permalink")What Happens in Preview

After the wizard resolves matches, Step 4 shows the result:

- Rows matched to existing records → **Update**
- Rows with no match (or using Name matching) → **Create new**
- Rows with an ID that doesn't exist → **Skip**

### [\#](#no-unique-field-mapped "Permalink")No Unique Field Mapped?

If you don't map any matchable field, the wizard shows a warning: all rows will be created as new records. You can go back and map a field, or continue anyway.

### [\#](#update-behavior "Permalink")Update Behavior

When the wizard matches a CSV row to an existing record, updates follow these rules:

- **Blank fields are ignored**: If a CSV column is empty, the existing value is preserved. You don't need to fill in every column — only include the fields you want to change.
- **Multi-value fields merge**: For fields that accept multiple values (emails, phone numbers, tags, multi-select), new values are merged with existing ones rather than replacing them.
- **Duplicates within the CSV**: If the same record appears multiple times in your file (e.g., two rows with the same email), the second row updates the first instead of creating a duplicate.

---

[\#](#id-based-updates "Permalink")ID-Based Updates
---------------------------------------------------

For precise updates, include Record IDs from a previous export.

### [\#](#workflow "Permalink")Workflow

1. **Export** your records (includes `id` column with ULIDs)
2. **Modify** the CSV, keeping the `id` column intact
3. **Re-import** - rows with valid IDs update those exact records

### [\#](#example "Permalink")Example

```
id,name,custom_fields_industry
01KCCFMZ52QWZSQZWVG0AP704V,Acme Corporation,Software
01KCCFN1A8XVQR4ZFWB3KC5M7P,TechStart Inc,Hardware

```

**Preview shows**:

- Rows with valid IDs → "Update"
- Rows without IDs → "New"

### [\#](#mixed-imports "Permalink")Mixed Imports

You can create and update in the same file:

```
id,name
01KCCFMZ52QWZSQZWVG0AP704V,Update This Company
,New Company (blank ID = create new)

```

---

[\#](#entity-specific-details "Permalink")Entity-Specific Details
-----------------------------------------------------------------

### [\#](#companies "Permalink")Companies

**Fields**:

- `name` (required) - Company name
- `account_owner_email` - Team member email for ownership
- Custom fields with `custom_fields_` prefix

**Matching**: By domain (`custom_fields_domains`) or Record ID

```
name,account_owner_email,custom_fields_industry,custom_fields_domains
Acme Corporation,owner@yourcompany.com,Technology,acme.com

```

### [\#](#people "Permalink")People

**Fields**:

- `name` (required) - Person's full name
- Custom fields with `custom_fields_` prefix

**Relationships** (mapped in Step 2):

- **Company** - Link to a company. Match by Record ID, Domain, or Name (creates new).

**Matching**: By email (`custom_fields_emails`), phone (`custom_fields_phone_number`), or Record ID

```
name,company,custom_fields_emails,custom_fields_title
John Doe,acme.com,john@acme.com,CEO
Jane Smith,acme.com,jane@acme.com,CTO

```

**Note**: In the example above, the `company` column is mapped to the Company relationship. In Step 2, choose "Match by Domain" so `acme.com` links to the existing company. If you choose "Match by Name", a new company will always be created.

### [\#](#opportunities "Permalink")Opportunities

**Fields**:

- `name` (required) - Opportunity name
- Custom fields (amount, stage, close\_date, etc.)

**Relationships** (mapped in Step 2):

- **Company** - Link to a company. Match by Record ID, Domain, or Name.
- **Contact** - Link to a person. Match by Record ID, Email, Phone, or Name.

**Matching**: Record ID only

```
name,company,contact,custom_fields_amount,custom_fields_stage
Q1 Enterprise Deal,acme.com,john@acme.com,50000,Proposal

```

**Note**: Map the `company` column to Company → Domain and the `contact` column to Contact → Email for the best matching results.

### [\#](#tasks "Permalink")Tasks

**Fields**:

- `title` (required) - Task title

**Relationships** (mapped in Step 2):

- **Companies** - Link to one or more companies
- **People** - Link to one or more people
- **Opportunities** - Link to one or more opportunities
- **Assignees** - Assign to team members by email

**Matching**: Record ID only

```
title,assignee,company,custom_fields_due_date,custom_fields_priority
Follow up with client,assignee@yourcompany.com,acme.com,2024-03-15,High

```

**Note**: The `assignee` column is mapped to the Assignees relationship in Step 2. Choose "Match by Email" to link to team members by their email address.

### [\#](#notes "Permalink")Notes

**Fields**:

- `title` (required) - Note title

**Relationships** (mapped in Step 2):

- **Companies** - Link to one or more companies
- **People** - Link to one or more people
- **Opportunities** - Link to one or more opportunities

**Matching**: None. Notes are always created as new records.

```
title,company
Meeting Notes,acme.com

```

---

[\#](#custom-fields "Permalink")Custom Fields
---------------------------------------------

### [\#](#column-naming "Permalink")Column Naming

Use the prefix `custom_fields_` followed by the field code:

```
custom_fields_industry
custom_fields_emails
custom_fields_website

```

Find field codes in **Settings → Custom Fields** under the "Code" column.

### [\#](#field-type-formatting "Permalink")Field Type Formatting

TypeFormatExampleTextPlain text`Technology`NumberNumeric, no symbols`50000`DateYYYY-MM-DD, DD/MM/YYYY, or MM/DD/YYYY`2024-03-15`EmailValid email(s), comma-separated`john@acme.com,jane@acme.com`SelectExact option label`Enterprise`Multi-SelectComma-separated labels`CRM,Analytics`Booleantrue/false, yes/no, 1/0`true`---

[\#](#csv-best-practices "Permalink")CSV Best Practices
-------------------------------------------------------

### [\#](#do "Permalink")Do

- Include headers in the first row
- Save as UTF-8 encoding
- Quote values containing commas: `"Last, First"`
- Use consistent formatting within each column
- Test with a small sample first (5-10 rows)

### [\#](#dont "Permalink")Don't

- Use Excel's default encoding (use "CSV UTF-8")
- Mix date formats in the same column
- Include currency symbols in numbers: use `50000` not `$50,000`
- Leave empty rows at the end of the file

### [\#](#date-formatting-tips "Permalink")Date Formatting Tips

The wizard accepts multiple date formats, but consistency is key:

**Good** (pick one format per column):

- `2024-03-15` (ISO - recommended)
- `15/03/2024` (European)
- `03/15/2024` (American)

**Avoid**:

- Mixing formats: `2024-03-15` and `03/15/2024` in same column
- Two-digit years without context: `03/15/24`

---

[\#](#troubleshooting "Permalink")Troubleshooting
-------------------------------------------------

### [\#](#upload-issues "Permalink")Upload Issues

ProblemSolutionFile too largeSplit into files under 10,000 rows eachInvalid formatRe-save as "CSV UTF-8" from ExcelUpload failsCheck internet, try smaller file### [\#](#mapping-issues "Permalink")Mapping Issues

ProblemSolutionColumn not auto-mappedManually select from dropdownCustom field missingCheck field code in Settings → Custom FieldsRequired field redMap a CSV column to the required field### [\#](#validation-issues "Permalink")Validation Issues

ProblemSolutionInvalid emailFix email format: `user@domain.com`Invalid dateUse a supported format (ISO, European, or American)Invalid IDRe-export to get fresh Record IDsUnknown select optionUse exact option label from field settings### [\#](#import-issues "Permalink")Import Issues

ProblemSolutionStuck at "Processing"Large imports take time; check back in a few minutesSome rows failedDownload failed rows, fix errors, re-importUnexpected duplicatesMap a unique field (email, domain, or ID) in Step 2---

[\#](#faq "Permalink")FAQ
-------------------------

**Can I import multiple entity types at once?**No, each entity imports separately. When importing People, related companies can be auto-created if you choose "Match by Name" for the Company relationship.

**What happens if my import fails halfway?**Successful rows remain. Failed rows can be downloaded, fixed, and re-imported.

**Can I undo an import?**No automatic undo. Test with small samples first and backup important data.

**How do I update existing records?**Include the `id` column from a previous export. For People, email or phone matching also works. For Companies, domain matching works.

**What date formats are supported?**ISO (YYYY-MM-DD), European (DD/MM/YYYY), and American (MM/DD/YYYY). The wizard auto-detects the format.

**What if a date is ambiguous (like 01/02/2024)?**You'll see a warning. Use the format dropdown to select European or American interpretation.

**What's the maximum file size?**10MB or 10,000 rows per file. Split larger datasets into multiple imports.

**Do imports run in real-time?**Small imports complete immediately. Large imports process in the background with progress updates.

**How does the wizard match existing records?**It depends on which match method you choose in Step 2. Record ID updates exact records. Domain and email find existing records or create new ones. Name always creates new records.

**Can Notes be updated via import?**No. Notes are always created as new records regardless of whether you include an ID column.

---

[\#](#csv-templates "Permalink")CSV Templates
---------------------------------------------

Export existing records to get perfectly formatted templates with all your custom fields.

### [\#](#company-template "Permalink")Company Template

```
id,name,account_owner_email,custom_fields_industry,custom_fields_domains
,Acme Corporation,owner@yourcompany.com,Technology,acme.com

```

### [\#](#people-template "Permalink")People Template

```
id,name,company,custom_fields_emails,custom_fields_title
,John Doe,acme.com,john@acme.com,CEO

```

**Tip**: Map the `company` column to Company → Domain to link to existing companies. Choose "Match by Name" only when you want to create new companies.

### [\#](#opportunity-template "Permalink")Opportunity Template

```
id,name,company,contact,custom_fields_amount,custom_fields_stage
,Q1 Enterprise Deal,acme.com,john@acme.com,50000,Proposal

```

**Tip**: Map `company` to Company → Domain and `contact` to Contact → Email to link to existing records.

### [\#](#task-template "Permalink")Task Template

```
id,title,assignee,custom_fields_due_date,custom_fields_priority
,Follow up with client,assignee@yourcompany.com,2024-03-15,High

```

**Tip**: Map the `assignee` column to Assignees → Email to assign tasks to team members.

### [\#](#note-template "Permalink")Note Template

```
title,company
Meeting Notes,acme.com

```

**Tip**: Export any existing record to get a template with all your workspace's custom fields already included.

 [  Edit this page on GitHub ](https://github.com/Relaticle/relaticle/edit/main/packages/Documentation/resources/markdown/import-guide.md)

  ###    On this page

 - [ Supported Entities ](#supported-entities)
- [ Quick Start ](#quick-start)
- [ The 4-Step Process ](#the-4-step-process)
- [ Date Format Detection ](#date-format-detection)
- [ Matching Existing Records ](#matching-existing-records)
- [ ID-Based Updates ](#id-based-updates)
- [ Entity-Specific Details ](#entity-specific-details)
- [ Custom Fields ](#custom-fields)
- [ CSV Best Practices ](#csv-best-practices)
- [ Troubleshooting ](#troubleshooting)
- [ FAQ ](#faq)
- [ CSV Templates ](#csv-templates)

   [                                                         ](https://relaticle.com) The open-source CRM built for AI agents. Self-hosted. No per-seat pricing. Yours to own.

  [  ](https://github.com/Relaticle/relaticle) [  ](https://x.com/relaticle) [  ](https://www.linkedin.com/company/relaticle)

 ###  Quick Links

- [ Home ](https://relaticle.com)
- [ Pricing ](https://relaticle.com/pricing)
- [ Documentation ](https://relaticle.com/docs)
- [ Features ](https://relaticle.com/#features)

 ###  Support & Legal

- [ Privacy Policy ](https://relaticle.com/privacy-policy)
- [ Terms of Service ](https://relaticle.com/terms-of-service)
- [ Contact Us ](https://relaticle.com/contact)

 © 2026 Relaticle. All rights reserved.