If this is your first time setting up an NGP VAN integration, we recommend reviewing our integrations getting started guide. |
Introduction
Impactive offers an integration with NGP VAN so that campaigns can keep their VAN instance synchronized with Impactive.
Contents
|
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:
Log in to VAN
Click “Integrations” in the bottom left of the screen under the “Administrative Menu”
Click “API Integrations” from the dropdown list
Click the blue “Request an API Key” button on the next screen
Choose “Outvote” from the first dropdown list in the pop-up window
Choose the appropriate VAN administrator from the second dropdown list in the pop-up window
Select “Submit Request” in the bottom right of the pop-up window
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
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.
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.
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.
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.
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.
VAN components
The following components are mandatory to set up on the sync instruction configuration.
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
Canvass Response
Result Code
Survey Question
Contact List
*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
Syncing P2P and F2F Message custom fields to "Texted" fields in 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.
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:
Review whether the voter(s) exist in either My Voters or My Campaign.
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 [email protected] for more assistance.