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

# Importing opportunities: troubleshooting common errors

> Resolve common CSV import errors for opportunities in the HoopAI platform, including column mapping issues, required fields, date formats, and duplicate handling.

The HoopAI platform allows you to bulk-import opportunities from a CSV file into your pipelines. If your import is failing or producing unexpected results, this guide covers the most common errors and how to fix them.

<Note>
  Before importing, make sure the target pipeline and its stages already exist in Hoop. The import process matches opportunities to existing pipelines and stages by name — it does not create new ones automatically.
</Note>

***

## Required fields

Every opportunity import requires the following columns in your CSV:

| Column                 | Description                                      | Example                      |
| ---------------------- | ------------------------------------------------ | ---------------------------- |
| Contact Email or Phone | Used to associate the opportunity with a contact | `jane@example.com`           |
| Pipeline               | The exact name of the pipeline in Hoop           | `Sales Pipeline`             |
| Stage                  | The exact name of the stage within that pipeline | `Qualified`                  |
| Opportunity Name       | A label for the opportunity                      | `Jane Doe - Enterprise Plan` |

<Warning>
  If any required column is missing or the header name does not match, the entire import will fail at the validation step. Double-check your CSV headers before uploading.
</Warning>

***

## Column mapping issues

During the import process, Hoop attempts to auto-map your CSV columns to opportunity fields. If the mapping is incorrect:

<Steps>
  <Step title="Review the mapping screen">
    After uploading your CSV, Hoop displays a column mapping preview. Review each row to ensure the CSV column is mapped to the correct Hoop field.
  </Step>

  <Step title="Manually adjust mismatched columns">
    Use the dropdown next to each field to change the mapping. Common mismatches include "Company" mapping to "Opportunity Name" or "Value" mapping to "Phone."
  </Step>

  <Step title="Skip unmapped columns">
    If your CSV contains columns that do not have a corresponding field in Hoop, set them to **Skip** to prevent import errors.
  </Step>
</Steps>

***

## Date format errors

Hoop expects dates in one of the following formats:

* `YYYY-MM-DD` (recommended) — for example, `2026-03-05`
* `MM/DD/YYYY` — for example, `03/05/2026`
* `DD/MM/YYYY` — for example, `05/03/2026`

<AccordionGroup>
  <Accordion title="Import fails with 'invalid date' error">
    Open your CSV in a text editor (not Excel, which may reformat dates) and verify the date column values match one of the accepted formats. Remove any timestamps or timezone suffixes.
  </Accordion>

  <Accordion title="Dates are imported with the wrong day/month">
    This typically occurs when using `DD/MM/YYYY` format and Hoop interprets it as `MM/DD/YYYY`. Use the `YYYY-MM-DD` format to avoid ambiguity, or select the correct date format on the mapping screen.
  </Accordion>
</AccordionGroup>

***

## Pipeline and stage matching

The pipeline and stage names in your CSV must match exactly with the names configured in Hoop, including capitalization and spacing.

* **"Sales pipeline"** will not match **"Sales Pipeline"** — capitalization matters
* **"New Lead "** (with a trailing space) will not match **"New Lead"** — remove extra whitespace
* If a stage name exists in multiple pipelines, you must include the pipeline column so Hoop can resolve the correct one

<Tip>
  Export your current pipelines and stages from Hoop before building your import file. Use the exported names as a reference to ensure exact matches.
</Tip>

***

## Duplicate handling

By default, Hoop identifies duplicate opportunities by matching on contact email and pipeline. When a duplicate is found:

* **Update existing**: The imported data overwrites the existing opportunity fields
* **Skip duplicates**: The row is ignored and no changes are made
* **Create new**: A new opportunity is created regardless of existing matches

Select your preferred duplicate handling option on the import settings screen before starting the import.

<Info>
  If you are re-importing a file to correct errors, select **Update existing** to avoid creating duplicate opportunities in your pipeline.
</Info>

***

## File size and formatting limits

| Constraint              | Limit                               |
| ----------------------- | ----------------------------------- |
| Maximum file size       | 5 MB                                |
| Maximum rows per import | 10,000                              |
| File format             | `.csv` (UTF-8 encoded)              |
| Delimiter               | Comma only (not semicolons or tabs) |

If your file exceeds these limits, split it into smaller files and run multiple imports. Ensure each file includes the header row.

***

## After the import

Once your import completes:

1. Check the import summary for the count of created, updated, skipped, and failed records
2. Navigate to the target pipeline and verify that opportunities appear in the correct stages
3. Open a few individual opportunities to confirm that field data (value, status, custom fields) imported correctly
4. If rows failed, download the error report from the import summary to identify and fix the specific issues