CSV import format guide

This guide covers the exact CSV format you need for importing contacts into HoopAI, including required columns, data formatting, and common pitfalls.

Required columns

Only one field is technically required — you need at least one identifier:

Column	Required?	Notes
Email	Required (if no phone)	Must be a valid email address
Phone	Required (if no email)	E.164 format recommended (+1XXXXXXXXXX)

You must have at least email or phone for each row. Rows missing both are skipped.

Standard columns

Column header	Format	Example
`firstName`	Text	John
`lastName`	Text	Smith
`email`	Email	john@example.com
`phone`	E.164 or national	+15551234567
`address1`	Text	123 Main St
`city`	Text	Austin
`state`	Text or abbreviation	TX
`postalCode`	Text	78701
`country`	ISO 2-letter code	US
`companyName`	Text	Acme Corp
`website`	URL	https://example.com
`dateOfBirth`	YYYY-MM-DD	1990-05-15
`source`	Text	Website Form
`tags`	Comma-separated	lead, webinar, vip

Phone number formatting

HoopAI accepts multiple formats, but E.164 is strongly recommended to avoid errors:

Format	Example	Accepted?
E.164 (recommended)	+15551234567	Yes
National with country code	15551234567	Yes (assumes US if no +)
National only	5551234567	Yes (assumes US)
Formatted	(555) 123-4567	Yes (parsed automatically)
With dashes	555-123-4567	Yes
International	+442071234567	Yes

For international contacts, always include the country code with a + prefix. Without it, numbers default to US formatting and may be invalid.

Date formats

Accepted format	Example
YYYY-MM-DD (recommended)	2024-03-15
MM/DD/YYYY	03/15/2024
DD/MM/YYYY	15/03/2024
MM-DD-YYYY	03-15-2024

Use YYYY-MM-DD to avoid ambiguity between US (MM/DD) and international (DD/MM) date formats.

Custom field mapping

To import data into custom fields, use the custom field’s key (not the display name) as the column header. Find the key in Settings → Custom Fields. Example: If you have a custom field “Lead Score” with key lead_score, your column header should be lead_score.

Tags formatting

Tags can be included in a single column, separated by commas:

tags
"lead, webinar-attendee, vip"

If a tag does not exist yet, it will be created automatically during import.

Do-Not-Disturb flags

Column	Values	Effect
`dndEmail`	true / false	Sets email DND
`dndSms`	true / false	Sets SMS DND
`dndCall`	true / false	Sets call DND
`dndAll`	true / false	Sets DND on all channels

Sample CSV template

firstName,lastName,email,phone,companyName,tags,source,address1,city,state,postalCode,country
John,Smith,john@example.com,+15551234567,Acme Corp,"lead, webinar",Website Form,123 Main St,Austin,TX,78701,US
Jane,Doe,jane@example.com,+15559876543,,"vip, customer",Referral,456 Oak Ave,Denver,CO,80202,US
Bob,Wilson,,+442071234567,UK Ltd,"prospect",Import,10 Downing St,London,,SW1A 2AA,GB

Import steps

Prepare your CSV

Format your CSV according to the guidelines above. Save as UTF-8 encoded CSV.

Go to Contacts

Navigate to Contacts and click Import → Import from CSV.

Upload the file

Select your CSV file. HoopAI will preview the first few rows.

Map columns

Map each CSV column to the corresponding HoopAI field. The system will auto-match common column names.

Set import options

Duplicate handling — choose to skip, update, or create new for duplicates
Tags — optionally apply a tag to all imported contacts
Source — set the import source for tracking

Import

Click Import and wait for processing. You will receive a notification when complete.

Common errors and fixes

Error	Cause	Fix
”Invalid email format”	Email column has invalid addresses	Check for spaces, missing @, or invalid domains
”Phone number invalid”	Number missing country code or too short	Use E.164 format with + prefix
”Duplicate detected”	Email or phone matches an existing contact	Choose update or skip in duplicate handling
”Row skipped — no identifier”	Row has no email or phone	Add at least one identifier per row
”Date format not recognized”	Ambiguous date format	Use YYYY-MM-DD format
”File encoding error”	File saved in non-UTF-8 encoding	Re-save as UTF-8 CSV
”File too large”	CSV exceeds the upload limit	Split into multiple files under 50MB each

For detailed troubleshooting of import issues, see Bulk import troubleshooting.

Contacts Overview

Managing Contacts

Organizing & Segmenting

Import & Export

Tasks & Compliance

Opportunities Overview

Pipeline Management

Managing Opportunities

Sales Tools

Automation & Reporting

Required columns

Standard columns

Phone number formatting

Date formats

Custom field mapping

Tags formatting

Do-Not-Disturb flags

Sample CSV template

Import steps

Common errors and fixes

​Required columns

​Standard columns

​Phone number formatting

​Date formats

​Custom field mapping

​Tags formatting

​Do-Not-Disturb flags

​Sample CSV template

​Import steps

​Common errors and fixes

Required columns

Standard columns

Phone number formatting

Date formats

Custom field mapping

Tags formatting

Do-Not-Disturb flags

Sample CSV template

Import steps

Common errors and fixes