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

# Import and clean contacts

> CSV in, deduplicated contacts out — mapped, verified, and organized into a list ready for outreach.

**Outcome:** clean contact records in your workspace, deduplicated, validated, and organized into a
list ready for sequencing.

## Best interface

<Note>
  **API for bulk import** — one `POST /v3/contacts/import` call handles dedupe, list assignment, and
  per-item outcomes. Drive it from your own code, or from the terminal with
  [`reply api`](/cli/overview#raw-api-access). **MCP** for conversational, one-at-a-time creation.
</Note>

## Steps

<Steps>
  <Step title="Build the import payload">
    Import takes JSON, not CSV — convert your spreadsheet first. The body is
    `{"items": [...], "options": {...}}`, where each item uses the contact fields and `options`
    controls dedupe and list assignment. **Maximum 1000 items per request** — batch anything larger.

    ```json theme={null}
    {
      "items": [
        {"email": "john@acme.com", "firstName": "John", "lastName": "Doe", "company": "Acme"}
      ],
      "options": {"skipExisting": true, "listIds": [42]}
    }
    ```
  </Step>

  <Step title="Import, then read the per-item outcome">
    ```bash theme={null}
    reply api /v3/contacts/import --body @import.json --json
    ```

    The response reports added / updated / skipped / failed counts with a per-item outcome — report
    exact numbers rather than "done". Nothing is written until you send this call, so validate the
    payload locally first: there is no server-side dry-run.
  </Step>

  <Step title="Or create contacts programmatically (API / MCP)">
    For one-at-a-time or system-to-system sync, use the Contacts endpoints in the
    [API Reference](/api-reference/introduction), or `reply_create_contact` /
    `reply_update_contact` via [MCP](/mcp/tools#contacts) (needs a name plus email or LinkedIn URL).
  </Step>

  <Step title="Validate emails before sending">
    Schedule email validation on the list — never send to a dead address. Available today via the
    API; part of the [list-hygiene loop](/guides/automate-outbound).
  </Step>

  <Step title="Verify list membership">
    ```bash theme={null}
    reply api /v3/contact-lists/42 --json
    reply api '/v3/contacts/filter?top=100' --body '{"listId":42}' --json | jq '.data.items | length'
    ```
  </Step>
</Steps>

## Availability notes

* CSV import, contact CRUD, lists, and email validation: **available today**.
* Waterfall **enrichment** of imported records (fill missing emails/phones/firmographics):
  **coming soon** — see [Find prospects](/guides/find-ideal-prospects#availability-notes).

## Related

* [Launch multichannel outreach](/guides/launch-outreach) — enroll the list into a sequence
* [Automate outbound end-to-end](/guides/automate-outbound) — keep the list clean on a schedule
* [Skill: Import prospects](/skills/catalog#import-prospects)