Contact Lists

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. A Download template button generates a correctly formatted starter file.

​

Required columns

Any additional column becomes a custom field, provided you have defined it first (see below).

​

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

​

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. Keys are normalized to lowercase snake_case.
2. Include a matching column in your CSV — its values are stored per contact.
3. In the agent’s flows and prompts, the field appears as a Campaign variable grouped under the campaign’s name. phone and zipcode are always available as built-in campaign variables.

At call time, the dialed contact’s values are injected into the agent session, so {{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.

​

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 straight away, or up to 48 hours ahead — 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 (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_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, and for the date consent was obtained when you say you hold consent, so have both ready. Uploading a CSV is still done on the Campaigns page.

​

Where to go next