Spoke offers four ways to add contacts to a text campaign: 1) upload a formatted CSV file, 2) sync a list directly from VAN, 3) pull contacts that have previously been uploaded using the follow-up campaign feature, or 4) import an Action Kit report.
This article covers how to format a CSV and explains what happens once you upload your file.
Minimal formatting requirements
For Spoke to read the data in your CSV file, and to sync back to VAN (if you’re using it), you’ll need to format the CSV file in a specific way.
The first step is to save your spreadsheet as a .csv (comma separated values). If you try to upload a format other than a .csv, Spoke will be unable to read your data.
Note: Spoke can't read Excel or Numbers files.
Image showing how to save a Google Sheet as a .csv file.
Mandatory Columns
Your file must contain columns for the first name, last name, and cell of your contacts. These columns should have these exact (case insensitive) headers:
firstname (or first_name)
lastname (or last_name)
cell
In your file, that can look like this:
or this:
What if I only have phone numbers?
If you have a list with only cell phone numbers and no names, you still must include first name and last name columns. A file without these columns will not be accepted by Spoke.
Note: You just need the header row - the rest of the column can be empty. You can also use "there" as a placeholder for first names.
Do I need to format my phone numbers?
No. The numbers you include in the cell column can include parenthesis, dashes, periods, or "+1" in front of the number. For example, +18001234567, +1(800)1234567, 8001234567, 800-123-4567, are all acceptable cell inputs.
Formatting for VANID and external_id
VANID column: Formatting for VAN sync
Using VAN/Votebuilder? You can upload your data as a CSV file and still use VAN integration to sync back statuses automatically. In order for this to work, you must:
Connect your campaign to a VAN key in the “Integrations” section
Make sure your CSV includes VAN IDs in a column titled VanID (case insensitive)
If your file does not include VANIDs, or the VANIDs are in a column under a different name, data will not sync back.
External_id column: Formatting for PDI and other CRMs
if your data includes a unique ID for your contacts, you should title that column with the header name external_id. This will allow you to easily bulk upload your responses into your voter file platform once the campaign ends.
How to add Custom Fields / Merge Fields
If your CSV file contains additional columns, the headers will be treated as custom fields. There is no manual mapping step.
Custom fields can be added to scripts to make them more personal and relevant to the contact. For example, you can include fields like city, zip code, senator, polling location, or previous donation amount.
There is no limit to the number of custom fields you can have, nor is there a limit to the maximum length of the custom field.
How to format your headers
The header row of your custom fields should be formatted as “word” or “word_word”, ex: streetname, or street_name. Do not use brackets or other special characters.
Screenshot of an example CSV file with a column for a “street_name” custom field.
How to reference your custom fields
Custom fields take the form of {word} once they are in Spoke. They will automatically be available for you to use in your Spoke scripts, as shown in the image below.
Screenshot of an example script showing the custom fields available to be added.
To add the appropriate custom field to your script, click on the custom field in the Spoke script box or type it using the {word} format. When your messages are sent, the data associated with each contact (for that column) will dynamically populate in the text.
Uploading your CSV
Step 1: Click "Upload Contacts"
To upload a CSV file, simply open the “Contacts” section of your campaign, then click “Upload Contacts”.
Click “Upload Contacts” to select the CSV file from your desktop.
Step 2: Select your CSV
This will open a popup where you can select the file from your desktop. Once you’ve selected your list for upload, Spoke will read your file and let you know once it’s ready for import.
Example of what you’ll see after selecting your list. Spoke will confirm the name and size of your CSV file.
Hit “Save and Go to Next Section” to confirm that you want to add the list.
After you hit “Save”, Spoke will scan your list to remove any duplicates, invalid phone numbers, previously opted out phone numbers, and first names containing profanity.
Spoke filters the contacts in your list to find and remove non-textable numbers.
Spoke will also remove any landlines at no additional cost. This helps save you time and money by ensuring you’re not sending messages to numbers that can't text back!
Step 3: View how many contacts were removed
To view how many non-textable contacts Spoke has removed, click on the “Contacts” section after the upload has completed.
Click on “Contacts” to see an overview of how many contacts were uploaded and removed.
Spoke will display the number of contacts removed and the reason for their removal. If you are using VAN to sync a list, Spoke will also display whether VAN has removed contacts it considers non-textable.
Step 4: View how many contacts were removed after list upload
After a campaign has been started, you won’t be able to add any new contacts, but you can still click on “Contacts” to view the size of your contact list.
Image showing the “Contacts” section of a launched campaign.
If your contact list has changed after you uploaded it due to opt-outs or suppressions, the “Contacts” section will update accordingly to display only the number of contacts still remaining in the campaign.
Image showing the Contacts section of a campaign that has been started. The report will update if contacts have been removed from your campaign since you initially uploaded the list.
Profanity filter: which words are removed?
[TRIGGER WARNING for ableist, racist, sexist, homophobic slurs]: With this trigger warning in mind, you can view the list of words Spoke removes from your contacts list here.
Overwriting your list
Want to use a different list than what you uploaded? Simply upload a new list - this will overwrite the one you had uploaded previously. You can overwrite existing lists as often as you like so long as the campaign has yet to be started. Once a campaign has launched, you can no longer upload new contacts.
Troubleshooting
Error during list upload: “Missing fields: firstName, lastName, cell”
Please confirm:
Your file contains the mandatory headers (firstname, lastname, and cell) - Spoke will show an error if a mandatory header is missing.
Your file is saved as a .csv. If it is an Excel or Numbers file, Spoke will also generate this error.
There are no extra header rows in your file. If there is a header row on top of the mandatory header row, Spoke will be unable to read your file.
If you have corrected for these issues and continue to experience an error, please file a ticket here.
Custom fields won't populate
Note: Custom fields will only populate in your scripts if you add them in the "Script" or "Canned Responses" sections of your campaign. They will not populate if a texter types them in manually from the texter side of Spoke.
Custom fields appear green in the "Script" tab of your campaign when Spoke has mapped them from your CSV.
When there is a mismatch between what you type in the script field and the custom fields available, the custom field will appear orange. Orange means that that custom field will not dynamically populate information, and would literally populate for your contacts as {word}!
Example of custom fields that will populate data (in green) and a custom field that will not populate data (in orange).
If you are manually typing in your custom fields, watch for typos and keep in mind that the custom fields need to be formatted in {} in your scripts.
If you find that some of your custom fields are populating empty for contacts, this means that no data was contained in that column for the specific contact.