Upload Leads - Tuco AI

Overview

Import leads into your workspace using multiple methods: CSV upload, Google Sheets, HubSpot, or Salesforce integration.

Quick Start

New to importing leads? Start with CSV Upload for the easiest experience.

CSV Upload

The recommended method for beginners. Upload a CSV file with your lead data.

Step 1: Prepare Your CSV File

Your CSV must include these required fields:

string

required

Lead’s first name

string

required

Lead’s last name

string

required

Primary email address

string

required

Primary phone number (include country code, e.g., +1234567890)

Optional fields:

string

Alternate phone numbers

string

Alternate phone numbers

string

Alternate phone numbers

string

Alternate email addresses

string

Alternate email addresses

string

Alternate email addresses

string

Company or organization name

string

Position or role

string

LinkedIn profile URL

string

Free-text context about the lead. Your team can read and edit it later, and your AI campaigns and goal bots use it when they write — see Lead notes.

string

Email of the workspace user to assign as owner. Must match a user in your workspace. Invalid or missing values default to the first workspace user.

Any additional columns will be stored as custom fields.

Step 2: Download Template (Optional)

Click the Download Template button to get a pre-formatted CSV with all fields.

Step 3: Upload Your File

Navigate to Leads → Import
Select CSV File method
Drag & drop your file or click Choose File
File size limit: 10MB max

Step 4: Select or Create a List

Choose whether to:

Add to an existing list (select from dropdown)
Create a new list (enter list name)

Step 5: Map Fields

The system will auto-map common field names. Review and adjust:

Each CSV column maps to one lead field
Required fields must be mapped
See live preview of sample data

Custom variables

Any column you do not map to a standard field is imported as a custom variable. The mapping step lists every one of them in a Custom variables section, showing:

a toggle to import it or ignore it (everything is ON by default)
the variable name, which you can rename
the exact token it will produce, e.g. {cf:Industry}
a sample value from your first row

Rename a variable here and the token updates with it — what you see is what your campaign will use.

This is how you get your own data into messages. A column called Industry becomes {cf:Industry}, usable in any campaign step. See Message Templates for the full syntax.

Turn OFF the columns you do not need. Tracking columns like utm_source or internal row IDs become variables too, and they clutter the variable picker in the campaign editor.

Step 6: Preview & Import

Review first 10 records
See validation summary (valid leads, invalid records)
Custom variable columns appear in the preview table with their real values, so you can confirm the data landed on the right variable before importing
Click Import to save

Import Results:

✅ Number of leads saved
⚠️ Invalid records skipped
📋 List assignment confirmation
🏷️ Custom variables imported, named, with the {cf:...} syntax to use them

Duplicates

A lead already in your workspace is skipped, not re-imported — matched on any of its phone numbers or email addresses, not just the primary one.

A skipped duplicate stays in its original list. Importing an existing contact into a new list does not move it there, and does not add it to both — a lead belongs to exactly one list. To move existing leads, use Add to list on the Leads page, which reports the conflicts and lets you transfer them deliberately.

Google Sheets Integration

Import leads directly from Google Sheets.

Prerequisites

Google API Access Token

Generate an access token from Google Cloud Console

Spreadsheet ID

Found in your Google Sheet URL

Sheet Name

Default: “Sheet1” (optional parameter)

Import Steps

Navigate to Leads → Import
Select Google Sheets
Enter credentials:
- Access Token
- Spreadsheet ID
- Sheet Name (optional)
Click Connect & Import

Your Google Sheet must follow the same field structure as CSV (see above).

HubSpot Integration

Premium Feature - Requires HubSpot account and premium plan

Features

✓ Bidirectional sync
✓ Contact properties
✓ Deal tracking
✓ Activity logs

Setup Steps

Navigate to Leads → Import
Select HubSpot
Click Authorize & Import
Log in to HubSpot and grant permissions
System automatically imports contacts

Salesforce Integration

Premium Feature - Requires Salesforce account and premium plan

Features

✓ Lead & Contact sync
✓ Custom fields support
✓ Campaign tracking
✓ Opportunity data

Setup Steps

Navigate to Leads → Import
Select Salesforce
Click Authorize & Import
Log in to Salesforce and grant permissions
System automatically imports leads

Lead notes

notes is one free-text field on the lead — a place for the context that does not fit a column. “Quoted in March, went quiet.” “Only answers after 5pm.” “Property address: 8 Williams Wood Rd; lead score: high.” Where to edit it

Leads → open a lead → Edit — the Notes box at the bottom of the contact details. The saved note shows as its own Notes card on the lead page.
Unibox → the contact button on a conversation — opens the same contact panel with the same Notes box, so you can write one down mid-conversation.
CSV import — map a column to notes, or send notes on the Leads API. This sets the note on new leads only: re-importing someone you already have is treated as a duplicate and leaves their existing note untouched, so notes cannot be bulk-rewritten by re-uploading a file.

To clear a note, empty the box and save. There is no separate delete. What reads it

AI campaign steps — the note goes into the prompt, so generated copy can work from it.
Goal bots and task agents — returned by their get_lead_details tool.
{notes} in a message template — inserts the note verbatim, so use a fallback ({notes|}) if only some leads have one.

Notes are internal context, not message copy. Bots are told to use a note for context and never to read it back to the lead, but {notes} in a template pastes it into the message exactly as written — do not put anything there you would not want a lead to see.Very long notes are truncated before they reach a model, so keep them to the facts that matter.

Managing leads in bulk

Everything below lives on the Leads page and respects whatever filter you currently have applied — list, search, or owner.

Selecting more than one page

The Leads page shows 50 rows at a time, so the header checkbox selects those 50. When more leads match your filter than fit on the page, Tuco offers a wider scope:

All N matching — every lead in the current list or filter
All N in HubSpot / LeadConnector — every lead carrying a record ID for your connected CRM (only shown when a CRM is actually connected)

The counts come from the server, so they are the true totals, not what is on screen. The page scope stays the default — nothing is escalated without you choosing it.

Delete all matching leads

Delete all N removes every lead in the chosen scope, along with their activities, messages, conversation history and campaign stats. You must type the count to confirm.

This is permanent and cannot be undone. It also removes those leads from any campaign they are enrolled in and decrements that campaign’s stats.

Delete all N keeps the list itself — it only removes the leads. Delete List is the separate action that removes the list as well.

Add leads to a list

Add to list moves the selected scope into a list you pick. Because a lead belongs to exactly one list, any lead already in a different list is reported rather than silently moved. Tuco shows a duplicate report naming each one and the list it is currently in, and offers:

Download CSV — the conflicted leads with their current and target list, so you can decide outside the app
Transfer to this list — moves them, which removes them from their old list

Leads with no list are added immediately. Leads already in the target list are left alone.

Bulk operations run in the background

A bulk delete or transfer across tens of thousands of leads does not run while you wait. Tuco confirms with a toast — “Deleting 60,000 leads from Q4 Push in the background. This can take a few minutes.” — and works through it. While an operation is in flight, that list is locked: further bulk actions on it are disabled and the list shows as deleting in background in the filter. Other lists stay fully usable.

The lock is held on the server, not in your browser, so it survives a reload and is visible from a second tab. Trying to start a conflicting operation returns a clear error rather than running twice.

A bulk action that covers all leads (rather than one list) locks every list for its duration, because it can touch leads anywhere. Two different lists can still be worked on at the same time.

If something goes wrong

Bulk operations are not silent about failure. If one stops early — because it could not remove some leads, or because the server restarted mid-run — Tuco tells you what happened and how far it got:

Bulk operation didn’t finish — Deleting 60,000 leads stopped unexpectedly. 12,000 of 60,000 were processed. The server restarted while this was running. Re-run to finish the rest.

The operation is safe to re-run: it picks up whatever is still matching and leaves the rest alone. You will see this message once, the next time you open the Leads page.

Data Validation Rules

Phone Numbers

Phone numbers are automatically formatted according to these rules:

Input Format	Output Format	Description
10 digits	+1XXXXXXXXXX	Assumes US number
11 digits (starts with 1)	+1XXXXXXXXXX	US number with country code
Other formats	Must be E.164	International: +[country][number]

Email Addresses

Must contain @ and .
Automatically converted to lowercase
Whitespace trimmed

Duplicate Detection

Duplicates are detected by email address:

Duplicate rows in same CSV are skipped
Existing database duplicates are handled gracefully

API Reference

Upload leads programmatically using our REST API.

API Endpoint

View complete API documentation for lead uploads

Quick Example

POST /api/leads

Request:

{
  "leads": [
    {
      "firstName": "John",
      "lastName": "Doe",
      "email": "john@example.com",
      "phone": "+12025551234",
      "companyName": "Acme Corp",
      "jobTitle": "CEO",
      "contactOwnerEmail": "rep@yourcompany.com",
      "customFields": {
        "industry": "Technology",
        "revenue": "1M-5M"
      }
    }
  ],
  "listId": "507f1f77bcf86cd799439011",
  "source": "csv_import"
}

Response:

{
  "message": "Leads saved successfully",
  "savedCount": 1,
  "listId": "507f1f77bcf86cd799439011"
}

Error Codes

Code	Description
`400`	Invalid data or missing required fields
`401`	Unauthorized (missing/invalid auth token)
`404`	List not found
`500`	Server error

Best Practices

✅ Use Templates

Download and use our CSV template to ensure proper formatting

📋 Validate Before Upload

Review your data for completeness and accuracy before importing

🗂️ Organize with Lists

Create specific lists for different campaigns or lead sources

🔄 Regular Syncs

Set up automated syncs with HubSpot/Salesforce for up-to-date data

​Overview

Quick Start

​CSV Upload

​Step 1: Prepare Your CSV File

​Step 2: Download Template (Optional)

​Step 3: Upload Your File

​Step 4: Select or Create a List

​Step 5: Map Fields

​Custom variables

​Step 6: Preview & Import

​Duplicates

​Google Sheets Integration

​Prerequisites

​Import Steps

​HubSpot Integration

​Features

​Setup Steps

​Salesforce Integration

​Features

​Setup Steps

​Lead notes

​Managing leads in bulk

​Selecting more than one page

​Delete all matching leads

​Add leads to a list

​Bulk operations run in the background

​If something goes wrong

​Data Validation Rules

​Phone Numbers

​Email Addresses

​Duplicate Detection

​API Reference

API Endpoint

​Quick Example

​Error Codes

​Best Practices

Overview

CSV Upload

Step 1: Prepare Your CSV File

Step 2: Download Template (Optional)

Step 3: Upload Your File

Step 4: Select or Create a List

Step 5: Map Fields

Custom variables

Step 6: Preview & Import

Duplicates

Google Sheets Integration

Prerequisites

Import Steps

HubSpot Integration

Features

Setup Steps

Salesforce Integration

Features

Setup Steps

Lead notes

Managing leads in bulk

Selecting more than one page

Delete all matching leads

Add leads to a list

Bulk operations run in the background

If something goes wrong

Data Validation Rules

Phone Numbers

Email Addresses

Duplicate Detection

API Reference

Quick Example

Error Codes

Best Practices