When you integrate Spoke with VAN, it allows you to load lists and sync back canvassed statuses, activist codes, survey questions, and event statuses from Spoke to VAN in real time. There are four steps to setting up the integration:
Requesting your API Key in VAN
Saving your API Key in Spoke
Linking your VAN folder/s to Spoke
Integrating your campaigns in Spoke
Once you have completed these steps, you can also load lists and sync survey responses back to VAN, as we outline further below.
TABLE OF CONTENTS |
1. Requesting your API Key in VAN
On the Main Menu page in VAN, find the section titled Administrative Menu. Click on Integrations, then click on API Integrations.
Image displaying where to find “API Integrations” in the VAN “Administrative Menu”.
On the API Integrations page, click the blue Request an API Key button in the upper right corner.
Image showing where to find the “Request an API Key” button on the API Integrations page.
From the window that pops up, select Scale to Win from the Integration drop down menu. Then use the “Request will be sent to” drop down menu to select the person you want to request your key from.
Image displaying the “Request an API Key” popup window.
If you don't see Scale to Win in the dropdown, you’ll need to send NGP / VAN a quick email requesting the key. They typically turn this around in less than 24 hours.
After the request is approved, you’ll be notified via email that you can generate your API Key in VAN.
IMPORTANT: Before you click the generate API key button in VAN, make sure you are ready to write down or copy and save the key that is generated, because you will only be able to view it once. |
Clicking the Generate API Key button gives you two pieces of information:
- Application Name - usually written in some variance of DNCFL.004.scaletowin. This is also accessible after you generate the key.
- API Key - written in a form of numbers, letters, and dashes. You can only view the key once.
You’ll enter both pieces of information into Spoke to save your VAN API key.
2. Saving your VAN API Key in Spoke
To add your VAN API Key information to Spoke, you'll need Owner permissions.
As an Owner, go to the admin side of Spoke. Click on Settings. Then click the Manage API Keys button in the upper right corner.
Image showing where to find the “Manage API Keys” button on the Settings page.
This will open a page for you to enter and view your API Keys. To add your new key, click the green + button in the bottom right corner.
Image showing where to find the green + button to add a new API key.
An “Add/Edit Api Key” window will pop up.
Image showing the Add/Edit Api Key popup window.
You’ll want to fill out each of these fields. Here’s what they mean:
| Key Type | Select whether your key is for MyVoters or MyCampaign/Everyaction/LAN |
| Key Nickname | Enter the name you'll use to find this key in Spoke. For example, “My Voters” |
| Key Name (Assigned By VAN) | Enter the Application Name generated with your API Key |
| Key Value | Enter the actual API Key here - the string of numbers, letters and dashes you generated in VAN |
Filled out, the window will look something like this:
Example of the window to Add or Edit an API Key.
Click Save to add the API key to Spoke.
Note: you will need to create separate entries for My Campaign and My Voters, even if both use the same VAN key.
After saving your key(s), you'll see the type and name of your each saved key listed on the "Manage API Keys" page.
Example of saved API keys in Spoke.
3. Linking your folder/s in VAN to Spoke
Linking your folders will allow you to upload saved lists from VAN directly into your Spoke campaigns. If you wish to upload your lists as CSV files instead, you can skip this step.
To set up the ability to sync lists from VAN, go to My Folders in VAN.
Example of the "My Folders" section in VAN.
Add a new folder or edit an existing one. Then, check the box "Allow other users to save into this folder".
Image of the checkbox to “Allow other users to save into this folder”.
Click the blue Save button. You will now have the option to add users to save into the folder in a section called "User Access" (you may have to scroll down to see this).
Add the "API User, Scale to Win" to the "Users with Access" by selecting the API User and hitting Add, then hti
Find the user titled “API User, Scale to Win” and add that user to the folder, then click Save.
Next, save your lists in the folder you've made accessible to the Scale to Win API. You'll only be able to sync lists with Spoke if they are in a folder the API User can access. You can share multiple folders with the API User.
Keep in mind that only Saved Lists can be imported - Saved Searches are not supported. Moreover, the maximum limit for a list is around 150,000 phone numbers. Lists larger than the maximum will not appear in your Spoke.
4. Integrate your campaigns in Spoke
Now that you have an API key in your Spoke, you can connect your text campaigns to VAN. To do this, you’ll need to select the key in the campaigns you wish to sync back to VAN.
Each campaign you create has a section called Integrations. Open that, then select the nickname of the API key you want to connect to the campaign.
Image showing how to select an API Key from the Integrations section of a campaign.
Now that your campaign has been integrated with VAN, Spoke will sync back "Texted" as a canvass status to any contact you proceed to message in your texting campaign. We will only apply this canvass status once per contact per texting campaign.
If you do not select a key, your campaign will not automatically sync back to VAN.
Note: you cannot connect a campaign to a VAN key after you hit the "Start" button and launch the campaign. If you need to integrate your campaign with VAN after the fact, you can always bulk upload your campaign data exports so long as your contact list included a column with VAN IDs.
Loading Lists from VAN
Once you have completed all steps above, you can pull saved lists from VAN. Some notes on that:
VAN integration only supports importing saved lists. Saved searches must be saved as a new list before being imported.
Lists should contain no more than 250,000 contacts. Larger lists will not appear in Spoke.
VAN integration for texting platforms only supports importing the numbers that VAN considers "textable," so you may see a difference between the number of contacts in your campaign and the number of phone numbers displayed in VAN. When you're building your list in VAN you can also specifically select "Textable Phones Only" in the phones section to get a more accurate count of how many contacts you'll be able to import.
To sync your lists directly from VAN, go to the Contacts section of your campaign. If you have integrated your campaign with an API key, you will be able to select NGP VAN as the contact upload method.
Image displaying where to select “NGP VAN” in the Contacts section of your campaign.
After selecting "NGP VAN" as your upload method, you'll see a text field (“Select a list to import”) where you can type in the name of the list you'd like to access in VAN.
Image displaying where to start typing to bring up a dropdown with all available lists to sync from VAN.
After you begin typing, Spoke will show you all available lists matching your search. Click the correct name in the dropdown list to select your contacts.
Click Save, and the list from VAN will be uploaded into your Spoke platform.
After your list has been imported, click on "Contacts" again to see a report of how many contacts uploaded successfully.
Image displaying the contact list report for a list synced from VAN.
Spoke will report how many landlines, opt-outs, and duplicates were removed, and whether VAN removed any non-textable contacts.
Note: Spoke only removes landlines, duplicates of the same number in the list, names containing profanity, and Opt-Outs. If numbers have been removed by VAN, Spoke will list how many of the numbers in your list were specifically excluded by VAN, as shown in the image above.
Syncing additional statuses back to VAN
There are two ways to sync additional canvass statuses, survey responses, event statuses, and activist codes back to NGP VAN: using our scripting features or using our tags feature.
To sync data back from tags, check out this article.
To sync data back from scripts: For each response in the Script section of your campaign, you will have a field to add an Action Handler.
Image displaying the “Action Handler” dropdown in a response. This is only visible if you have selected NGP VAN in the Integrations section of the campaign.
For responses that you want to sync back to VAN, click that box and select NGP VAN Action (or NGP Event if you are syncing a VAN event). A text field will appear where you can begin typing to pull up activist codes, survey responses, canvass responses, or event statuses.
Image displaying how you can type in and search for your VAN activist codes, survey responses, and canvass responses after selecting “NGP VAN Action” as the Action Handler.
Once you save your scripts, the response you want to track will automatically sync back to VAN.
Here’s an example of what a wrong number response might look like with the VAN Action Handler selected:
Screenshot of a wrong number canvass response added to a script.