CSV & Notes Import

CSV import and Notes import are two different tools. They are opened from the same group view, but they solve different problems:

Tool	Use it for	What it adds
Import CSV	Moving structured records from a spreadsheet or another CRM	Records, field values, relationships, and group placement
Import Notes	Bringing in a history of calls, meetings, emails, or internal comments	Notes attached to the right records, with optional dates, authors, and privacy

The safest way to use either tool is to test a small sample first. A full migration can involve field creation, choice values, relationships, group placement, record matching, permissions, and validation. If the data is business-critical, large, or difficult to map, contact support before importing so the source and destination can be reviewed together.

Important: CSV import is mainly a record-creation and organisation tool. When the importer finds an existing record through the matching field, it does not overwrite that record with the incoming row. It avoids creating a duplicate and can place the existing record in the selected destination group. If you need to update existing field values in bulk, contact support before importing.

Use cases

These imports fit the common small-business sales process: finding prospects, running outreach, holding meetings, sending proposals, and keeping the CRM as the shared record of what happened.

CSV import use cases

Situation	What to import	Practical outcome
Starting a new workspace	A lead list with names, companies, email addresses, and stages	The sales team can begin outreach without retyping every lead
Moving from another CRM	Companies, contacts, opportunities, and their relationships	Existing structured sales data is brought into the new workspace in a planned order
Preparing an outreach campaign	Prospects, owner, source, segment, and campaign fields	A group or view can hold the campaign population and the team can work from one list
Loading several related files	Separate company, contact, and opportunity files	Records can be linked by stable values such as company name or email, when the mapping is correct
Adding a custom sales process	A file containing custom fields such as lead source, product interest, region, or qualification status	The workspace can reflect the founder’s or team’s own process instead of forcing a generic pipeline
Handing work to another salesperson	Records plus owner or assignment fields	The next person receives a structured list with enough context to follow up

Notes import use cases

Situation	What to import	Practical outcome
Recovering call history	One note per call, with a contact email or other matching value	The sales history appears on the relevant contact records
Moving meeting notes	Notes from previous meetings with dates and authors	A founder or salesperson can see what was discussed before the next meeting
Adding post-campaign context	Responses, objections, next steps, or handoff notes	Outreach results stay with the record instead of remaining in a separate spreadsheet
Importing company-level history	Notes keyed by a text field on a related company record	Notes can be found through a related text field when the relationship is already usable for matching
Keeping sensitive internal context	Internal notes with a default or row-level private setting	Sensitive information can be imported with a deliberate visibility choice
Preserving authorship	`owner_email` and `timestamp` columns	The note can retain who wrote it and when it was recorded, subject to workspace membership

Getting started

What you need before opening the importer

Prepare the following before you click Import / Export:

A backup copy of the original files. Keep it unchanged so you can compare the result or retry with a corrected mapping.
A destination group for each kind of record. For example, you might send companies to one group and a new outreach list to another.
A decision about the matching value. This is the value used to decide whether an incoming row refers to an existing record. A stable email address, customer ID, or other consistently formatted text value is usually safer than a person’s display name.
A list of fields that should be imported, skipped, or created.
A decision about privacy for notes. Imported notes are shared by default unless you select private-by-default or set is_private for individual rows.
Permission to edit the destination group and, if required, permission to create fields, groups, or choice values.

Who can start an import

The Import / Export control is available from a group view to a group owner, administrator, or editor who can edit records in that group. A viewer cannot start the import. The server checks permissions again when the import is submitted, so seeing a control is not a guarantee that every mapping action is allowed.

Creating fields, creating choice values, or creating groups also requires workspace editing access. If you can edit records but cannot create fields or groups, ask a workspace administrator or editor to prepare the destination structure first.

Supported files and basic limits

Both import tools accept CSV, Excel workbooks, and ZIP files containing CSV files. Each uploaded file can be up to 50 MB.

For CSV import, the first row must contain column names. The file must contain at least one data row. Column names must be non-empty and unique, ignoring differences in capitalisation. Remove title rows such as January Prospects above the real header row. A file whose headers all look like numbers or dates is also rejected because it usually means the header row was not selected correctly.

CSV import can combine up to five input files or parsed worksheets in one session. One file, everything inside accepts one file; Separate files supports multiple files, up to the importer limit. A ZIP must contain CSV files; a ZIP with no CSV files cannot be imported.

Notes import uses a fixed column format described below. It is not a general-purpose spreadsheet mapper.

Where to start

Open the group view that should be the starting point.
Click Import / Export.
Choose Import CSV for structured records, or Import Notes for historical notes.
Read the relevant section below before uploading the full file.

How to use it

Import structured records with CSV

Use this flow for records such as companies, people, opportunities, products, or custom record types. It can map columns, create fields where permitted, connect related records, route records to groups, validate values, and start a background migration task.

Step 1: Choose what the file represents

After choosing Import CSV, the first screen asks What are you importing? Select the main table or record type represented by the file, then click Continue.

Think of a table as a kind of record—such as “Companies” or “Contacts”—and a group as the working list where those records should appear. The table determines which fields and relationships are available for mapping. The group determines where the imported records can be worked on afterward.

Step 2: Choose the file shape

Choose the option that matches the source files:

Separate files: use this when each type has its own file, such as companies.csv and contacts.csv. This is the normal choice for a migration with related record types.
One file, everything inside: use this when one CSV has all of the data mixed together, with rows for every type of record living in the same file. This is useful when the source has been flattened into one file rather than separated into one file per record type.

Choose carefully. The file-shape choice affects whether the importer expects multiple files and whether it can merge files before mapping.

Step 3: Upload and check the source structure

Upload the CSV, Excel workbook, or ZIP file. For an Excel workbook, each worksheet is treated as a possible sheet to review. For a ZIP, only CSV files are considered.

Before continuing, check that:

the first row contains the real headers;
there are no duplicate headers such as two columns both called Email;
blank or decorative columns have been removed;
values are in the rows below the headers; and
the file is not larger than 50 MB.

If the source contains a title row, merged cells, or repeated headers in the middle of the file, correct the source and upload it again. These patterns make a spreadsheet look readable to a person but do not provide a reliable table for an importer.

When multiple files are uploaded, the importer shows a merge step. Select the main file, then explain how each additional file connects to it by choosing a source column and a target column.

For example:

contacts.csv might contain company_name;
companies.csv might contain name; and
those two columns can be used to connect a contact to a company.

The merge matching can ignore extra spaces and differences in capitalisation. It does not make two genuinely different values the same. Every uploaded file needs a connection, and duplicate source headers must be renamed before the merge can continue. Review the preview, then click Combine files & continue.

Do not connect files using a value that is blank, inconsistently spelled, or shared by many unrelated records. If two companies have the same name, use a more reliable identifier if one exists.

Step 5: Map source columns to destination fields

The header-mapping screen shows the incoming columns and suggested destination fields. Suggestions are based on the header name, but they are only suggestions. Confirm each important mapping yourself.

For each source column, choose one of these actions:

map it to an existing destination field;
choose Skip column when it is not needed; or
choose Create field when the destination needs a new field and you have workspace permission.

Use the sample values shown in the mapping screen to check that the meaning is correct. For example, do not map a source column called Owner to a free-text description field when the destination has a user field intended for assignment.

The importer prevents continuing when required destination fields are unmapped, when two source columns are mapped to the same destination field, or when no columns are mapped. A viewer or a user without workspace editing access may be able to review a mapping but may not be allowed to create fields.

Choice and multi-choice fields

For a select or multi-select field, map each incoming value to an existing choice, create a new choice, or skip the value. Check spelling and capitalisation before creating choices. Qualified, qualified, and QUALIFIED may represent the same business stage to a person but can become confusing separate options if imported carelessly.

If you choose to create options, the importer saves those options before the records are imported. Make sure the new choices are intentional because they become part of the destination field for future users.

Step 6: Set record matching and relationships

The Record Matching step controls two related decisions:

Which text field should be used to find an existing record; and
Which values should be used to build relationships between record types.

For each involved table, choose a text field that is stable and present in the source. The importer prioritises fields such as title, name, and email when suggesting a field, but check the choice yourself.

Example for a small sales migration:

Destination table	Incoming value used for matching	Relationship
Companies	Company name or a stable company ID	Parent record for contacts and opportunities
Contacts	Contact email or a stable contact ID	Person associated with a company and opportunity
Opportunities	Opportunity name plus another identifying field where available	Sales item connected to the company and contact

The relationship mapping needs values that actually identify the related record. A blank value cannot create a link. A common name may match the wrong record. Open several imported records after the task completes and verify both directions of important relationships.

Existing records are not overwritten

If an incoming row matches an existing record using the selected matching field, the importer skips creating a second copy. It does not use the incoming row to overwrite or bulk-update the existing record’s fields. The existing record can still be assigned to the selected destination group.

This means matching is a duplicate-prevention and relationship aid, not a spreadsheet update mechanism. If the purpose of the file is “change the stage, owner, or phone number for records that already exist,” stop and contact support before importing.

Step 7: Choose destination groups

The Where should records go? step lets you choose a destination group for each involved table. Use a group that represents the next working context—for example, “New outbound prospects,” “Active opportunities,” or a team handoff list.

If a selected group does not yet have a view for a table, the system can create a default view automatically. Make sure the selected group is the intended one before proceeding; group placement affects who finds and works the records afterward.

The setting Auto-assign me when user field is empty is enabled by default. With it enabled, an empty user or owner field can be assigned to the person running the import. Turn it off if an empty owner should remain unassigned for later routing.

Step 8: Review and validate the rows

The review screen is titled Review & Validate Data. Use its tabs to inspect:

All: every parsed row;
Valid: rows without blocking validation errors; and
Invalid: rows that need attention.

Validation can flag missing required values and malformed email addresses, URLs, phone numbers, text values, currencies, numbers, times, or dates. You can edit cells, add a row, delete selected rows, download selected rows, and hide empty or unmapped columns while reviewing.

Fix the source or correct the row in the review screen where appropriate. If you continue while error-level problems remain, rows with those errors are excluded from the import. Review the invalid rows before continuing so that an apparently successful task does not silently omit part of the file.

Warnings may still be allowed, but treat warnings as a reason to inspect the affected values rather than ignoring them automatically.

Step 9: Start and monitor the background import

When you start the import, the client sends the validated mapping and data to the server and receives an import task. The work then runs in the background. A start notification tells you to check the sidebar for progress.

The task moves through pending and processing states and can finish as completed, failed, or cancelled. The importer works in batches and saves checkpoints, so larger imports may take time. Refresh the affected group or view after completion and inspect representative companies, contacts, opportunities, custom fields, and relationships.

Cancellation stops remaining work but is not a rollback. Rows already written can remain in the workspace. If a mapping is wrong, cancel as soon as possible, record the task details, and contact support before attempting cleanup or a second full import.

CSV scenarios

Scenario: import a new outreach list

Suppose a founder has a spreadsheet of prospects with name, email, company, source, and stage.

Open the group that will hold the outreach list and choose Import / Export → Import CSV.
Select the contact or prospect table.
Choose One file, everything inside.
Upload the file and map name, email, source, and stage to the intended fields.
Use email as the matching field if it is consistently populated and unique.
Check select values such as stage before creating any new options.
Choose the outreach group and decide whether empty owner fields should auto-assign to you.
Import a small sample, inspect the result, then run the remaining rows.

This gives the sales team a clean working list for outreach. It does not update an existing contact merely because a new spreadsheet row contains a different stage or phone number.

Scenario: migrate companies and contacts from separate files

Suppose the source has companies.csv and contacts.csv.

Choose Separate files and upload both files.
Select the company file as the main file if contacts refer to companies.
Connect contacts.company_name to companies.name, or use a stable company ID if available.
Map the contact email as the contact matching value and the company ID or name as the company matching value.
Review the relationship mapping and group destination for each table.
Validate the rows and import a small sample.
Open a few company records and contact records to confirm that the links are correct before importing the full dataset.

If company names are not unique, do not assume the importer can infer the intended company. Clean the source or get help with the migration design first.

Scenario: load a custom sales process

Suppose the team tracks lead_source, region, product_interest, qualification_status, and next_step in addition to standard contact information.

Map standard columns to existing fields.
Create only the custom fields the team has agreed to keep.
For controlled stages or statuses, map values to a small, deliberate set of choices.
Skip temporary spreadsheet columns such as formulas, formatting helpers, or internal row numbers.
Check that the destination group and owner behaviour match the team’s follow-up process.

Custom fields are useful when they support a real decision or handoff. Importing every historical spreadsheet column makes the record harder to use and maintain.

Import historical notes

Use Import Notes for plain-text history that should live on records already in the CRM. This is a separate workflow from CSV record import: it does not use the CSV flow’s table selection, multi-file merge, column-to-field mapping, relationship mapping, or group-mapping sequence.

Step 1: Choose the destination and matching field

The first Notes screen asks Where should notes be saved? Choose the table that owns the records, then choose How should we find the right record? by selecting a text field.

The matching field can be:

a text field directly on the selected table, such as contact email or company name; or
a text field reached through a usable relationship, such as a contact’s related company name.

The field list can show related fields with a related indicator. Choose the direct field when possible. Related matching is useful for attaching notes to an existing record when the source only has a value from a related record, but it is less suitable for creating missing records.

Click Continue to File Upload. Use Change if the destination or matching field is wrong before continuing.

Step 2: Prepare the Notes file

Notes import expects these headers:

Column	Required?	Meaning
`key`	Required	The value to compare with the selected matching field
`note`	Required	The plain-text note content
`timestamp`	Optional	The date and time associated with the note; use an ISO-style date and time
`owner_email`	Optional	The workspace member who should be recorded as the note owner
`is_private`	Optional	A row-level privacy value such as `true`, `false`, `1`, `0`, `yes`, or `no`

The column names are part of the file format. Do not rename key to email, or note to comments, unless you are preparing the file through another process that restores the required names before upload.

A minimal file looks like this:

key,note
alex@example.com,"Discussed pricing and agreed to send a proposal."

A richer file can look like this:

key,note,timestamp,owner_email,is_private
alex@example.com,"Pricing call; follow up next Tuesday.",2026-09-10T14:30:00Z,alexis@example.com,false

Use the Download Notes Sample action in the upload screen to obtain the current sample format. Keep the key exactly as it appears in the destination field, including the part that makes it unique.

Step 3: Choose privacy and missing-record behaviour

The upload screen provides two important settings:

Default private notes: controls the privacy default when a row does not provide is_private. It is off by default, so notes are shared unless you change it.
Create missing records automatically: asks the system to create a record when no matching record is found. It is enabled by default in the importer, so turn it off for a history-only import. This works only when the matching field is directly on the selected table. It does not create a record from a related-table field.

Turn on automatic creation only when the source is clean and you really want new records. The new record uses the key value and is placed in the first active view or group available for that table. If the table has no active view or group, creation can fail.

For a related-field match, leave automatic creation off. First import or create the related records, then run Notes import against a direct field on the intended destination table if new records are needed.

Step 4: Upload, review, and start

Upload the CSV, Excel workbook, or ZIP file. Check that:

every row has a key;
every row has note text;
the key uses the same spelling and format as the selected field;
timestamps are valid dates and times;
owner_email belongs to a workspace member; and
private notes are intentional.

Rows with missing required values are skipped. Multiple rows with the same key are grouped so several notes can be attached to the same record. That is useful for a call history, but make sure a repeated key really refers to the same record.

Start the import when the preview is correct. The task runs in the background and the notification reports progress and counts. Refresh the destination records and inspect a few notes after the task completes.

Notes scenarios

Scenario: bring in old contact call notes

The source file has one row per call and the contact’s email in key.

Open a group view and choose Import / Export → Import Notes.
Choose the Contacts table and its direct email text field.
Leave automatic creation off if the file should only add history to known contacts.
Prepare the fixed headers key, note, timestamp, and optionally owner_email.
Choose private-by-default if the history is internal, or set is_private row by row.
Import a small sample and confirm that each note appears on the intended contact.

If a contact is missing, the row will not create a contact while automatic creation is off. That protects the workspace from turning a typo in an email address into a new record.

The source only has a company name, but the selected destination records can be found through a related company text field.

Choose the destination table and the related company-name field in How should we find the right record?
Keep Create missing records automatically off.
Use the exact company value in key.
Import a small sample.
Check several destination records, especially where multiple records are related to the same company.

This flow can find existing records through the relationship. It cannot create missing destination records from that related key, and if multiple records match the same value, the result may not be the record the user intended. Use a direct, unique key when the history must land on one specific record.

Scenario: preserve note owners and dates

Include owner_email only for people who are members of the workspace. If an owner email is missing or not recognised, the system falls back to the person running the import. An invalid or missing timestamp falls back to the task start time, so review the result if historical dates matter.

Notes best practices

Use a stable direct key whenever possible.
Do not use a common company name to identify an individual contact.
Check for duplicate key values before enabling missing-record creation.
Decide whether notes should be shared or private before starting the task.
Keep the original date and author in the source file when that history is important.
Use plain text for the note body. Markdown image links with HTTP or HTTPS addresses may be downloaded and stored when supported; an image that cannot be downloaded does not prevent the note text from being imported.
Run one Notes import at a time. A second active Notes import for the same workspace is rejected until the first one finishes or is cancelled.

Troubleshooting

I cannot see Import / Export

You need record-editing access to the group. Ask the group owner, an administrator, or an editor to grant the appropriate access or run the import. If the import needs new fields, choice values, or groups, workspace editing permission is also required.

The file is rejected before mapping

Check the following:

the extension is CSV, Excel, or ZIP;
the file is no larger than 50 MB;
the first row contains the real headers;
there is at least one data row;
headers are not blank or duplicated;
there is no title row above the headers; and
a ZIP actually contains CSV files.

For Excel, check each worksheet separately. Remove empty worksheets or worksheets that are only presentation material.

The importer says the headers are invalid

Rename duplicate columns so every header is unique, remove blank headers, and make sure the header row contains words rather than dates or numbers. If a spreadsheet has merged cells or a report title above the table, copy the actual table into a clean worksheet first.

The wrong destination field was suggested

Suggestions are based on header names and do not understand the business meaning of every column. Choose the destination field manually, use the sample values as a check, and select Skip column for fields that do not belong in the workspace.

I cannot create a field or choice value

Record editing and workspace structure editing are separate permissions. Ask a workspace administrator or editor to create the field or choice first, then reopen the importer. Do not map sensitive or temporary spreadsheet columns into an arbitrary existing field just to get past the screen.

Existing records were not updated

That is expected when the incoming value matches an existing record. CSV import avoids creating the duplicate but does not overwrite existing field values. Use the supported update workflow or contact support if the intended job is a bulk update.

Duplicate records or incorrect matches appeared

Review the matching field and the source values. Names are often not unique; email addresses or stable IDs are safer when available. Stop before rerunning the complete file. Compare the affected rows with the destination records and get support for cleanup if necessary.

Relationships were not created

Return to the relationship mapping and check that the source column contains the value expected by the related record’s matching field. Remove extra spelling differences, blank values, and ambiguous names. Verify that the destination user can access the related records and that the selected tables are included in the import.

Records went to the wrong group

Check the Where should records go? choices for every involved table. A group may receive a default view automatically when it did not already have one, so inspect the group and table after completion. If the wrong owner was assigned, review Auto-assign me when user field is empty and the source owner values before retrying.

Invalid rows are missing after the import

Rows with error-level validation issues are excluded when you continue with errors. Use the Invalid tab before starting, fix the source or the rows in the review screen, and compare the final imported count with the original row count.

Notes import says required columns are missing

Notes import requires key and note with those names. Add the optional columns only with the exact names timestamp, owner_email, and is_private. Do not rely on the CSV importer’s flexible column mapping; Notes import has its own fixed format.

Notes went to the wrong record

Check the selected destination table, the selected matching field, and the exact value in key. If several records have the same matching value, the oldest matching record is selected, so a non-unique key can attach notes to an unintended record. Use a direct unique field for the next sample.

Missing notes did not create records

Automatic creation works only for a matching text field directly on the selected table. It does not create records when the selected key is a related-table field. It can also fail when the destination table has no active view or group. Create the destination records first or select a direct matching field.

A note is shared when it should be private

Notes are shared by default. Use Default private notes before the import, or include is_private for each sensitive row. After the task finishes, inspect representative records and correct visibility before sharing them. Follow your organisation’s rules for confidential information.

The note owner or date is wrong

owner_email must identify a workspace member. An unknown or missing owner falls back to the person who started the import. A missing or invalid timestamp falls back to the task start time. Correct the source and run a small, separate import after confirming the intended behaviour.

The Notes import cannot start because another task is running

Only one active Notes import is allowed per workspace. Wait for the existing task to finish or cancel it when the cancel action is available. Starting another task with the same file can create duplicate notes if the first task partially completed.

The task is slow, failed, or cancelled

Check the task notification and sidebar status. Large files, many relationships, and record creation can take longer because the server processes the work in batches and saves checkpoints. For a retry, keep the original task details, confirm the mapping, and avoid blindly re-uploading a file that may have partially completed. Cancellation does not remove records or notes already written.

I am planning a full migration

Treat the migration as a project rather than a single upload. Keep a source backup, document the matching keys and relationships, decide which fields are truly needed, test a small sample, and record the resulting task counts. For large datasets, complicated relationships, or any need to update existing records, contact support before proceeding.

Safety checklist

Before starting either import, confirm:

the destination table and group are correct;
the source backup is saved;
matching values are stable and consistently formatted;
fields, choices, and relationships have been reviewed;
private-note settings are intentional;
the sample result has been inspected; and
the team understands that cancellation is not rollback and CSV import does not overwrite existing records.