Skip to main content

​
Overview

Naturalead provides a two-step CSV import process that lets you preview and map columns before committing leads to your account. This prevents data errors and gives you full control over how CSV columns map to lead fields.
1

Upload CSV for Preview

Upload your CSV file to get a preview of parsed rows and detected columns.
2

Map Columns and Confirm

Define how CSV columns map to lead fields, then confirm the import.
All imported leads are automatically deduplicated by phone number. If a lead with the same phone already exists in your account, it will be updated rather than duplicated.

​
Step 1: Upload CSV for Preview

Send your CSV file as a multipart form upload. The API parses the file and returns detected columns along with a sample of rows so you can verify the data before importing. 
curl -X POST https://api.naturalead.ai/api/leads/upload/preview \
  -H "X-API-Key: nl_live_YOUR_API_KEY" \
  -F "[email protected]"
The response includes:
  • columns — an array of detected column names from the CSV header row
  • rows — a sample of parsed rows for verification
  • uploadId — a temporary identifier to reference this upload in the confirm step

​
Step 2: Map Columns and Confirm Import

Once you have reviewed the preview, send a column mapping and the uploadId to confirm the import. The mapping tells Naturalead which CSV column corresponds to each lead field. 
curl -X POST https://api.naturalead.ai/api/leads/upload/confirm \
  -H "X-API-Key: nl_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "uploadId": "preview_abc123",
    "mapping": {
      "Phone Number": "phone",
      "Full Name": "name",
      "Email Address": "email",
      "Company": "company",
      "Lead Source": "source"
    },
    "tags": ["csv-import", "q1-2026"]
  }'

​
Field Mapping Rules

The mapping object maps CSV column names (keys) to Naturalead lead fields (values).
Lead FieldRequiredDescription
phoneYesPhone number — used as the unique identifier for deduplication
nameNoLead’s full name
emailNoEmail address
sourceNoWhere the lead came from (e.g., “website”, “referral”)
The phone field is required. Every row in your CSV must have a valid phone number mapped. Rows without a phone number will be skipped during import.
Any CSV column mapped to a value that is not a recognized lead field is automatically stored as a custom field on the lead. For example, mapping "Company" to "company" will create a custom field called company on each lead.

​
Deduplication

Naturalead deduplicates leads by phone number within your account. During import:
  • If a lead with the same phone number already exists, the existing lead is updated with the new data.
  • If no match is found, a new lead is created.
This means you can safely re-import updated CSV files without creating duplicate records.

​
Tracking Imports with importBatchId

Every confirmed import generates a unique importBatchId. Use this ID to:
  • Filter leads by import batch using the List Leads API
  • Track import history to see which leads came from which file
  • Roll back imports by identifying and deleting all leads from a specific batch
Store the importBatchId returned from the confirm response. It is the only way to identify which leads were part of a specific import.

​
Error Handling

Status CodeMeaning
400Invalid CSV format, missing required phone mapping, or expired uploadId
401Missing or invalid authentication
413CSV file exceeds the maximum upload size
422Column mapping references columns not found in the CSV
429Rate limit exceeded — wait and retry
When some rows fail validation but others succeed, the API performs a partial import and returns both the count of successfully imported leads and details about skipped rows in the response.