# Import contacts from a spreadsheet

Prepare a CSV or XLSX file, map its columns and review created, updated, skipped and failed rows without assuming the whole file succeeded.

Canonical: https://docs.lead-knight.com/en/contacts/import-contacts/

## What import does

Import creates new contacts and enriches matching existing records. It is not a bulk overwrite: existing names and identity details are retained when already present, missing details can be filled, and tags can be merged. Results are reported per file and per problem row.

## Before you start

- Use a workspace owner or admin account; other roles do not see **Import** on **Contacts**.
- Prepare a UTF-8 CSV or Excel `.xlsx` file with column headers. Legacy `.xls` is not supported.
- Keep the file at or below 2 MiB (2,097,152 bytes), with at most 5,000 data rows, excluding the header. These are Contacts import limits, not the separate audience-import limits.
- Give each mapped column a distinct, nonblank header. Repeated nonblank headers are rejected. Keep the sheet to at most 100 columns; parser limits also restrict cell lengths to 4,096 characters for CSV and 500 for XLSX.
- Include a name column and at least one phone or email column. New contacts must satisfy your workspace's **Required contact details**; mapping one identity column alone does not override a requirement for both.

## Upload and map the file

1. Open **Contacts** and click **Import**. The **Import contacts** dialog opens.
2. Under **CSV or Excel file**, click **Choose file**, or use **Drop a file here or choose a file**. After the preview finishes, the dialog shows the filename, data-row count and sample values.
3. Review the suggested mappings. Recognized English and Hebrew headers can be mapped automatically, but you must check them against the sample.
4. Map **Name**, **Phone** and **Email** to the correct file columns. **No column** leaves an optional field unmapped. Saving remains disabled without a name column and at least one phone/email column.
5. Map optional **Tags**, **Source**, **Notes** and configured custom contact fields. For tags, notes and custom fields, **Fixed value** applies one value to every row instead of reading a file column. A field cannot use both methods at once.
6. Choose **Default source** for rows that need the fallback source. Choose **Owner** if the new contacts should belong to another eligible teammate. Existing matched contacts keep their owner.
7. In Nadlanite, **Buyer / seller** can add a buyer role, seller role or both to imported contacts. **None** adds neither; import does not remove existing roles.
8. Click **Import contacts**. While work is in progress the button shows **Importing…**. Wait for the result rather than submitting the same file again.
9. Review **Created**, **Updated**, **Skipped (hidden details)**, **Possible duplicates** and **Errors**. Check each listed **Row** before treating the import as complete.

## Fixed values and custom fields

A fixed tag list supports up to 20 tags, each up to 40 characters. Fixed notes support up to 4,000 characters; fixed custom values up to 500 characters. Custom values must also fit their configured type, such as number or date. An invalid fixed value blocks submission; correct the highlighted input rather than deleting the entire mapping.

The preview lasts 15 minutes. If it expires, select the file again and review the mapping again. A preview is tied to the user and workspace that uploaded it.

## What happens to matches

| Row outcome | Meaning |
| --- | --- |
| **Created** | A new contact was created from a valid row. |
| **Updated** | Phone/email matched one accessible contact; import can fill missing values and merge tags without replacing its existing owner. |
| **Skipped (hidden details)** | A match exists but its details are not visible to you. It is left unchanged; the result can identify the owner without exposing the record. |
| **Possible duplicates** | For example, the phone points to one existing contact and the email to another. The conflicting row is flagged rather than imported as another record. |
| **Errors** | These rows failed validation. Other valid rows may already have been imported. |

Existing names and phone/email values are not replaced simply because the spreadsheet has different values. Custom fields fill blanks. An identical note already added by the importing user is not added again. To intentionally edit an existing record, use [contact details](https://docs.lead-knight.com/en/contacts/details-and-tags/).

## If something goes wrong

| Message or error | Meaning and next step |
| --- | --- |
| **Only CSV or Excel files can be imported.** | Unsupported file type. Export as CSV or `.xlsx`; changing a filename is not a repair. |
| **The file is too large or has too many rows.** | Split the file below the size and row limits, keeping headers in each file. This can correspond to `import_too_large` or HTTP 413. |
| **This file can't be imported safely. Choose a different file.** | `import_file_unsafe`: the file failed safety checks; XLSX size/row limits and the upload size guard can also produce this error. Export a clean, smaller CSV/XLSX and choose it again. |
| **The CSV file is invalid.** | CSV parsing failed or headers are duplicated. Check quoting and unique headers, then re-export. |
| **Could not import contacts. Please try again.** | A general failure, including `invalid_file` for malformed XLSX. Re-export a valid workbook or CSV and select it again. |
| **This import has expired. Choose the file again.** | The temporary preview is no longer available. Re-select and remap the file. |
| **A selected column is not in the file. Choose the file again.** | Mapping no longer matches the preview. Choose the intended file again. |
| **Import is busy. Try again shortly; if previews are full, they expire within 15 minutes.** | `import_busy`: temporary import capacity is full. Wait and retry rather than repeatedly opening more previews. |
| **Invalid phone number.**, **Invalid email address.** or **Missing:** | Correct the indicated row and satisfy the workspace identity requirement. Import corrected failed rows rather than assuming every original row failed. |

## Related pages

- [Contacts overview](https://docs.lead-knight.com/en/contacts/overview/)
- [Add one contact](https://docs.lead-knight.com/en/contacts/add-contact/)
- [Edit details and tags](https://docs.lead-knight.com/en/contacts/details-and-tags/)
- [Audiences](https://docs.lead-knight.com/en/audiences/overview/)


## Import contacts from a spreadsheet

[Import contacts from a spreadsheet](https://kwqpaiaguxkmadaipfrf.supabase.co/storage/v1/object/public/guide-videos/guides/videos/J3/nadlanite-en-8f994fdc34b4.mp4)

1. To bring in contacts from a spreadsheet, click Import.
2. Choose a CSV or Excel file.
3. Your columns are matched to contact fields automatically. Change any match from the list.
4. Set a default source for everyone in the file.
5. You can also mark them as buyers or sellers and choose their owner.
6. Click Import contacts.
7. When it finishes, you see how many contacts were created, updated or skipped.