VAN Integration
Many of our campaigns and organizations use Reach alongside VAN and we know how important it is to get all your campaign’s data flowing smoothly, seamlessly, and efficiently between the tools you use. We have been the people tasked with importing and exporting CSVs at 3am to move data manually between a bunch of different tools and we deeply understand how painful that process is. That is why we’re pleased to offer an API-based VAN integration that will make getting your data from Reach to VAN a snap! Read on to learn how it works and get answers to frequently-asked questions.
VAN Integration Functionality
What can the VAN Integration do?
The VAN integration allows data collected in Reach to sync to VAN automatically and in real time. It currently includes the following features a capabilities:
- My Voters Database (syncs from imported voters in Reach):
- Send Reach Survey Responses to VAN Survey Responses
- Send Reach Survey Responses to VAN Activist Codes
- Send Reach Survey Responses to VAN Canvass Results (like “Not Home” or “Moved”)
- Send Reach Long Text and Short Text Survey Responses as VAN Notes
- Send Reach Contact Actions to VAN when someone taps a Contact Action button in Reach. Due to limitations with the VAN API, Reach can only send one contact history entry per hour for a voter to Reach. So, if you Message someone, and then Email them two minutes later, only the first Contact Action will sync to VAN.
- Set VAN Contact Type (one for each type of Contact Actions and one for Reach Survey Responses.)
- Send data about voters either via Voterfile VAN ID or by another supported External ID that exists in both Reach and VAN.
- My Campaign Database (syncs from new “Reach Adds” in Reach):
- Send Reach Survey Responses to VAN Survey Responses
- Send Reach Survey Responses to VAN Activist Codes
- Send Reach Survey Responses to VAN Canvass Results (like “Not Home” or “Moved”)
- Send Reach Long Text and Short Text Survey Responses as VAN Notes
- Send new people added in Reach (“Reach Adds”) to My Campaign and match them to existing My Campaign people if someone already exists in My Campaign who is similar enough.
- Send edits to an added person’s name or address to the VAN record in My Campaign.
- Send phone numbers and email addresses of added people to the VAN record in My Campaign.
- Send new users on your campaign to My Campaign and match them to existing My Campaign people if someone already exists in My Campaign who is similar enough.
- Send user edits to My Campaign.
- Send Reach Contact Actions to VAN when someone taps a Contact Action button in Reach. Due to limitations with the VAN API, Reach can only send one contact history entry per hour for a voter to Reach. So, if you Message someone, and then Email them two minutes later, only the first Contact Action will sync to VAN.
- Set VAN Contact Type (one for each type of Contact Actions and one for Reach Survey Responses)
All of these features can be individually turned on or off in the Features tab of your Integration Instance in the Integrations Admin screen.
What can the VAN Integration not do?
We are constantly building new features and functionality, but some there are some specific things we want to note as not being included in the current VAN Integration:
- Track which Reach users took which actions. Everything that Reach syncs to VAN will show up in VAN as having been added “Reach.Vote API User”
- Track Reach Network relationships and relationship types
- Using “Phone” or “Text” contact types. VAN has chosen to not to support phone and text-based contact types from relational tools like Reach. In order to protect the privacy and preferences of your users, these contact types are not available.
- Sending phone numbers and email addresses for voters to VAN. While we do send emails and phone numbers to people in My Campaign, the VAN API does not support adding phone numbers or email addresses to voters in the voter file. You can always still export these from Reach and bulk upload them to VAN if you have permissions to Bulk Apply phones or emails.
- Send Reach Tags to VAN.
- Add voters to My Campaign.
- Integrate with the VAN Voter Registration Screen
- Send your initial voter file into Reach. You can learn more about how voter data gets into Reach here.
Some of these things are simply not possible with the VAN API and others are things that we could add support for in the future if they are important to our clients. If this is important to you let us know at https://feedback.reach.vote.
VAN Integration Setup
Request a VAN API Key
The first step to setting any any VAN integration is to request an API Key in VAN:
- Navigate to the API Integrations Page in VAN.
- Click Request an API Key in the upper right corner.
- Select “Reach.Vote” from the Integration dropdown and submit.
Create an Integration Instance
After you’ve received your API key from VAN, you need to create integrations instances for each My Voters and My Campaign in the Integrations Admin screen in the Admin Dashboard.Tap the ‘+’ icon on the right hand side of an integration type to add a new integration instance. You should include the following:
Configuration
- Integration Name
- Status: You can toggle an integration between being Active and Inactive. Inactive instances will not actually send any data to VAN.
- Process People From: (only shown in certain cases – you can probably skip this!)This is where you choose the type of people this instance should process. For My Voters, choose your imported voter file. For My Campaign, choose your Reach Adds.
- Application Name: This is provided when you request your API key from VAN.
- API Key: Think of an API Key like a password for computers to talk to each other. You should guard this like a bank password, and never share it in plain text via any method at all.
- Reach External ID: Pick the external ID from your Reach data that you want to use for VAN sync. In most cases, this should be a VAN ID, In the integration instance for My Voters, if you select an ID other than VAN ID (like State File ID) then you’ll see an additional field appear:
- Transform ID: This is in case you need to apply formatting (like removing leading 0’s) to make the external IDs in your Reach data match the format of that ID in VAN.
Next, you’ll need to set Contact Types for each of the 6 Reach canvassing options. By default, no Contact Type will be assigned in your integrations – it will just show up as a general “contacted” in VAN. Not all contact types are available in all VAN instances.
- Synced Responses: This is applied for all survey responses collected.
- Phone: This applies to the “Call” Contact Action.
- Email: This applies to the “Email” Contact Action.
- SMS: This applies to the “Message using SMS/iMessage” Contact Action.
- Message with another App: This applies to the “Message using another app” Contact Action.
- Mark as Contacted: This applies to the “Mark as Contacted” Contact Action.
Please be careful with contact type mapping. Unfortunately, not all contacts types are available in all VAN instances and many of the contact types you might like to use are not allowed due to restrictions of VAN’s API. All of the phone and text contact types (including “Relational Call” and “Relational Text'”) would require us to provide the phone number called or texted to VAN. In many cases, your Reach users will be calling and texting phone numbers they have asked us to keep private and we respect their wishes. So, until VAN changes their mind, we cannot sync contact attempts from Reach as phone or text based VAN Contact Types. If you wish this was possible, so do we! Please let VAN know!
Features
Before saving your integration, be sure to select which features you want included in the integration. All features are turned on by default, but you can turn off/on the following features:
- Create Notes
- Send Added People (My Campaign only)
- Send Users to My Campaign (My Campaign only)
- Send Contact Actions: Email
- Send Contact Actions: Mark as Contacted
- Send Contact Actions: Message
- Send Contact Actions: Phone
- Send Contact Actions: SMS
- Send Mapped Activist Codes
- Send Mapped Canvass Results
- Send Mapped Survey Responses
- Send Person Edits (My Campaign only)
API Key Security Note
Think of an API Key like a password for computers to talk to each other. Just like you connect to your online banking with a password, Reach connects to VAN with an API Key. So please treat it as you would a password that you care deeply about. API Keys should never be shared as plain text via any method at all. If you need to send an API Key to someone over the internet, we recommend sharing it using a service like https://onetimesecret.com/
Mapping your Reach data to VAN
One your initial setup steps are complete, it is now time to map your Reach Survey Questions to various items in VAN so the data can start flowing. This takes place on the Reach Survey Questions Admin screen. When you enter into a specific question, you’ll see and “Integrations” button. Until you have integrations setup, it will be disabled with a tooltip like this:
Once you we the integrations configured, you’ll be able to tap on the button to pick which response you want to map and map it to any Survey Response, Activist Code, or Canvass Result code in VAN!
Each Reach response can have multiple mappings. Frequently, you may want to map each question to the My Voters question in VAN and the My Campaign question in VAN as shown above.
Mapping Example
Let’s say you want to map a Numerical Scale “Support Score” question to VAN. You’ll want to go through each Response Option in Reach and choose the equivalent Survey Response in VAN. Here are the steps to do it:
- Click into the Survey Quesiton in Reach Survey Questions Admin
- Click the Integrations Button in the “Response Options” section
- Under “Response” choose the first response option you want to map. For this example, let’s choose “1”
- Choose the integration instance you want to map using. Let’s start with your “VAN My Voters” instance.
- Choose the VAN Mapping Destination. If your integration is set up correctly, you will see on this drop-down all your available Survey Questions, Activist Codes, and Canvass Results. Pick the Survey Question that is the equivalent of the one you’re working on in Reach.
- Choose the NGP VAN Response. This dropdown will contain all the available Survey Responses from VAN for the Question you chose above. Pick the equivalent response. In our case, “1 – Strong Support”
- Click “Save Mapping”.
You’ve done it! You’ll now see that new mapping listed for that Response Option. You can add a second mapping for the same Response Option by clicking “Add Mapping” or switch to a different Response Option like “2” and map that to the same Survey Question but a different Survey Response in VAN.
Once any questions are mapped, saved responses will start appearing in VAN immediately.
If you need to get any historical responses from Reach into VAN, you’ll need to do a one-time load of historical responses by pulling your Responses export from your Export screen in the Admin Dashboard, and loading it into VAN using VAN’s upload tool.
Who can use the VAN Integration?
The VAN integration is available to all Reach Complete and Reach Movement campaigns.
VAN Error Handling, Notification, and Troubleshooting
From time to time, VAN will return errors when we try to send it data via the integration. This can happen for many reasons. We believe it is crucial that you are aware when something prevents you data from flowing as you’d expect, so we proactively email you when we get errors back from VAN.
By default, all VAN error emails get sent to all Admins and Owners on your campaign. If you would like these emails to instead be sent to a different set of email addresses, please contact [email protected] after you have created the Integration Instance and we can make this adjustment for you.
We divide errors from VAN into three categories:
P1: The whole Integration Instance is broken and will not work
This most often happens if the VAN API Key you have used in Reach has expired or is invalid. Nothing we send to VAN using this API Key will work. If we get an error like this from VAN, we will deactivate the entire integration instance and email you. Here are the most common steps to fix this sort of issue:
- Obtain a valid non-expired API key for your VAN instance
- Visit the Integrations Admin screen in Reach
- Find the Integration Instance with the issue. You’ll notice its status is shown as “Inactive”. Click on it to open the right side bar. Make sure you’re on the “Configuration” tab.
- Paste your new API key into the “API Key” field.
- At the top of the side bar, use the “Status” drop-down to set the instance back to “Active”.
- Click Save in the side bar’s footer.
P2: One feature of the Integration Instance is broken and will not work
This most often happens when an integration is configured incorrectly or something has changed in VAN. For example, perhaps you chose a Contact Type or External ID that is not available in your VAN instance. Or perhaps a Survey Question or Activist Code is no longer available in your VAN instance. The email notification we send you will explain the specific error. Here are some steps you might take to fix this sort of issue:
- Confirm in VAN what is available or not, fix the issue in VAN, or contact VAN support for help.
- In Reach Admin, correct the issue.
- For missing Survey Questions or Activist Codes, follow the instructions earlier in this article to re-map your Reach Survey Questions to different Survey Questions or Activist Codes in VAN
- For invalid Contact Types, change which contact types you’re using for the integration from the “Configuration” tab of the integration instance editor side bar. Save those changes.
- Once the root cause of the issue is fixed, visit the Integrations Admin screen in Reach
- Find the Integration Instance with the issue. Click on it to open the right side bar. Switch to the “Features” tab.
- Notice that at least one of the features is switched off due to the error. Switch it back on.
- Click Save in the side bar’s footer.
P3: Certain data is being reject by VAN
This may happen when VAN has internal errors or considers certain data to be invalid. This means that at least some data was prevented from flowing into VAN, but it does not mean that future data will also fail to flow. In this case, we will email you to let you know about the issue, but we will not deactivate any integrations or features. No action is required from you.
