Skip to main content

​
CSV File Format

Your CSV file must follow these rules for successful batch calling:

​
Rule 1: Use E.164 Phone Format

All phone numbers must include the country prefix in E.164 format (e.g., +11231237890). ❌ Wrong:
✅ Correct:
E.164 is the international standard for phone numbers. It includes:
  • Plus sign (+)
  • Country code (1-3 digits)
  • Area code and number (up to 14 digits total)

​
Rule 2: Use contact_number Header

The phone number column header must be exactly contact_number. ❌ Wrong:
✅ Correct:

​
Rule 3: Add Custom Variables

Include any additional variables (name, email, company, etc.) as separate columns. These are passed to your agent as context. Example with custom variables:

​
Complete Example

​
Important Notes

​
Excel Formula Warning

In Excel, if you type a cell starting with +, it may be interpreted as a formula. To prevent this:
  1. Right-click the column
  2. Select Format Cells
  3. Choose Text format
  4. Add an apostrophe before the plus: '+11231237890
The apostrophe won’t appear in the final file, but it prevents Excel from treating it as a formula.

​
Column Order

  • Column order doesn’t matter
  • contact_number is the only required column
  • All other columns are optional and become variables

​
Variable Naming

  • Use lowercase with underscores: first_name, last_name, phone_ext
  • Avoid spaces and special characters
  • Use clear, descriptive names

​
Using Variables in Agent Prompts

Reference variables in your agent prompt using curly braces:

​
Validation Checklist

Before uploading, verify:
  • ✓ All phone numbers start with +
  • ✓ All phone numbers are in E.164 format
  • ✓ Header column is exactly contact_number
  • ✓ No duplicate phone numbers
  • ✓ No empty rows or columns
  • ✓ CSV is UTF-8 encoded
  • ✓ File size is under 50MB

​
Common Issues

​
”Invalid phone number format”

Problem: Phone numbers not in E.164 format Solution: Add country code with + prefix

​
”contact_number header not found”

Problem: Column header is misspelled Solution: Make sure the header is exactly contact_number (lowercase, underscore)

​
“Duplicate contact”

Problem: Same phone number appears multiple times Solution: Remove duplicate rows or use different contact identifiers if needed

​
Download Example

Download our example CSV file to use as a template:

​
Next Steps

Contact Format

JSON contact format for API calls

Create Batch

API reference for batch creation