📋 Upload Sheet Format Guide

​

Why File Format Matters So Much

Think of your upload sheet like a key that must fit perfectly into a lock. If the key is even slightly wrong - wrong shape, wrong size, wrong teeth - the lock won’t open. The same is true for your audience upload sheet. Small formatting mistakes = Complete upload failure

​

Important: File Size Limits

​

Maximum Capacity: 20,000 Customers Per File

Your upload sheet can contain a maximum of 20,000 customers in a single file. This is a system limitation to ensure optimal performance and reliable campaign execution.

​

What Happens If You Have More Than 20k Customers?

If your audience list contains more than 20,000 contacts, you’ll need to:

1. Split your data into multiple files - Each file with maximum 20k customers
2. Upload each file as a separate audience list - Create multiple audience lists
3. Run campaigns on each audience list - Manage them separately or combine them

​

Example: 35,000 Customer Scenario

File Number	Customer Range	File Size	Action
File 1	Customers 1-20,000	20,000	Upload as “Audience List A”
File 2	Customers 20,001-35,000	15,000	Upload as “Audience List B”

Result: You’ll have 2 audience lists that you can use for separate campaigns or combine for larger reach.

​

The Golden Rule: Column Headers Must Match Custom Fields Exactly

​

What This Means:

If your custom field is {duedate}, your column header must be exactly duedate - not due date, not DueDate, not duedate (with extra spaces).

​

Why This Happens:

The system looks for exact matches between your custom field names and your column headers. It’s like a computer looking for a file named “report.txt” - it won’t find “Report.txt” or “report .txt”.

​

Required Columns (Always Present)

These columns must be in your sheet for any upload to work:

Column Header	Must Be Exactly	What It Contains	Example
FirstName	FirstName	Person’s first name	John
LastName	LastName	Person’s last name	Smith
PhoneNum	PhoneNum	Contact phone number	12185262990

​

Custom Field Columns (Based on Your Prompt)

​

How to Know What to Include:

1. Look at your AI agent’s prompt - Find all the custom fields in curly braces like {FirstName}, {AmountDue}, {DueDate}
2. Add a column for each custom field - The column header must match exactly
3. Remove the curly braces - {DueDate} becomes DueDate in your sheet

​

Example Custom Field Mapping:

Custom Field in Prompt	Column Header in Sheet	What to Enter
{FirstName}	FirstName	John
{AmountDue}	AmountDue	$500.00
{DueDate}	DueDate	2024-03-30
{AccountNumber}	AccountNumber	ACC12345

​

Common Formatting Mistakes That Cause Failures

​

❌ WRONG - These Will Fail:

What You Have	What It Should Be	Why It Fails
First Name	FirstName	Spaces are not allowed
firstname	firstname	Wrong capitalization
FirstName	FirstName	Extra spaces at the end
first_name	firstname	Underscores are different
Due Date	DueDate	Spaces break the match
duedate	DueDate	Wrong capitalization

​

✅ CORRECT - These Will Work:

Column Header	Status	Why It Works
FirstName	✅ Correct	Matches {FirstName} exactly
AmountDue	✅ Correct	Matches {AmountDue} exactly
DueDate	✅ Correct	Matches {DueDate} exactly
AccountNumber	✅ Correct	Matches {AccountNumber} exactly

​

Phone Number Formatting (Critical!)

​

Why Phone Number Formatting is So Important:

Phone numbers must include the country code without the + sign and have no dashes, spaces, or special characters. The system needs the complete international format to ensure successful SMS delivery.

​

✅ Correct Phone Number Formats:

Required Format: Country code + phone number (no + sign, no dashes, no spaces)

Country	Example Format	What to Enter
US/Canada	+1 (218) 526-2990	12185262990
India	+91 99639 05554	919963905554
UK	+44 20 7946 0958	442079460958
Australia	+61 2 9374 4000	61293744000

​

❌ Wrong Phone Number Formats:

What You Have	Why It Fails
+12185262990	Contains + sign
218-526-2990	Missing country code and has dashes
1 218 526 2990	Contains spaces
(218) 526-2990	Missing country code and has special characters

​

Date Column Formatting (Critical!)

​

Why Date Formatting is So Important:

Date columns are extra sensitive to formatting errors. The system needs to understand exactly what date you’re providing.

​

✅ Correct Date Formats:

Allowed

• March 25, 2025 (Recommended)
• 25-03-2025 in DD-MM-YYYY format
• 03-05-2025 in DD-MM-YYYY format

Not allowed

• Just writing 10-03-2025 - it is confusing if it is MM-DD or DD-MM

​

Complete Example Sheet

Here’s what a properly formatted upload sheet should look like:

FirstName	LastName	PhoneNum	AmountDue	DueDate	AccountNumber
John	Smith	12185262990	$500.00	2024-03-30	ACC12345
Jane	Doe	919963905554	$750.00	2024-04-15	ACC12346
Mike	Johnson	14155552368	$300.00	2024-03-25	ACC12347

​

Key Points About This Example:

1. Required columns are : FirstName, LastName, PhoneNum
2. Custom field columns match prompt customfields: FirstName, AmountDue, DueDate, AccountNumber
3. Dates are in stringify date format: March 25, 2025
4. No extra spaces anywhere in column headers
5. Consistent formatting throughout

​

Step-by-Step Upload Sheet Preparation

​

Step 1: Download the Sample Excel Template

1. Select your desired AI agent in the platform
2. Navigate to the Audience tab
3. Click “Add New Audience” to open the dialog box
4. Click the “Download Sample Excel File” button
5. Save the sample file to your computer

​

Step 2: Use the Sample File as Your Template

1. Open the downloaded sample Excel file
2. Review all column headers - These are exactly what you need
3. Keep the file structure intact - Don’t modify any column headers
4. Save a copy as your working template for future uploads

​

Step 3: Format Your Data

1. Names: Use proper capitalization (John, not john)
2. Phone numbers: Use country code + phone number format (12185262990, 919963905554)
3. Dates: Use stringify date format (March 25, 2025)
4. Numbers: Use consistent decimal places ($500.00, not$500)

​

Step 4: Check for Common Errors

1. Don’t modify column headers - Use exactly what’s in the sample file
2. No extra spaces - Don’t add spaces to any headers or data
3. Consistent formatting - Keep the same format throughout all rows
4. Proper date format - Use stringify date format (March 25, 2025)

​

Testing Your Sheet Before Upload

​

Before You Upload:

1. Double-check column headers - Compare with your custom fields exactly
2. Verify date formats - All dates should be stringify date format March 25, 2025
3. Check for extra spaces - Look at the beginning and end of each header
4. Test with a small file - Upload 2-3 contacts first to verify

​

Best Practices for Reliable Uploads

​

1. Use Excel Templates

• Create a template with correct column headers
• Save it as .xlsx format
• Reuse the template for future uploads
• Never copy-paste column headers (can add hidden characters)

​

2. Validate Your Data

• Check phone numbers - Make sure they include country code without + sign (e.g., 12185262990, 919963905554)
• Verify dates - Ensure they’re in the future if needed
• Review names - Check for obvious typos
• Test calculations - If using formulas, verify results

​

3. Keep It Simple

• Start with basic fields - Add complexity gradually
• Use consistent formats - Same style throughout
• Avoid special characters - Stick to letters, numbers, and basic punctuation
• Test small batches - Verify before uploading large lists

​

4. Respect File Size Limits

• Maximum 20,000 customers per file - Don’t exceed this limit
• Split large lists - Break them into multiple files if needed
• Plan your uploads - Consider how many audience lists you’ll need
• Monitor file sizes - Check customer count before uploading

​

Troubleshooting Upload Failures

​

If Your Upload Fails:

1. Check the error message - It usually tells you what’s wrong
2. Verify column headers - Compare with custom fields exactly
3. Check date formats - Convert all dates to stringify date format
4. Look for extra spaces - Remove any trailing or leading spaces
5. Verify file format - Make sure it’s .xlsx or .xls

​

Common Fixes:

Problem	Solution
Column header has spaces	Remove spaces: First Name → FirstName
Wrong capitalization	Fix case: firstname → FirstName
Extra spaces	Trim whitespace: FirstName → FirstName
Wrong date format	Convert to stringify date format : March 25, 2025
Missing required column	Add the missing column with correct spelling

​

Next Steps

Now that you understand proper sheet formatting:

1. Review your AI agent’s prompt - Identify all custom fields
2. Check your audience size - Ensure you’re within the 20,000 customer limit
3. Create a properly formatted sheet - Use correct column headers
4. Format your data correctly - Especially dates and phone numbers
5. Test with a small upload - Verify everything works
6. Upload your complete audience - Enjoy successful, error-free uploads

---

Need help with audiences? Check out our Audience Guide to learn the complete process of creating and managing your contact lists. Want to learn about custom fields? Visit our Custom Fields Guide to understand how to use dynamic placeholders in your prompts.