CSV Import Workflow - Naturalead API

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.

Upload CSV for Preview

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

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]"

import requests

url = "https://api.naturalead.ai/api/leads/upload/preview"
headers = {"X-API-Key": "nl_live_YOUR_API_KEY"}
files = {"file": open("leads.csv", "rb")}

response = requests.post(url, headers=headers, files=files)
preview = response.json()

print(f"Detected columns: {preview['columns']}")
print(f"Sample rows: {len(preview['rows'])}")

const fs = require("fs");
const FormData = require("form-data");

const form = new FormData();
form.append("file", fs.createReadStream("leads.csv"));

const response = await fetch(
  "https://api.naturalead.ai/api/leads/upload/preview",
  {
    method: "POST",
    headers: {
      "X-API-Key": "nl_live_YOUR_API_KEY",
      ...form.getHeaders(),
    },
    body: form,
  }
);

const preview = await response.json();
console.log("Detected columns:", preview.columns);
console.log("Sample rows:", preview.rows.length);

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"]
  }'

import requests

url = "https://api.naturalead.ai/api/leads/upload/confirm"
headers = {
    "X-API-Key": "nl_live_YOUR_API_KEY",
    "Content-Type": "application/json",
}
payload = {
    "uploadId": "preview_abc123",
    "mapping": {
        "Phone Number": "phone",
        "Full Name": "name",
        "Email Address": "email",
        "Company": "company",
        "Lead Source": "source",
    },
    "tags": ["csv-import", "q1-2026"],
}

response = requests.post(url, headers=headers, json=payload)
result = response.json()

print(f"Imported: {result['imported']}")
print(f"Duplicates skipped: {result['duplicates']}")
print(f"Batch ID: {result['importBatchId']}")

const response = await fetch(
  "https://api.naturalead.ai/api/leads/upload/confirm",
  {
    method: "POST",
    headers: {
      "X-API-Key": "nl_live_YOUR_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      uploadId: "preview_abc123",
      mapping: {
        "Phone Number": "phone",
        "Full Name": "name",
        "Email Address": "email",
        Company: "company",
        "Lead Source": "source",
      },
      tags: ["csv-import", "q1-2026"],
    }),
  }
);

const result = await response.json();
console.log("Imported:", result.imported);
console.log("Duplicates skipped:", result.duplicates);
console.log("Batch ID:", result.importBatchId);

Field Mapping Rules

The mapping object maps CSV column names (keys) to Naturalead lead fields (values).

Lead Field	Required	Description
`phone`	Yes	Phone number — used as the unique identifier for deduplication
`name`	No	Lead’s full name
`email`	No	Email address
`source`	No	Where 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 Code	Meaning
`400`	Invalid CSV format, missing required `phone` mapping, or expired `uploadId`
`401`	Missing or invalid authentication
`413`	CSV file exceeds the maximum upload size
`422`	Column mapping references columns not found in the CSV
`429`	Rate 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.

​Overview

​Step 1: Upload CSV for Preview

​Step 2: Map Columns and Confirm Import

​Field Mapping Rules

​Deduplication

​Tracking Imports with importBatchId

​Error Handling

Overview

Step 1: Upload CSV for Preview

Step 2: Map Columns and Confirm Import

Field Mapping Rules

Deduplication

Tracking Imports with importBatchId

Error Handling