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

# Import contacts (CSV)

> Add many contacts at once from a spreadsheet, match the columns, and apply tags and a segment.

<Info>
  **Time to complete:** \~5 minutes  ·  **Difficulty:** Beginner
   ·  **Limits:** 10 MB file, up to 50,000 rows
</Info>

## Overview

Import lets you add many contacts at once from a `.csv` file (a spreadsheet saved as
plain text; Excel and Google Sheets can export one). You upload the file, match its
columns to contact fields, and optionally apply tags and add everyone to a
[segment](/getting-started/glossary#segment). The import then runs in the background.

Reach it from **Contacts → Import CSV**, or directly at `/contacts/import`.

<Tip>
  Click **Download Template** on the import page to get a correctly formatted
  starter file with the standard columns.
</Tip>

## Before you start

Have these ready:

* A `.csv` file saved as plain text (UTF-8), **10 MB max**, **up to 50,000 rows**.
* A heading row plus at least one row of contacts.
* At minimum a **Phone** column and a **First Name** column.
* Any [custom fields](/contacts/custom-fields) you want to import, already created
  in **Settings → Module Setup**.

## Import your contacts

<Steps>
  <Step title="Upload CSV" icon="upload">
    On the **New Import** tab, drag in or browse to your `.csv`. Autocampaign AI reads
    the column headings and shows a preview of the first rows. Only `.csv` is accepted.
  </Step>

  <Step title="Map fields" icon="arrow-right-arrow-left">
    Match each spreadsheet column to a contact field. Autocampaign AI recognizes common
    headings on its own (a green **High match** badge means it's confident). You can map:

    * **First Name** (required), **Last Name**, **Phone** (required), **Email**
    * **Street Address**, **Address Line 2**, **City**, **State / Province**,
      **Postal Code**, **Country**
    * Any importable **custom fields** (shown with a "Custom" badge)

    Each mapped field has an **action** for contacts you already have: **Replace**,
    **Skip**, or **Overwrite if Empty**. You can't move on until First Name and
    Phone are mapped.
  </Step>

  <Step title="Tags & options" icon="tag">
    Apply one or more [tags](/getting-started/glossary#tag) to every imported
    contact. Optionally add them all to a **static segment** (or create a new one).
  </Step>

  <Step title="Review & import" icon="circle-check">
    Check the summary, then click **Start Import**. The import runs in the
    background, and you can watch live progress.
  </Step>
</Steps>

## How duplicates are handled

Autocampaign AI spots duplicates by **phone number**. If a contact with the same phone
already exists in your workspace, the imported row is **skipped** and your existing
contact is left unchanged. The row is counted under **Duplicates** in the results.

## Watch progress and check results

While the import runs you'll see a progress bar ("X of Y rows") and three counters:

* **Success** — new contacts created.
* **Failed** — rows that couldn't be imported (with the reason).
* **Duplicates** — rows skipped because the phone already existed.

If any rows fail, an **Import Errors** panel lists them (for example, *"Row 12:
Phone — Invalid phone number format"*).

## Import history

Switch to the **Import History** tab to see past imports with their file name,
status, and Success / Failed / Duplicates counts. Search by file name to find a
specific import.

<Note>
  You can run up to **3 imports at the same time** per workspace. Wait for one to
  finish if you hit the limit.
</Note>

## FAQ

<AccordionGroup>
  <Accordion title="What columns are required?">
    **Phone** and **First Name**. Everything else is optional. Use **Download
    Template** for the recommended layout.
  </Accordion>

  <Accordion title="Can I import tags per row?">
    Not from a column. Tags are chosen in the **Tags & options** step and applied to
    every contact in the import. See [Tags](/contacts/tags).
  </Accordion>

  <Accordion title="Can I import custom fields?">
    Yes. Create them first in **Settings → Module Setup**, then map your spreadsheet
    columns to them. (Lookup, user, and auto-number field types can't be imported.)
  </Accordion>

  <Accordion title="What happens to duplicate phone numbers?">
    They're skipped and counted as duplicates; the existing contact isn't changed.
  </Accordion>

  <Accordion title="Can I import into a dynamic segment?">
    No. Only **static** segments can be an import target. Dynamic segments fill
    themselves from rules. See [Segments](/contacts/segments).
  </Accordion>
</AccordionGroup>

## Troubleshooting

<AccordionGroup>
  <Accordion title="Why do I see 'File does not appear to contain valid CSV text'?">
    The file isn't a plain-text CSV. It may be an Excel `.xlsx`, or contain unsupported
    characters. Re-export it as **CSV UTF-8** and try again.
  </Accordion>

  <Accordion title="Why do I see 'File exceeds 10 MB limit' or too many rows?">
    Split large files into batches under 10 MB / 50,000 rows and import them
    separately.
  </Accordion>

  <Accordion title="Why do I see 'Required fields missing'?">
    Map both **First Name** and **Phone** to spreadsheet columns and make sure they're
    turned on before continuing.
  </Accordion>

  <Accordion title="Why do I see 'Unknown custom field(s)'?">
    A column is mapped to a custom field that doesn't exist. Create it in **Settings
    → Module Setup** first, then map the column again.
  </Accordion>

  <Accordion title="Why did rows fail with 'Invalid phone number format'?">
    Phone values must be digits, spaces, hyphens, parentheses, or a leading `+`, up
    to 20 characters. Clean the column and import those rows again.
  </Accordion>
</AccordionGroup>

<Card title="Next: organize with tags" icon="tag" href="/contacts/tags">
  Label imported contacts for easy targeting.
</Card>