📋 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

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:

​

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:

​

Common Formatting Mistakes That Cause Failures

​

❌ WRONG - These Will Fail:

​

✅ CORRECT - These Will Work:

​

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)

​

❌ Wrong Phone Number Formats:

​

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:

​

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:

​

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.