Skip to main content
The Contacts tab holds the campaign’s target list. Upload a CSV, and every extra column you define becomes a {{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. Download Template (on an empty list) or Download template (in the upload panel) generates a correctly formatted starter file named contacts_template.csv. It has the five required columns, a column for each custom field you’ve defined, an example row, and a few # comment lines explaining the formats. Lines that start with # are ignored on upload, so you can leave them in. Before anything is uploaded, Studio checks the file and stops with a message if a required column is missing (Missing required column: … or Missing required columns: …), if the file has no data rows (CSV has no data rows.), or if it holds more than 100,000 rows. Fix the file and drop it again.

Required columns

Reading dates. Slash dates are US-style, month first: 3/7/2024 is March 7, not July 3. A day-first date is rejected when the day is above 12, such as 19/04/2026. When the day is 12 or lower, the date is read month first without any warning: 03/07/2024 becomes March 7, even if you meant 3 July. Check dates exported from non-US systems before you upload. Written months take no comma: Apr 19 2026 and April 19 2026 work, but Apr 19, 2026 is rejected. A CSV upload also accepts two-digit years such as 3/7/24. The date is kept only when has_pewc is true. On other rows it is ignored, so a date Studio can’t read causes a row error only where has_pewc is true. Any additional column becomes a custom field, but only if you have defined it in the Custom contact fields panel first (see below). Every extra column that has a value on a row must already be defined, or that row is rejected as Invalid. The reason in Row errors begins custom_fields key ”…” is not defined, or This campaign has no custom field configuration when the campaign has no custom fields at all. A rejected row isn’t imported, but the rest of the file is. Define the column first or remove it from the file. An empty cell is skipped and never causes a rejection. Column headers are matched ignoring capital letters and any spaces around the name, and nothing else is changed. A header must therefore equal the field name: First Name does not match a field named first_name, and spaces are not turned into underscores. A column whose header doesn’t match counts as undefined.
Format the phone column as Text in Excel or Google Sheets before saving. The uploader detects and rejects the two classic spreadsheet corruptions — dashed numbers evaluated as arithmetic (+1-206-555-0109 → -869) and long numbers truncated to scientific notation — with a row-level error explaining the fix.

Phone number normalization

Numbers are validated and normalized to E.164 on upload. Accepted inputs include full E.164, digits-only international numbers that start with the country code (a + is added), US numbers without a country code, and dashed or spaced formats. A US number without a country code needs all 10 digits and a valid area code. 408-555-1234 and (408) 555-1234 both become +14085551234, and a 7-digit local number is rejected. Invalid numbers are reported per row and skipped — they never fail the whole upload.

Limits

A row that goes over the 50-key or 16 KB limit is rejected as Invalid.

Custom Fields → Agent Variables

Define custom fields in the Custom contact fields panel before uploading columns that use them:
  1. Type a field name (e.g. first_name) and press Enter or select Add. What you type is lowercased, spaces become underscores and other punctuation is dropped, so First Name becomes first_name. The five required column names (phone, zipcode, has_pewc, pewc_date and is_voice_call_opted_out) are reserved, and a name can only be added once.
  2. Include a matching column in your CSV — its values are stored per contact. The header must be the field name itself (first_name, not First Name), because CSV headers are not converted the way the panel input is.
  3. In the agent’s flows and prompts, type {{ to open the variable picker. The field is listed in a group named for your campaign, as <Campaign name> / <Field name> — for example Summer Outreach / First Name for a field called first_name. The field name is shown in Title Case. Pick it from the list rather than typing it by hand. The built-in fields are always listed too, as Summer Outreach / Phone and Summer Outreach / Post Code. Post Code holds the contact’s zipcode value.
Campaign variables are listed only for the AI agent the campaign is assigned to. They aren’t offered on the Chat and Email tabs of Greeting & Sign-off, because they hold per-contact data from a voice campaign. At call time, the dialed contact’s values are injected into the agent session, so {{Summer Outreach / First Name}} in the greeting speaks the right name for every call.
Removing a custom field (the x on its tag in the panel) deletes its campaign variable. Any flow node or prompt that still references it will break, and the removal can’t be undone. Studio asks you to confirm in a Remove field? dialog first, but the dialog doesn’t show what uses the field, so check your agent before you remove it.

Upload Behavior

Uploads are parsed in your browser, validated row by row, and sent in batches of 500 rows — keep the tab open until the progress bar completes. The results screen then breaks down exactly what happened, in five counts:
  • 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.
  • Invalid — rows that failed validation, listed with row number, phone, and reason.
  • Duplicates (file) — the same phone appeared more than once in the file; the last row wins. Repeats are spotted within each batch of 500 rows, so a repeat that lands in a later batch is counted as Contacts updated instead.
  • Duplicates (campaign name) — this tile carries your campaign’s name, for example Duplicates (Summer Outreach). It counts rows whose phone number was already in the campaign, so it is always the same number as Contacts updated.
If no contacts were added or updated, the screen says No new contacts were added. All rows were duplicates or invalid. Row errors under the counts is not only a list of failures. It also has an informational line for every contact that was updated (Existing contact updated with latest compliance values) and for every in-file duplicate (Duplicate phone number within this upload — row N takes precedence, listed against the earlier row). Its total can therefore be higher than Invalid, and a re-upload where nothing failed still shows a list. Only the first 200 lines are displayed. Rows with an unreadable phone number, or a has_pewc or is_voice_call_opted_out value Studio doesn’t recognize, are added at the end of the list. When you re-import a large list, they can fall below that cut-off even though Invalid counts them.
Contacts with is_voice_call_opted_out = true are registered on your internal Do-Not-Call list. Re-uploading an existing contact with is_voice_call_opted_out changed from true to false takes that number off the list again, when a SAN is configured. See Compliance & DNC.If a contact can’t be registered, the upload still succeeds and a warning says that opted-out contacts were saved but could not be registered with the IDNC list, which is your internal Do-Not-Call list. This is usually because your account has no SAN configured yet — those contacts are registered automatically once you save a SAN. The warning also appears if the Do-Not-Call service was unavailable at that moment. Saving the same SAN again does not retry in that case, so email support@squawkvoice.ai if you need help getting those numbers registered. Either way, the contacts stay marked as opted out and this campaign does not dial them.

Adding Contacts Over the API

Contacts do not have to arrive as a CSV. The On-Demand Call API adds one contact at a time and dials it as soon as the campaign’s calling hours allow, or at a time up to 48 hours ahead. The call is only placed when the request includes the consent fields (has_pewc and pewc_date). It is useful when the trigger lives in your own systems rather than in a list. Two differences from a CSV upload worth knowing:
  • Postcodes may be sent as a string or a number, but send a leading-zero postcode as a string. JSON drops the zero before SquawkVoice ever sees it (02134 arrives as 2134), and the postcode is what resolves a contact’s local timezone for legal calling hours. An on-demand call with an unresolvable postcode is rejected outright; a batch upload stores the shortened value and falls back to the phone number’s area code at dial time, so hours are still enforced but less precisely. A postcode sent as any other type is reported as an invalid row.
  • Repeat submissions of the same number are accepted on an on-demand run — each is its own attempt with its own request_id. The one-number-per-run rule still applies to CSV uploads.

Managing the List

The contacts table shows Phone, Zipcode, the three consent columns — Has PEWC, PEWC date and Voice consent OK, each with an explanatory tooltip — and up to six custom columns, paginated 50 per page. Voice consent OK is the opposite of the is_voice_call_opted_out column in your CSV. It shows Yes when is_voice_call_opted_out is false and No when it is true, and a No contact is never dialed.
  • Upload CSV and Add more — upload a CSV; existing contacts are updated, new ones added. Upload CSV sits next to Download Template while the list is empty, and becomes Add more once the list has contacts.
  • Clear all — remove every contact (inline confirmation required).
Upload CSV, Add more, Clear all and the Custom contact fields panel appear only while the campaign is editable: in Draft, Stopped, Completed or Failed status. In any other status, such as while a run is active or paused, they are hidden.

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. A test call reaches the agent’s published version once it has one, unlike Talk, so publish first if you’ve changed the agent.
  • Mind consent dates. pewc_date is required whenever has_pewc is true — rows missing it are rejected at upload and blocked from dialing.
  • Adding contacts through the Co-pilot? The Squawk Co-pilot asks for each contact’s postcode up front, whether consent is on record (and the date it was obtained, when it is) and whether the contact has opted out of voice calls, and never assumes either answer, so have them ready. A number already in the campaign is updated with the answers you give. You can also attach a contacts CSV in the chat with the paperclip and say which campaign it is for. The Co-pilot loads up to 5,000 contacts from a file of up to 10 MB, by the same rules as Upload CSV, and only while the campaign is in Draft, Stopped, Completed or Failed status. The contacts appear on the Contacts tab as soon as it finishes, and no calls are placed. The Co-pilot can’t read what is in the file, so check it against Download template first. For a larger file, use Upload CSV on the Contacts tab (the button reads Add more once the campaign has contacts).

Where to go next

Scheduling

Configure the calling windows before launch.

Compliance & DNC

How consent fields and DNC scrubbing gate each dial.