Video Tutorial: Setting Up Your VAN Integration

  • Updated
If this is your first time setting up an NGP VAN integration, we recommend reviewing the NGP VAN Getting Started Guide

Introduction

Impactive offers an integration with NGP VAN so that campaigns can keep their VAN instance synchronized with Impactive. 

Contents

1. How it works

2. Setting up the VAN integration

3. Sync instructions

4. Common Workflows

5. Troubleshooting

How it works

Admins can synchronize the following data between VAN and Impactive.

    • Sync a saved list in VAN over to Impactive
    • Pass Impactive tags or custom fields to VAN Activist Codes or Survey Questions
    • Pass Impactive opt-out, peer-to-peer, friend-to-friend message tags to VAN Canvass Results and their respective contact type 

<

Setting up the VAN integration

Getting your VAN integration configured will require you to navigate outside of Impactive to obtain your VAN API key. This credential will give Impactive access to sync data over to your database.

Obtaining a VAN API key

To set up the VAN integration, first, obtain an API key from NGP VAN. You can accomplish by doing the following:

  1. Log in to VAN
  2. Click “Integrations” in the bottom left of the screen under the “Administrative Menu”
  3. Click “API Integrations” from the dropdown list
  4. Click the blue “Request an API Key” button on the next screen
  5. Choose “Outvote” from the first dropdown list in the pop-up window
  6. Choose the appropriate VAN administrator from the second dropdown list in the pop-up window
  7. Select “Submit Request” in the bottom right of the pop-up window
  8. Once your request has been authorized, you will be provided with a link to navigate back to the API Integrations page in order to generate your API key
  9. Obtain your API key and copy it for use in Impactive

If you are unable to find the Integrations page in VAN, reach out to your VAN administrator to request this information.

Add your VAN API key to Impactive

Now lets navigate back to the Impactive admin interface. On the admin sidebar, click on “Settings” and navigate over to the “Integrations” tab.

From here, click on the “+ Add API key” button. The button will open a modal and you can add your VAN API credentials here.

van_apikey.png

The configuration screen

Enter a name for the integration in the Name field of the pop-up window. We recommend naming the integration based on your committee/VAN instance, such as “Impactive VAN MyVoters integration”.

Next, select “NGP VAN” under the integration type dropdown menu.

Last, copy and paste your VAN API key into the API key field.

Once you’ve included all your integration information in the fields, click create. 

If your configuration was successful, you’ll see “Active” under your Integration in the API key summary. If your configuration was unsuccessful, you’ll see an “Error” under status.

van_apikeysummary.png

A successful integration

Sync instructions

Once the Impactive <> VAN integration is configured, you’ll need to configure a sync instruction.

A sync instruction is basically a setting that tells Impactive what data to synchronize over to the VAN database.

You can find sync instructions under Settings > Integrations directly below the API keys summary table.

van_syncinstruction.png

Overview

To create a sync instruction, click the “+ Create Sync Instruction” button at the very top of the sync instruction summary table.

This button will open a modal that will allow you to configure your sync instructions.


van_syncinstruction_impactive.png

Configuration

The sync instruction modal will include a number of components to configure. There are numerous components here and it’s easy to get overwhelmed, but rest assured: the goal is to match an Impactive tool (called instruction in the admin interface) with a VAN endpoint (called type in the admin interface). 

You can synchronize the following Impactive tools:

  • Tags
  • Custom fields
  • Contact lists
  • Sync hooks

To the following VAN endpoints:

  • Activist Code
  • Codes
  • Supporter Group
  • Result Code
  • Canvass Response
  • Survey Question

Impactive components

The following components are mandatory to set up on the sync instruction configuration.

  • Instructions for (integration type): toggle “NGP VAN” under instructions. 
  • Instruction name: name the instruction under “Name”*.
  • Instructions for (tool): tags, lists, custom fields or sync hooks
  • For [tool name]: particular name of the tool you want to sync above

VAN components

The following components are mandatory to set up on the sync instruction configuration.

  • Sync [tool] with integration: choose your API key here
  • Database mode: select the particular VAN DB to sync to, either My Voters or My Campaign
  • Type: VAN endpoint could be an Activist Code, Codes, Supporter Group, Result Code, Canvass Response, or Survey Question

Variable VAN components

Depending on the VAN endpoint selected under “Type”, an additional level of components will need to be configured. See the name of the Impactive components and their respective matching endpoints in VAN below.

Activist Code

  • Object: a name for the Activist Code

Canvass Response

  • Object: Contact type (SMSText, Bulk, etc.)
  • Result code: Result code (Busy, Callback)

Result Code

  • Result code: Result code (Busy, Canvassed, Callback)

Survey Question

  • Object: name of the survey question
  • Response: survey question answers

Contact List

  • VAN Export Types: we recommend choosing SmsSync
  • VAN Folders: folder where your list is saved
  • VAN List to Sync: list to sync over to Impactive

*As a best practice, we recommend that your instruction name follow the format “Tool: Name of item”. For example, if you are integrating an Impactive tag called “Volunteer”, name the instruction “Tag: Volunteer”.

 

Common Workflows

Sync a VAN list to Impactive

See “Integrations and Automations: How to Sync a Saved List from NGP VAN“.

Syncing P2P and F2F Message custom fields to "Texted" fields in VAN

See “Syncing P2P and F2F Custom Fields to VAN”.

Sync multiple choice custom fields to VAN survey questions

Did your volunteers obtain important survey information during their conversations with voters using Impactive? Use a custom field sync instruction to pass back the results of these survey questions to VAN.

First, set up a sync instruction for the custom field and pass it back to the VAN “survey questions” type.

Next, select the appropriate custom field under object. You’ll then need to map the multiple-choice responses to the correct survey question response. Click “create” when the configuration is complete.

unnamed.png

A visual of the configuration for a survey question sync

Sync “opt-out” tag

Need to track if voters or contacts have unsubscribed? Impactive automatically tags voters who have unsubscribed from peer-to-peer campaigns using the opt-out tag.

Set up a sync instruction for the opt-out tag and pass it back to the VAN “result code” type as a “Do not text” object. This will ensure all texting opt-outs in Impactive are labeled as “do not text” in VAN.

Sync “canvassed at” custom field

Need to track which voters or contacts have been canvassed on Impactive? Impactive automatically appends a custom field to contacts when canvassed in an open canvassing action. 

Set up a sync instruction for the “canvassed at” custom field and pass it back to the VAN as a “canvasser response” type. We encourage you to use the “Walk” object and the “Canvassed” result code. This will ensure all canvassed contacts in Impactive are show up as canvassed in NGP VAN.

Troubleshooting

I’ve contacted voters in Impactive, but I’m not seeing the results in NGP VAN.

If you’ve contacted voters in Impactive, but are not seeing them in NGP VAN, we encourage you to review the following:

  1. Review whether the voter(s) exist in either My Voters or My Campaign.
  2. Review if your voter(s) VAN ID matches a VAN ID in your NGP VAN database. Impactive cannot match to NGP VAN if there is no corresponding VAN ID.

Still experiencing issues? Contact support@impactive.io for more assistance.

Was this article helpful?

/