Upload CSV Programmatically

Import contacts and companies from CSV files using the API — with AI-powered column matching.

Overview

Consuelo’s CSV import isn’t just a UI feature — you can upload CSV files programmatically through the API. This is useful when you want to:

• Automate imports from other systems
• Build integrations that push data into Consuelo on a schedule
• Import data from scripts or pipelines without opening the browser

How It Works

The programmatic CSV flow mirrors what happens in the UI:

1. Upload your CSV — send the file contents to the API
2. Column matching — Consuelo’s AI analyzes your headers and sample data to map columns to the right fields (first name, last name, email, phone, etc.)
3. Import — matched data is created as records in your workspace

AI-powered matching means messy headers work. Columns named “Contact Email”, “E-mail Address”, or even “Copy of Leads Export (1)” will be matched correctly. The AI looks at both the header name and the actual data to figure out what each column contains.

Step 1: Get Your API Token

You need an authenticated token to call the API.

1. Go to Settings → Developers
2. Create an API key, or use an existing one
3. Include it as a Bearer token in your requests

Step 2: Analyze Column Mapping

Before importing, send your CSV headers and a few sample rows to get AI-powered column suggestions.

curl -X POST https://your-instance.consuelohq.com/api/v1/csv-mapping/analyze \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "headers": ["Full Name", "Email Address", "Phone", "Company"],
    "sampleRows": [
      ["Jane Smith", "[e-mail]", "555-0100", "Acme Corp"],
      ["Bob Jones", "[e-mail]", "555-0200", "Example Inc"]
    ],
    "targetFields": [
      {"key": "name.firstName", "label": "First Name"},
      {"key": "name.lastName", "label": "Last Name"},
      {"key": "email", "label": "Email"},
      {"key": "phone", "label": "Phone"},
      {"key": "company", "label": "Company"}
    ]
  }'

The response tells you how each CSV column maps to a Consuelo field:

{
  "mappings": {
    "Full Name": "name.firstName",
    "Email Address": "email",
    "Phone": "phone",
    "Company": "company"
  },
  "confidence": "high"
}

Field	Description
headers	Array of your CSV column names
sampleRows	2-5 rows of actual data (helps the AI disambiguate)
targetFields	The Consuelo fields you want to map to (key + label pairs)
mappings	The AI’s suggested mapping — CSV header → Consuelo field key
confidence	How confident the AI is: high, medium, or low

You can skip columns. If a mapping value is "skip", the AI determined that column doesn’t match any target field. You can override this in your import logic.

Step 3: Import the Data

Once you have the column mapping, use the GraphQL API to create records. Here’s an example using the createPeople mutation:

mutation {
  createPeople(data: [
    {
      name: { firstName: "Jane", lastName: "Smith" }
      emails: { primaryEmail: "[e-mail]" }
      phones: { primaryPhoneNumber: "555-0100" }
    },
    {
      name: { firstName: "Bob", lastName: "Jones" }
      emails: { primaryEmail: "[e-mail]" }
      phones: { primaryPhoneNumber: "555-0200" }
    }
  ]) {
    id
  }
}

Import Companies before People if you want to link them. The Company record must exist before you can reference it from a Person record.

Tips

Batch Your Requests

The API supports up to 60 records per batch call. For large CSVs, split your data into chunks:

1,000 records ÷ 60 per batch = 17 API calls

Handle Duplicates

Use the email field as a unique identifier. If a record with the same email already exists, you can use upsert operations to update instead of creating duplicates.

Validate Before Importing

Send a small batch first (5-10 records) to verify your mapping is correct before importing the full dataset.

When to Use This vs. the UI

Scenario	Use
One-time import of a few hundred contacts	UI — drag and drop your CSV
Recurring imports from another system	API — automate with a script
Large dataset (10,000+ records)	API — more reliable, supports batching
Non-technical user importing a list	UI — no code required
Integration pipeline	API — fits into your existing workflow

Related

• Import Contacts via CSV — the UI-based import flow
• Import Data via API — full API import guide
• Prepare Your CSV Files — formatting tips
• Field Mapping — how column matching works