# Importing contacts

> Bring people and companies in from a CSV file, map the columns, and deal with rows that fail.

Source: https://help.clockworkcrm.com/contacts/importing
Last updated: 2026-10-09

Contacts are imported from a CSV file. Imports run in the background, one row at a time, so you can
carry on using Clockwork CRM while one runs.

People and companies are imported separately, because their fields differ. Import companies first
if your people file names the companies they work for: a person is linked to a company that
already exists with the same name.

You can import contacts if you have access to **Add Contact**. See
[Teams and permissions](https://help.clockworkcrm.com/admin/teams).

## Preparing the file

- The file must be a CSV file (`.csv`). Save a spreadsheet as CSV before you import it.
- Separate values with commas.
- The first row must be a header row. Each header becomes a column you map to a field.
- Save the file as UTF-8 so that accented characters come through.
- Blank lines are skipped.
- Each row after the header creates one new person or company.

## Starting an import

1. Go to **Contacts → Import Contacts**.
2. Select **New Import**, then **Import People** or **Import Companies**. **Contacts → Add Contact**
   offers the same two imports as **Bulk Import people using a csv file.** and **Bulk Import
   companies using a csv file.**
3. Select **Choose a file**. The file browser opens and lists only CSV files.
4. Select the file. To use a file from your computer, upload it with **Upload** first. See
   [File browser](https://help.clockworkcrm.com/general/file-browser).
5. Map the columns, as described below.
6. Set the options you need.
7. Select **Begin Import**.

![The Import People step asking you to choose a CSV file](https://clockworkcrm.blob.core.windows.net/public-internal/docs/contacts/import-people-upload.png?v=d6221b6b)

Clockwork CRM then opens the **Contact Imports** list, where you can follow the import.

## Mapping your columns

Clockwork CRM reads the header row and lists each header under **CSV Header**. Beside it, **CRM
Field** sets which field that column goes into.

![The column mapping: each CSV header with the CRM field it goes into, and unmapped columns in red](https://clockworkcrm.blob.core.windows.net/public-internal/docs/contacts/import-mapping.png?v=887f5e4d)

- A header that matches a field name, ignoring capitals, is mapped to that field automatically.
  For example, a column headed `first_name` or `First Name` is mapped to **First Name**. When
  two headers match the same field, only the first is mapped.
- A column set to **N/A** is not imported. Unmapped columns are shown in red.
- Each CRM field can be filled from one column only. Once a field is mapped, it is unavailable for
  the other columns, and shows "(mapped from *column*)" in their lists.
- **Begin Import** stays disabled until at least one column is mapped.
- **Reset** clears the mapping and goes back to choosing a file.

### Fields for people

| CRM Field | What it fills in |
|---|---|
| **Title** | The person's title, such as Mr or Dr |
| **First Name** | The person's first name. Required |
| **Last Name** | The person's surname. Required |
| **Job Role** | The person's job role |
| **Email** | The person's email address |
| **Telephone** | The person's telephone number |
| **Mobile** | The person's mobile number |
| **Officer Id** | The person's Companies House officer ID |
| **Tags** | Tags for the person, see [Tags](https://help.clockworkcrm.com/contacts/importing#tags) |
| **Company: Name** | The company the person works for, see [Linking people to companies](https://help.clockworkcrm.com/contacts/importing#linking-people-to-companies) |
| **Company: Email** | The person's email address at that company |
| **Company: Telephone** | The person's telephone number at that company |
| **Company: Mobile** | The person's mobile number at that company |
| **Company: Job Role** | The person's job role at that company |

Every person custom property is also listed, under its **Property Name**.

### Fields for companies

| CRM Field | What it fills in |
|---|---|
| **Name** | The company's name. Required |
| **Address Line 1**, **Address Line 2** and **Address Line 3** | The company's address |
| **City** | The town or city |
| **County** | The county |
| **Postcode** | The postcode |
| **Country** | The country |
| **Website** | The company's website |
| **Registration Number** | The company's registration number |
| **Telephone** | The company's telephone number |
| **Email** | The company's email address |
| **Business Type** | The company's business type |
| **Tags** | Tags for the company, see [Tags](https://help.clockworkcrm.com/contacts/importing#tags) |

Every company custom property is also listed, under its **Property Name**. To import into a custom
property, create it first at **Contacts → Properties**. See [Custom properties](https://help.clockworkcrm.com/general/custom-properties).

## Import options

| Option | What it does |
|---|---|
| **Add missing companies** | People imports only. When a row's **Company: Name** does not match an existing company, a company with that name is created and the person is linked to it. Off by default |
| **Ignore custom property validation errors** | When off, a row with a custom property value that is not valid fails and is not imported. When on, the value that is not valid is left empty and the rest of the row is imported. The row is then listed in **Download errors**, with the values that were left out. Off by default |

## Tags

Put a contact's tags in one column, separated by commas, such as `Customer, North`. Each tag is
added to the contact. A tag that does not exist yet is created, with a random colour. People tags and
company tags are separate.

## Linking people to companies

When **Company: Name** is mapped and the row has a company name:

- If a company with exactly that name exists, the person is linked to it.
- If no company has that name and **Add missing companies** is on, a company is created with just
  that name, and the person is linked to it. Later rows with the same name link to the same company.
- If no company has that name and **Add missing companies** is off, the person is imported without a
  company.

**Company: Email**, **Company: Telephone**, **Company: Mobile** and **Company: Job Role** are saved
on the link, as the person's details at that company. They are only saved when the person is linked.

## Existing contacts

An import always creates new records. It does not update contacts you already have.

A row fails, and is not imported, when:

- a people row has an **Email** already used by another person
- a companies row has a **Name** already used by another company
- a companies row has an **Email** already used by another company

Email addresses are compared ignoring capitals, so `Sam@example.com` is already used when another
person has `sam@example.com`.

Other existing contacts, such as a person with the same name but a different email address, are
imported as new records. When an import completes, Clockwork CRM scans for duplicates. People
imports with **Add missing companies** on scan companies too. If the scan finds any, you get a
notification. See [Finding and merging duplicates](https://help.clockworkcrm.com/contacts/duplicates).

Imported contacts do not trigger automations or webhooks.

## Custom property values

Each custom property value is checked against the property's type and settings.

| Property type | What the CSV value must be |
|---|---|
| **Text** and **Multi Line** | Text within the property's minimum and maximum length |
| **Number** | A whole number within the property's minimum and maximum |
| **Currency** | An amount, such as `1200.50`, within the property's minimum and maximum |
| **Date** | A date. Year first (`2026-09-28`) always works. Day and month order follows the **Date Locale** in instance settings: US locales read `09/28/2026`, other locales read `28/09/2026` |
| **Email** | A valid email address |
| **Phone** | A valid phone number, including the international dialling code, such as `+44` |
| **Url** | A full web address, including `https://` |
| **Checkbox** | `Yes`, `No`, `True` or `False`. An empty cell is unticked |
| **Radio** and **Select** | One of the property's options. Capitals are ignored |
| **Multiple Selection** | One or more of the property's options, separated by commas |
| **User** | The user's username (their email address) |
| **Company** | The company's email address |
| **Person** | The person's email address |

A required custom property must have a value in every row, even when no column is mapped to it.
Otherwise the row fails, unless **Ignore custom property validation errors** is on.

## Watching it run

**Contacts → Import Contacts** lists every import, newest first. The list updates while imports run.
It also lists the imports started with **Add all** in **Find UK companies**, as a **Company Import**
named after the area. See [Finding UK companies](https://help.clockworkcrm.com/contacts/uk-companies#searching-an-area).

![The Contact Imports list, showing name, upload date, rows to import, state and progress](https://clockworkcrm.blob.core.windows.net/public-internal/docs/contacts/import-list.png?v=56abe84e)

| Column | What it shows |
|---|---|
| **Name** | **Person Import** or **Company Import**, and the file name |
| **Upload Date** | When the import was started, and who started it |
| **Rows to Import** | The number of rows in the file |
| **State** | The import's state, and when it last changed |
| **Progress** | A progress bar and **Processed** count while it runs. **Download errors** once it has finished, if any rows failed or were imported without some values |

| State | Meaning |
|---|---|
| **Pending** | Queued, not started yet |
| **Running** | Importing rows |
| **Complete** | Finished. Some rows may still have failed |
| **Failed** | The import stopped because of an error |

An import that stops part way through is restarted automatically, and carries on from the last row
it processed.

The menu at the end of each import's row has **Delete**, which removes the import from the list after you
confirm. It is not available while the import is **Pending** or **Running**. Deleting an import
does not delete the contacts it added.

## Fixing the rows that failed

**Download errors** downloads a CSV file with one line for each row that failed. It has the row's
original columns, plus an **Import Error Message** column with the reason. A row with more than one
custom property value that is missing or not valid lists every one of them, separated by
semicolons. Reasons include:

- First name is a required field
- Surname is a required field
- This email address is already in use by another person
- Company name is a required field
- A company already exists with this name, company names must be unique
- This email address is already in use by another company
- a custom property value that is missing or not valid, named with the property

When **Ignore custom property validation errors** is on, the file also lists each row that was
imported with values left out. Its **Import Error Message** starts "Imported without these values:"
and names each value. These rows are already in Clockwork CRM.

To import the failed rows:

1. Open the downloaded file and correct each row. Remove any row that starts "Imported without
   these values:", as it has already been imported.
2. Import the file again, leaving **Import Error Message** set to **N/A**. Only these rows are
   added. The rows that were imported the first time are not affected.

## Related

- [People](https://help.clockworkcrm.com/contacts/people), person records
- [Companies](https://help.clockworkcrm.com/contacts/companies), company records
- [Finding UK companies](https://help.clockworkcrm.com/contacts/uk-companies), adding companies from the UK register
- [Custom properties](https://help.clockworkcrm.com/general/custom-properties), properties you can import into
- [Finding and merging duplicates](https://help.clockworkcrm.com/contacts/duplicates)