{{variable}} your AI agent can use in its greeting, guidelines, and actions.
CSV Format
Upload a.csv file by drag-and-drop or click-to-browse. A Download template button generates a correctly formatted starter file.
Required columns
| Column | Format | Purpose |
|---|---|---|
phone | E.164 with country code (e.g. +15551234567) | The number to dial |
zipcode | Postal code | Resolves the contact’s local timezone for legal calling-hours checks |
has_pewc | true/false (also accepts yes/no, y/n, 1/0) | Whether you hold Prior Express Written Consent for this contact |
pewc_date | YYYY-MM-DD, M/D/YYYY, MM/DD/YYYY, or written month (e.g. Apr 19 2026) | When PEWC was captured — required whenever has_pewc is true |
is_voice_call_opted_out | true/false | If true, the contact is never dialed, regardless of PEWC |
Phone number normalization
Numbers are validated and normalized to E.164 on upload. Accepted inputs include full E.164, digits-only international numbers (a+ is added), 7–10 digit US national numbers, and dashed or spaced formats. Invalid numbers are reported per row and skipped — they never fail the whole upload.
Limits
| Constraint | Limit |
|---|---|
| Contacts per CSV upload | 100,000 (split larger lists into multiple uploads) |
| Custom fields per campaign | 50 keys |
| Custom field data per contact | 16 KB |
| Custom field value length at call time | 500 characters (longer values are truncated) |
| Row errors displayed | First 200 (all are counted) |
Custom Fields → Agent Variables
Define custom fields in the Custom contact fields panel before uploading columns that use them:- Type a field name (e.g.
first_name) and press Enter. Keys are normalized to lowercase snake_case. - Include a matching column in your CSV — its values are stored per contact.
- In the agent’s flows and prompts, the field appears as a Campaign variable grouped under the campaign’s name.
phoneandzipcodeare always available as built-in campaign variables.
{{first_name}} in the greeting speaks the right name for every call.
Upload Behavior
Uploads are parsed in your browser, validated row by row, and sent in batches — keep the tab open until the progress bar completes. The results screen then breaks down exactly what happened:- Contacts added — new rows inserted.
- Contacts updated — rows whose phone number already existed in the campaign. Re-uploading a contact updates its zipcode, consent fields, and custom fields rather than being skipped, so you can refresh compliance data by re-importing.
- Duplicates (file) — the same phone appeared more than once in the file; the last row wins.
- Invalid — rows that failed validation, listed with row number, phone, and reason.
Contacts with
is_voice_call_opted_out = true are registered on your internal Do-Not-Call list. If your account has no SAN configured yet, the upload still succeeds and shows a warning — those contacts are registered automatically once you save a SAN. See Compliance & DNC.Managing the List
The contacts table shows Phone, Zipcode, the three consent columns (with explanatory tooltips), and up to six custom columns, paginated 50 per page.- Add more — upload another CSV; existing contacts are updated, new ones added.
- Clear all — remove every contact (inline confirmation required). Only available while the campaign is editable.
Best Practices
- One source of truth. Export from your CRM right before launch so consent flags are current — re-importing refreshes existing contacts.
- Keep custom fields lean. Only include columns the agent actually needs; every field is injected into the conversation context.
- Test with real data shapes. Place a test call with sample custom-field values to confirm variables resolve as expected.
- Mind consent dates.
pewc_dateis required wheneverhas_pewcis true — rows missing it are rejected at upload and blocked from dialing.
Where to go next
Scheduling
Configure the calling windows before launch.
Compliance & DNC
How consent fields and DNC scrubbing gate each dial.