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

# Bulk contact imports

> Import large contact lists from a CSV, track progress with live counts, and get suggested segments

Import large contact lists from a CSV without waiting on the page. Uploads process in the background, columns map to your contact fields automatically, and **Import History** shows a live breakdown of what was created, updated, skipped, and failed. Available in the dashboard and through the API, SDK, CLI, and MCP server.

* Import large lists from a CSV file, processed in the background
* Automatic column mapping to your contact fields
* Live status with created, updated, skipped, and failed counts
* Choose to update or skip contacts that already exist
* Suggested segments as soon as an import finishes

## Import from the dashboard

In **Contacts**, choose **Add Contact** then **Bulk Import** and upload your CSV. Migma matches each column to a contact field, with only Email required, and you confirm before it runs. The import processes in the background, so you can leave the page. Watch it finish in **Import History** with counts for imported, updated, and failed contacts and a summary of any rows that could not be added.

## Suggested segments after an import

When an import finishes, Migma suggests segments built from the contacts you just added, so a fresh list becomes a targeted audience in one step. Choose a suggestion to open the segment builder prefilled and ready to save.

## Import programmatically

Create and track imports from the API, SDK, CLI, and MCP server. Upload the CSV, then poll the import for its status and counts.

```typescript Node.js SDK theme={null}
import { readFileSync } from 'node:fs';
import Migma from 'migma';

const migma = new Migma('YOUR_API_KEY');

// Upload the CSV, processed in the background.
const { data: job } = await migma.contacts.imports.create({
  file: readFileSync('./contacts.csv'),
  projectId: 'PROJECT_ID',
  columnMap: { email: 'Email', firstName: 'First Name' },
  onConflict: 'upsert',
});

// Poll until it finishes.
const { data: status } = await migma.contacts.imports.get(job!.id);
```

A finished import reports counts you can reconcile against your file:

```json theme={null}
{
  "object": "contact_import",
  "id": "IMPORT_ID",
  "status": "completed",
  "counts": { "total": 1200, "created": 1150, "updated": 40, "skipped": 8, "failed": 2 }
}
```

## Update or skip existing contacts

Set `onConflict` to `upsert`, the default, to update contacts whose email already exists, which makes a re-import a safe way to refresh your list. Set it to `skip` to leave existing contacts untouched and only add new ones.

[Manage contacts](/audience/manage-contacts) · [API reference](/api-reference/introduction) · [SDK](/sdk) · [CLI](/cli) · [MCP](/mcp-server)