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) |
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 |
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.
| 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 can be included in a single column, separated by commas:
tags
"lead, webinar-attendee, vip"
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 |
