Import Contacts

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:

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

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:

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:

GET /v1/sales/imports/imp_01HXYZ1234

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

Subscribe to the sales.import.completed event to receive a notification when large import jobs finish, rather than polling.

Getting Started

Platform Concepts

App Guides — Office

App Guides — Access

App Guides — Sales

App Guides — Careers

App Guides — Project

App Guides — Guard

Integrations

Security & Compliance

CSV Import

Prepare Your File

Submit the Import Job

Duplicate Handling

API Import

Checking Import Status

​CSV Import

​Prepare Your File

​Submit the Import Job

​Duplicate Handling

​API Import

​Checking Import Status

CSV Import

Prepare Your File

Submit the Import Job

Duplicate Handling

API Import

Checking Import Status