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

Step 6: Preview & Import

Review first 10 records
See validation summary (valid leads, invalid records)
Click Import to save

Import Results:

✅ Number of leads saved
⚠️ Invalid records skipped
📋 List assignment confirmation

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.

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

​Step 6: Preview & Import

​Google Sheets Integration

​Prerequisites

​Import Steps

​HubSpot Integration

​Features

​Setup Steps

​Salesforce Integration

​Features

​Setup Steps

​Lead notes

​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

Step 6: Preview & Import

Google Sheets Integration

Prerequisites

Import Steps

HubSpot Integration

Features

Setup Steps

Salesforce Integration

Features

Setup Steps

Lead notes

Data Validation Rules

Phone Numbers

Email Addresses

Duplicate Detection

API Reference

Quick Example

Error Codes

Best Practices