Table of Contents

VAN Integration

You are here:

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:
    • 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
    • Set VAN Contact Type (once type per VAN integration)
    • 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:
    • 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.
    • Set VAN Contact Type (once type per VAN integration)

All of these features can be individually turned on or off upon request.

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:

  • Getting your initial voter file into Reach. This is not something that is currently supported by the VAN API so we will still need you to provide your voter file to us as outlined in detail here. If you can get a manual export from VAN or purchase access to a voter file that already includes Voterfile VAN IDs, that will ensure the most reliable and predictable integration.
  • 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.
  • Send Reach Network Relationships to VAN.
  • Send Reach Contact Actions to VAN when someone taps the SMS or Email button in Reach.

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:

  1. Navigate to the API Integrations Page in VAN.
  2. Click Request an API Key in the upper right corner.
  3. Select “Reach.Vote” from the Integration dropdown and submit.
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.
  • 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 two additional fields appear:
    • VAN External ID Type: This is the ID in VAN that corresponds to the ID type you selected for the integration. It should generally match your choice for Reach External ID.
    • 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.
  • VAN Contact Type: This sets the VAN contact type you’ll use for all survey responses collected in Reach. Not all contact types are available in all VAN instances.

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 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.

Once all your 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 onetime 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. It is not available during a free trial of Reach.

Was this article helpful?
How can we improve this article?
Need help?