CSV File Format for Importing Contacts and Opportunities

Modified on Fri, 26 Sep at 1:34 AM

Key Benefits of Preparing Your CSV File

Taking the time to format your CSV file correctly before importing ensures your contact data is clean, complete, and mapped accurately.

Reduces the chance of import errors or upload failures
Helps the platform automatically map fields during import
Enables contact deduplication and accurate updates
Supports custom fields and advanced segmentation
Saves time by avoiding post-import cleanup
Increases success with bulk contact/opportunity uploads

What is a CSV File Format?

CSV stands for 'Comma-Separated Values'. It's a simple file format used to store tabular data like spreadsheets or databases. Each line in a CSV file represents a single record, and fields within the record are separated by commas. It’s one of the most widely used formats for importing and exporting data between different systems.

CSV files typically have a .csv extension.
You can create or edit them in tools like Excel, Google Sheets, or Notepad.
Ensure only one sheet is present in the file to prevent import issues.

Example:

First Name	Last Name	Email	Phone
Jane	Doe	jane@example.com	+11234567890
John	Smith	john@example.com	+10987654321

Structuring Your File

To ensure accurate data mapping, structure your CSV file with column headers corresponding to standard or custom fields in your account.

Sample CSV Format

First Name	Last Name	Email	Phone	Company	Tags	Status	Created Date	Additional Phone
John	Doe	john@example.com	+11234567890	ABC Corp	VIP, Lead	New	01/01/2024	+17877123462
Jane	Smith	jane@example.com	+15556667777	XYZ Ltd	Customer	Active	02/02/2024	+17877123464

Each row represents a single contact or opportunity.
Each column represents a distinct property.
The header row is required to map fields correctly.

Mandatory Fields

At least one of the following is required to create or update a contact:

First Name
Email Address
Phone Number

Note: For updating contacts, a Unique Identifier (Contact ID, Email, or Phone) is required based on your deduplication settings. For opportunities, include the Opportunity ID if updating. Without it, a new one will be created.

Field Formatting

Follow these specific formatting rules to avoid import failures:

Field Type	Accepted Formats / Notes
Date Picker (Date Fields)	MM/DD/YYYY, YYYY/MM/DD, MM-DD-YYYY, YYYY-MM-DD
Multi-Select / Checkbox	Commas: VIP, Lead, Semicolons: Gold; Silver, Periods: Yes. No❌ Slashes = Invalid
Single Option (Dropdown)	One value only. Example: Blue
Contact Owner	FirstName LastName — e.g., Logan Paul
Tags	Commas, semicolons, or periods. e.g., Blue, Yellow, Blue; Yellow
Phone Number	E.164: +11234567890 (recommended); also 123-456-7890, (123) 456-7890 (US only)
Invalid Phone Formats	1234567, abc1234567
Numerical Fields	1.23, 1234, .123
Monetary Fields	1234, 1,234,234.33
Contact Followers	FirstName LastName, FirstName2 LastName2 — e.g., Adam Smith, David Lee
Additional Emails	abc@email.com, abc1@email.com
Additional Phone Numbers	+1 7877123460, +1 7877123461

Supported File Type and File Size

Your file must meet certain basic requirements for a successful upload.

Requirement	Details
File Format	.csv only
Sheets Allowed	One sheet per file
Max File Size	30 MB

Required and Optional Fields for Import

Including the right fields helps the platform identify and process your records accurately.

Import Action	Required/Optional Fields	Notes
New Contact	Name or Email, or Phone	At least one is required
Update Existing Contact	Contact ID or Name/Email/Phone	Depends on duplicate settings
Header Row	Required	Headers must match existing or custom fields in the software

Formatting Guidelines by Field Type

To prevent import errors, follow these formatting rules for each data type in your CSV.

Field Type	Format	Example	Notes
Phone Number	E.164 or standard US formats	+1 1234567890123-456-7890	Clean and consistent formatting
Email Address	Standard format	name@example.com	Must include @ and domain
Date	Multiple accepted formats	04/16/2025, 2025-04-16	Choose one format and stick to it
Multi-Select Fields	Separate with ,, ;, or .	Blue, Yellow, Green	Must match field options in CRM
Additional Emails	Comma-separated	email1@example.com, email2@example.com	Add in a separate column
Additional Phones	Comma-separated	1234567890, 9876543210	Add in a separate column

Tip: Before importing your CSV, ensure custom fields are already created in your account using the same labels and data types. For help with creating custom fields, refer to the Overview of Merge Fields & Custom Variables.

Supported Countries List in CSV Imports

This section contains a table of country names accepted during CSV imports into the platform. These are the official country values that should be used in your CSV file when mapping a country field, whether standard or custom. Use the exact country names or short codes listed below in your CSV file.

Purpose: The platform validates country names during import. If your CSV includes a Country field, each row must match one of the exact names in this list.
Format: Must match exactly—case-sensitive and spelling-sensitive. For example, United States is accepted, but USA or U.S. will cause an error.
Custom Field Use: If you're using a custom country field, you can still benefit from sticking to this list to maintain compatibility.

Supported Timezones

Use one of the following timezone formats in your CSV. These are case-sensitive and must match exactly.

Timezone	Timezone	Timezone
Etc/GMT+12	Pacific/Midway	Pacific/Honolulu
America/Juneau	US/Alaska	America/Dawson
America/Los_Angeles	America/Phoenix	America/Tijuana
US/Arizona	America/Belize	America/Boise
America/Chihuahua	America/Denver	America/Edmonton
America/Guatemala	America/Managua	America/Regina
Canada/Saskatchewan	US/Mountain	America/Bahia_Banderas
America/Bogota	America/Cancun	America/Chicago

Frequently Asked Questions

Q: Can I import contacts with more than one phone number or email?
Yes! Use separate columns like Additional phone numbers and Additional email addresses, and separate entries with commas.

Q: What happens if I include a field in the CSV that doesn’t exist in the platform?
That field will be ignored unless you map it to an existing standard or custom field during the import process.

Q: Will the platform detect duplicates automatically?
Yes, based on your Duplicate Detection Settings, it can match by Contact ID, phone, or email and either merge or skip duplicates.

Q: Can I update contacts with a CSV import?
Absolutely. Just make sure you're including a field used in your duplicate matching (like Contact ID, email, or phone).

Q: Do I need to clean blank rows and columns?
Yes. It’s best to remove all unnecessary data to avoid unexpected import behavior.