Search by keyword

Table of Contents
You are here:

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:

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

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

A Note for New York Campaigns & Orgs

If you’re using the NY BOE data for your campaign, you can’t use MyVoters VAN ID for your integration since that ID doesn’t exist in raw BOE data. Instead, please select “State File ID” for Reach External ID and select “NY State File ID” for Transform ID.

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.

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

This mapping is ready to save!
  1. Click into the Survey Quesiton in Reach Survey Questions Admin
  2. Click the Integrations Button in the “Response Options” section
  3. Under “Response” choose the first response option you want to map. For this example, let’s choose “1”
  4. Choose the integration instance you want to map using. Let’s start with your “VAN My Voters” instance.
  5. 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.
  6. 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”
  7. 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. It is not available during a free trial of Reach.

Was this article helpful?
How can we improve this article?
Please submit the reason for your vote so that we can improve the article.
Need help?