> ## Documentation Index
> Fetch the complete documentation index at: https://docs.vodex.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# 📋 Upload Sheet Format Guide

> Learn the critical formatting requirements for uploading audience sheets - avoid upload failures with proper column headers and data formatting

<Warning>
  **Critical Information:** The format of your upload sheet is the most important factor for successful audience uploads. Even small mistakes will cause your upload to fail completely.
</Warning>

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

<Info>
  **Important:** These three columns are the foundation of every audience upload. Without them, your upload will fail immediately.
</Info>

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

<Warning>
  **Important:** Always include the country code and remove all formatting characters (+, -, spaces, parentheses) from phone numbers.
</Warning>

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

<Info>
  **Perfect Template:** This sample file contains all the exact column headers you need - both system fields (FirstName, LastName, PhoneNum) and all custom fields specific to your selected agent.
</Info>

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

<Warning>
  **Remember:** If you have more than 20,000 customers, split them into multiple files before uploading. Each file should contain a maximum of 20,000 contacts.
</Warning>

<Check>
  **Ready to create perfect upload sheets?** Remember: exact column headers + proper date formatting = successful uploads every time!
</Check>

***

**Need help with audiences?** Check out our [Audience Guide](/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](/custom-fields/introduction) to understand how to use dynamic placeholders in your prompts.