Setting Up Integrations

  • Updated

Contents

  1. Overview
  2. Configure Your API Key
    1. How to Obtain Your API Key From VAN
    2. Add your VAN API key to Impactive

  3. About Sync Instructions

  4. Sync a Saved List from NGP VAN

  5. Syncing Contact History

  6. Syncing Activist Codes
  7. Syncing Opt Outs
  8. Syncing Survey Questions
  9. Integrating VAN Nationally or Across Multiple States

  10. Syncing Phone Bank Results

  11. Syncing "Canvassed At" Custom Field
  12. Syncing P2P and F2F Custom Fields
  13. Frequently Asked Questions

Overview

NGP VAN is an important tool for campaigns to manage contact history, canvass results, and much more. We’ve created the following guide to help campaigns set up the necessary configurations in Impactive and NGP VAN so that important data and workflows are synchronized.

Impactive offers an integration with NGP VAN so that campaigns can keep their VAN instance synchronized with Impactive. 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

We trigger syncs instantly. The speed that those syncs realize themselves in VAN, however, largely depends on traffic to both platforms. Usually, contact history, activist codes, and opt outs are quicker, typically take less than an hour. Larger jobs, like list syncs could take a few hours.

This article will review setting up integrations and common use cases.

 

Configure your API Key

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.

How to obtain your API Key from VAN

  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.

A VAN API key is required to give Impactive permission to sync back to your VAN instance. If you’re having trouble configuring your API key, refer back to your NGP VAN administrator for more assistance.

Add your VAN API key to Impactive

  1. Go to the DATA > Integrations tab to get started.
  2. Click the "+ Add API Key" button in the top left corner.
  3. In the “Create Integration” pop-up box, enter the following:
    • Name: enter integration name. We recommend naming this based on your committee/VAN instance, ie: “District 1” if you only have District 1 access)
    • Select an integration type: choose NGP VAN from the drop-down menu.
    • Add your API key.
  • Click “Create” to finish.

If successful, you’ll see an “Active” Status under your API key. If your configuration was unsuccessful, you’ll see an “Error” under Status.

PRO TIP: If you ever need to switch or change VAN committees to pull from, but want to keep your same sync instructions, we suggest updating your current key to the new one (as opposed to creating a new key and new sync instructions from scratch).

About Sync Instructions

Once the VAN API key is configured, you’ll need to create a sync instruction. Sync instructions are basically settings that tell Impactive what data to synchronize over to the VAN database. You can find sync instructions under DATA > Integrations directly below the API key summary table.

We recommend creating sync instructions for every type of integration you’ll want to maintain between us and VAN. These syncs include, but are not limited to:

  • Contact History: text messages, phone calls, and canvass contacts show up as canvass responses in VAN.
  • Activist Codes: tags or custom fields added to contacts in Impactive sync back as activist codes to VAN.
  • Do Not Call: “opt-out” tags in Impactive sync back as “Do not call” result codes in VAN.
  • Survey Questions: multiple choice custom fields like “Support Rating” sync back to VAN as survey questions and responses.
  • Static Lists: instead of importing a list from VAN using a CSV, sync a static list of voters from VAN into an Impactive contact list.

For more information about creating, uploading, and managing contacts, visit our help page How To Create and Manage Contacts.

 

There are numerous components to creating sync instructions and it’s easy to get overwhelmed, but rest assured: the goal is to match an Impactive tool, or “Instruction”, with a VAN endpoint, or “Type”.

van_customlist.png

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

spanish_activist_code__1_.png

Impactive components (mandatory):

  • Instructions for: select the integration type from the drop-down menu, such as “NGP VAN”
  • Instruction Name: name the sync instruction
  • Instructions for: Tag, Custom Field, Contact List, or Sync Hook (Impactive tools)
  • For [Impactive tool name]: Select or enter the name of the tag, custom field, contact list, or sync hook you want to sync

VAN components (mandatory):

  • Sync [Impactive tool name] with integration: select your API key
  • Database Mode: Select the particular VAN database to sync to, either My Voters or My Campaign
  • Type: Select the VAN endpoint, such as Activist Code, Code, Supporter Group, Result Code, or Survey Question

survey_q__1_.png

Variable VAN components

Depending on the VAN endpoint selected under “Type”, additional components will need to be configured:

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

 

Sync a Saved List from NGP VAN

Impactive understands that campaigns, advocacy organizations, and unions often use NGP VAN to create lists by cutting turf and segmenting voters using its many filtering tools. Setting up this sync will allow for data to flow two ways - to and from VAN and Impactive.

Contact list sync turnaround time depends on traffic to both the Impactive platform and VAN, but the list sync should typically complete within 24 hours. Update your NGP VAN list syncs with manual resyncing on contact lists syncs in the Data > Integrations tab. After clicking “re-sync” the contact lists in Impactive will be updated to reflect the state of the static list in NGP VAN.

To set up a Contact List sync:

  1. Go to the DATA > Integrations tab
  2. Click on the “+ Create Sync Instruction” button. Note: You'll need to have an active API key already set up to continue.
  3. In the "Instructions for" drop-down menu, select "NGP VAN".
  4. Name your sync instruction under "Instruction Name". We encourage you to make it something memorable ie: "Precinct #1"
  5. Leave “Target State” as “Any”.
  6. Under "Instructions for" select "Contact List".
  7. Enter a name for the list under "Contact List Name". This is the name that will appear in the CONTACTS > Lists tab.
  8. Select the integration and database under “Sync ContactList with integration
  9. Under “Database Mode” select “My Voters”.
  10. Select “SMS Sync” as the VAN Export Type.
  11. Find the VAN folder with your list under "VAN Folders".
  12. Choose the VAN List to Sync in final field.
  13. Click "Create" to complete.
    1. Note: If nothing happens when you try to create the sync instruction, make sure the list/folder in VAN has access to Impactive or check with your VAN administrator.

van_customlist.png

IMPORTANT NOTE: Contact list syncs are not dynamic. If you need to re-sync changes from a static list in VAN, revisit the DATA > Integrations tab and click on the "..." next to your list sync integration to reveal the "Re-sync List" button. When you click on this button, the list will re-sync within a few hours. You can also re-sync the list in the CONTACTS tab.

 

Syncing Contact History

As the old adage goes: “if it’s not in VAN, it didn’t happen”! Campaigns need Impactive actions to create contact history in NGP VAN so that they can carefully track performance, retarget voters, and create segmented lists. Keep VAN integrated with Impactive by syncing back contact history any time a contact is reached in Impactive.

Here’s an example for Peer to Peer:

  1. Under the DATA > Integrations tab, click on the “+ Create Sync Instruction” button.
  2. Select "NGP VAN" under "Instructions For".
  3. Name your sync instruction in "Instruction Name". We encourage you to call it "P2P Messaged At".
  4. Leave “Target State” as “Any”.
  5. Select "Custom Field" under "Instruction For".
  6. Under "For Custom Field", select "P2P Messaged At".
  7. Leave “Target Value” as “Any”.
  8. Select an API key under “Sync CustomField with integration”.
  9. Under “Database Mode”, select “My Voters”.
  10. Under "Type", select "Canvasser Response".
  11. Under "Object", select the VAN contact type of your choice. We encourage you to use "SMS Text".
  12. Under "Result Code", select the VAN result code of your choice. We encourage you to use "Texted".
  13. Click “Create” to finish.

van_p2p__1_.png

After this instruction is configured, every contact with a valid VAN ID will receive contact history in NGP VAN. A similar sync can be achieved for friend-to-friend, canvassing, and phone banking actions using the “F2F Messaged At”, “Canvassed At” and “Last Called At”/”Call outcome”.

 

Syncing Activist Codes

Leverage activist codes by creating a sync instruction that applies an activist code to contacts any time a tag is submitted on them in Impactive.

  1. Navigate to the DATA > Integrations tab to start. ****
  2. Click on the “+ Create Sync Instruction” button.
  3. Select "NGP VAN" under "Instructions For".
  4. Name your sync instruction in "Instruction Name". We encourage you to use something similar to the tag you want to sync, like "Spanish".
  5. Leave “Target State” as “Any”.
  6. Select "Tag" under "Instruction For"
  7. Under "For Tag", select the corresponding tag you want to sync.
  8. Select an API key under “Sync Tag with integration”.
  9. Under “Database Mode”, select “My Campaign”.
  10. Under "Type", select "Activist Code".
  11. Under "Object", select the name of the activist code in your VAN instance.
  12. Click “Create” to finish.

spanish_activist_code__1_.png

After this instruction is configured, every time you submit the tag on a contact with a valid VAN ID, the corresponding activist code will be created in NGP VAN.

 

Syncing Opt-Outs

Need to track if voters or contacts have unsubscribed? Impactive automatically tags voters who have unsubscribed from Peer to Peer (P2) 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. Pass the “Opt-Tut” tag to NGP VAN result codes to track contacts who have unsubscribed from P2P campaigns.

https://support.impactive.io/hc/article_attachments/5018162694679/opt_out__1_.png

  1. In the DATA > Integrations tab, click on “+ Create Sync Instruction”.
  2. Select "NGP VAN" under "Instructions For".
  3. Name your sync instruction in "Instruction Name". We encourage you to call it "Opt Out".
  4. Leave “Target State” as “Any”.
  5. Select "Tag" under "Instruction For".
  6. Select the corresponding tag under “For Tag”. In this case it would be “Opt Out”.
  7. Select an API key under “Sync Tag with integration”.
  8. Under “Database Mode”, select “My Voters”.
  9. Under "Type", select "Result Code".
  10. Under "Object", select "Do Not Text".
  11. Click “Create” to finish.

After this instruction is configured, every time a voter unsubscribes using “Stop”, “Cancel”, or “Unsubscribe” keywords, or if a volunteer manually opts-out the contact, NGP VAN will automatically create a “Do Not Text” result code in the contact’s history.

 

Syncing 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. Capture responses to survey questions in VAN by creating sync instructions on multiple choice custom fields.

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.

Sync the custom field “Support Rating” with the "Survey Question” type, while toggling the “Do Not Text” object.

https://support.impactive.io/hc/article_attachments/5018286724887/survey_q__1_.png

  1. Go to the DATA > Integrations tab and click on the “+ Create Sync Instruction” button.
  2. Select "NGP VAN" under "Instructions For".
  3. Name your sync instruction in "Instruction Name". We encourage you to call it "Support Rating".
  4. Leave “Target State” as “Any”.
  5. Select "Custom Field" under "Instruction For".
  6. Under “For Custom Field” select “Support Rating”.
  7. Leave “Target Value” as “Any”.
  8. Select an API key under “Sync CustomField with integration”.
  9. Under “Database Mode”, select “My Voters”.
  10. Under "Type", select "Survey Question”.
  11. Under "Object", select the name of the survey question in VAN. Note: only survey questions where Impactive has API access will be visible here.
  12. Map each survey response to the respective custom field multiple choice answer.
  13. Click “Create” to finish.

After this is configured, every time a volunteer submits a multiple choice custom field response on “Support Rating”, NGP VAN will apply the appropriate survey question response on the contact.

 

Integrating VAN Nationally or Across Multiple States

You can integrate Impactive with VAN nationally or across multiple states using the "Target State" field. This enables campaigns to sync VAN using the same API key in an Impactive campaign by overcoming the limitation where VAN_ID's are not unique state-by-state. You will need an API key that has access to your national or multi-state instance in VAN.

1. Ensure all contacts are uploaded with the state abbreviation field.

Upload a contact list as you usually would using the instructions here: How to Create and Manage Contacts; however, use the 'state_abbrev' column as well as the ‘van_id’. Include state abbreviation as a value: ie, "VA" for Virginia. Here's an example:

https://support.impactive.io/hc/article_attachments/4409647677463/state_abbrev.png

2. Create a sync instruction using the "Target State" field.

Create a sync instruction as you normally would by following the instructions here; however, include the "Target State" field in the sync instruction. This ensures that VAN syncs to IDs in a particular state (ex: Virginia).

Simply select the state abbreviation you will integrate under "Target State". For example, below, we want to make sure that the field is syncing to IDs in the state of Virginia. We'll select "Target Value": "VA".

Go ahead and create your sync instruction. Once the two steps above are completed, Impactive will sync to the correct contact in your national or multi-state VAN instance.

 

Syncing Phone Bank Results

Sync dialer activities to NGP VAN by setting up sync instructions for dialer-specific custom fields. There are two dialer-specific custom fields that Impactive configures by default to allow campaigns to sync back phone bank activities to NGP VAN.

The custom fields are the following:

  • Last Called At
  • Call Outcome

Last Called At

The “Last Called At” custom field is appended to a contact on Impactive anytime the predictive dialer attempts to call a contact in a phone bank. This means that regardless of whether the contact was reached or the call went to voicemail, the custom field is recorded. This custom field gets recorded as a  “Last Called At’ custom field in our system with a timestamp as a value. Use the “Last Called At” custom field in your Impactive sync instructions to ensure that your contact history in NGP VAN is up-to-date.

  1. Select "NGP VAN" under "Instructions For".
  2. Name your sync instruction in "Instruction Name". We encourage you to call it "Last Called At".
  3. Select "Custom Field" under "Instruction For"
  4. Under "For Custom Field", select "Last Called At".
  5. Under "Type", select "Canvasser Response".
  6. Under "Object", select the VAN contact type of your choice. We encourage you to use "Phone Call".
  7. Last, under "Result Code", select the VAN result code of your choice.

Once the sync instruction is correctly configured in Impactive, the platform will pass contact history to the voter’s profile in NGP VAN with the timestamp, contact method, and result code.

Call Outcome

The “Call Outcome” custom field is a multiple-choice custom field that is surfaced to the volunteer when they are recording the outcome of a connected call on an Impactive phone bank. When the call outcome prompt is surfaced, the volunteer should pick the appropriate outcome of the call:

  • Completed
  • Answering machine
  • No answer
  • Busy
  • Not home
  • Wrong number
  • Moved
  • Deceased
  • Refused
  • No language in common

The selected result will be recorded as the value of the “Call Outcome” custom field for the contact. The field is also auto-populated automatically by the dialer when answering machine detection is enabled for a particular phone bank action. It will map its auto-detected outcomes to the call outcomes listed above.

Use the “Call Outcome” custom field in your Impactive sync instructions to ensure that your contact history in NGP VAN is up-to-date.

  1. Select "NGP VAN" under "Instructions For".
  2. Name your sync instruction in "Instruction Name". We encourage you to call it “Call Outcome”.
  3. Select "Custom Field" under "Instruction For"
  4. Under "For Custom Field", select “Call Outcome”.
  5. Under "Type", select "Canvasser Response".
  6. Under "Object", select the VAN contact type of your choice. We encourage you to use “Phone Call”.
  7. Last, under "Result Code", select the VAN result code of your choice.

Note: A sync instruction will need to be created for each call outcome.

 

For more information, visit our Syncing Phone Bank Results article here.

 

Syncing “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 “WalkObject and the “CanvassedResult Code. This will ensure all canvassed contacts in Impactive are show up as canvassed in NGP VAN.

 

Syncing P2P and F2F Custom Fields

This section will help you set up a sync instruction to keep your text message custom fields in sync with NGP VAN's "Canvass Response" endpoint. Impactive enables two custom fields by default: P2P Messaged At and F2F Messaged At. The F2F Messaged At custom field is appended to a contact when you text them in a friend-to-friend text messaging action. The P2P Messaged At custom field is appended to contact when you text them in a peer-to-peer text messaging action. You can create an instruction to sync these fields with NGP VAN's "Canvass Response" endpoint.

P2P Messaged At

To sync the "P2P Messaged At" custom field with "Canvass Response"

  1. Go to the DATA > Integrations tab and select “+ Create Sync Instruction”. You'll need to have an active API key to do this.
  2. Select "NGP VAN" under "Instructions For".
  3. Name your sync instruction in "Instruction Name". We encourage you to call it "P2P Messaged At".
  4. Select "Custom field" under "Instruction For"
  5. Under "For custom field", select "P2P Messaged At".
  6. Under "Type", select "Canvasser Response".
  7. Under "Object", select the VAN contact type of your choice. We encourage you to use "SMS Text".
  8. Last, under "Result code", select the VAN result code of your choice. We encourage you to use "Texted".
  9. Click "Create" to finish the configuration.

van_p2p.png

If implemented correctly, any time a contact receives a peer-to-peer text in Impactive, they will receive a canvass result in NGP VAN under the  "SMS Texted" contact type and "Texted" under the result code.

 

F2F Messaged At

To sync the "F2F Messaged At" custom field with "Canvass Response":

  1. Go to the DATA > Integrations tab and click on “+ Create Sync Instruction.” You'll need to have an active API key to do this.
  2. Select "NGP VAN" under "Instructions For".
  3. Name your sync instruction in "Instruction Name". We encourage you to call it "F2F Messaged At".
  4. Select "Custom field" under "Instruction For"
  5. Under "For custom field", select "F2F Messaged At".
  6. Under "Type", select "Canvasser Response".
  7. Under "Object", select the VAN contact type of your choice. We encourage you to use "Personal Phone".
  8. Last, under "Result code", select the VAN result code of your choice. We encourage you to use "Texted".
  9. Click "Create" to finish the configuration.

van_f2f.png

If implemented correctly, friends or family receiving a friend-to-friend text in Impactive will receive a canvass result in NGP VAN under the "Personal Phone" contact type and "Texted" under the result code.

 

Have more questions?

Visit our Integrations FAQ page!

Was this article helpful?

/