> ## Documentation Index
> Fetch the complete documentation index at: https://help.hoopai.com/llms.txt
> Use this file to discover all available pages before exploring further.

# CSV import format guide

> Exact CSV format requirements for importing contacts into HoopAI — columns, date formats, phone formatting, and sample template.

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](mailto: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](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                        |

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

***

## 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 |

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

***

## 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

```csv theme={null}
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

<Steps>
  <Step title="Prepare your CSV">
    Format your CSV according to the guidelines above. Save as UTF-8 encoded CSV.
  </Step>

  <Step title="Go to Contacts">
    Navigate to **Contacts** and click **Import → Import from CSV**.
  </Step>

  <Step title="Upload the file">
    Select your CSV file. HoopAI will preview the first few rows.
  </Step>

  <Step title="Map columns">
    Map each CSV column to the corresponding HoopAI field. The system will auto-match common column names.
  </Step>

  <Step title="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
  </Step>

  <Step title="Import">
    Click **Import** and wait for processing. You will receive a notification when complete.
  </Step>
</Steps>

***

## 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       |

<Note>
  For detailed troubleshooting of import issues, see [Bulk import troubleshooting](/troubleshooting/bulk-import-issues).
</Note>