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

# Import Contacts

> Import contacts into Essal Sales via CSV upload or the API, with field mapping and deduplication options.

Essal Sales lets you import contact records in bulk from a CSV file or directly via the API. The import pipeline handles field mapping, validation, and deduplication before persisting records.

## CSV Import

### Prepare Your File

The CSV must include a header row. At minimum, a `email` or `display_name` column is required:

```csv theme={null}
display_name,email,company,phone,region
Jane Smith,jane@acmecorp.com,Acme Corp,+44 7700 900123,EMEA
John Doe,john@widgets.io,Widgets Inc,+1 555 0199,Americas
```

### Submit the Import Job

```bash theme={null}
curl -X POST https://api.essal.cloud/v1/sales/contacts/import \
  -H "X-API-Key: esk_live_xxxxxxxxxxxxxxxxxxxx" \
  -F "file=@contacts.csv" \
  -F 'options={"on_duplicate":"merge","field_map":{"company":"organization_name"}}'
```

The `field_map` object lets you map CSV column names to Essal Sales field names where they differ.

### Duplicate Handling

The `on_duplicate` option controls what happens when an imported contact matches an existing record (matched by email):

| Option      | Behaviour                                               |
| ----------- | ------------------------------------------------------- |
| `skip`      | Ignore the incoming row; keep existing record unchanged |
| `merge`     | Update existing record with non-empty incoming fields   |
| `overwrite` | Replace all fields with incoming values                 |
| `create`    | Always create a new record regardless of duplicates     |

## API Import

For programmatic imports, push contacts individually or in batches:

```bash theme={null}
POST /v1/sales/contacts/batch
{
  "contacts": [
    {
      "display_name": "Jane Smith",
      "email": "jane@acmecorp.com",
      "organization_name": "Acme Corp",
      "phone": "+44 7700 900123",
      "custom_fields": { "region": "EMEA" }
    }
  ],
  "on_duplicate": "merge"
}
```

Batch requests support up to 200 contacts per call.

## Checking Import Status

Both CSV and batch imports are processed asynchronously. Poll the job endpoint for progress:

```bash theme={null}
GET /v1/sales/imports/imp_01HXYZ1234
```

```json theme={null}
{
  "id": "imp_01HXYZ1234",
  "status": "completed",
  "total": 250,
  "created": 198,
  "merged": 47,
  "skipped": 5,
  "errors": []
}
```

<Tip>
  Subscribe to the `sales.import.completed` event to receive a notification when large import jobs finish, rather than polling.
</Tip>