All Collections
Help Articles
Integrations
NGPVAN & EveryAction
MobilizeAmerica VAN Integration Overview
MobilizeAmerica VAN Integration Overview

Configuration options for the MobilizeAmerica-to-VAN integration, how to set up the integration, and details about how data is mapped.

Updated over a week ago

Overview

  • MobilizeAmerica allows organizations to configure an integration with NGP VAN / EveryAction 8.

  • The integration syncs events, people, and signups from a single Mobilize Organization to a single VAN Committee.

  • Data is synced in realtime, including whenever an event is created or updated, or whenever a signup is created or updated.

  • Data sync is generally one-way—from Mobilize into VAN—with the exception of signup attendance statuses which can be updated in either VAN or Mobilize.

  • By default Mobilize syncs just the data for the events owned by your organization, but you can also have data synced for events that your organization promotes.

Notes

  • In this documentation and Mobilize, we will refer to the integration as “VAN,” but the integration can be used with any application built on the VAN platform, including EveryAction 8, VoteBuilder, LAN, and NGP 8. This integration will not work with NGP 7 or EveryAction 7.

  • All data is synced to the committee’s MyCampaign mode — data is never synced to or from MyVoters.


How is data synced between Mobilize and NGP VAN or EveryAction?

Events & Event Times

  • All Mobilize events & online actions owned by your dashboard will be synced to VAN as one or more Events in MyCampaign.

  • Mobilize creates a VAN Event for each day of Mobilize event timeslots, so an event with many times over several days in Mobilize may create multiple VAN Events. (This is because in VAN an event must exist on only one day.)

  • If an event has multiple shifts/times on a single day in Mobilize, Mobilize will group those times into a VAN Event with multiple shifts.

  • Petitions, pledges, and interest forms do not create Events and Signups in VAN but can be used to apply Activist Codes to contact records instead

Event Locations

  • Although in VAN events may have multiple locations and roles, Mobilize Events only have one location and role, so all events created in VAN will have just a single location, and all signups will use just one role (as configured in your VAN settings).

  • Mobilize will use VAN’s find-or-create logic for locations, to pick an existing location if one is found. How VAN determines location matches is described in their API documentation.

Tags, Source Codes, & Activist Codes

  • Event tags assigned to the event in Mobilize will be added as tags on the VAN Events

  • Events may have a Source Code applied if the event is a partner event you are promoting (see Promoted Events & Signups below)

  • Petitions, pledges, and interest forms do not create Events and Signups in VAN but can be used to apply Activist Codes to contact records instead

  • Checkbox additional fields can apply Activist Codes on volunteers synced to VAN (learn more)

Making changes to events

All events created in Mobilize must also be edited in Mobilize, and the integration will sync updates to VAN. We do not support editing Mobilize-created events directly in VAN; any edits you make in VAN may be overwritten the next time Mobilize syncs the event.

Supporters & Volunteers

  • Every unique Mobilize supporter (User) will be synced as a unique Person in VAN.

  • A User can be created in Mobilize by signing up for an Event, filling out a Lead Form, or creating an Event within a given organization.

  • Mobilize Users are considered unique by email address, and also usually have a full name, phone number, and zip code.

  • When syncing to VAN, we use VAN’s find-or-create logic to deduplicate records based on all the information we have about a user, which will merge that information into the existing VAN record if one is found. How VAN determines a match is configurable by VAN administrators as documented in their API documentation. 

Signups, aka Participants or Attendees

  • For every User signing up for an Event or Online Action in Mobilize, we will create a VAN Signup record in the VAN Event with the appropriate status as configured in your VAN settings.

  • When a User’s attendance status is updated through Mobilize (e.g., they cancel or confirm before the event, or are marked attended or no-show after the event), we will update the status in VAN.

Signup statuses

  • Although in general, our sync is one-way — we write data into VAN, but do not read data out — the one exception is VAN Signups created by Mobilize.

  • Starting two days before an event, Mobilize will read out the status of upcoming event signups in VAN around midnight every night. If a signup is marked “Cancelled” in VAN, its status will be updated in Mobilize and no reminder emails will be sent. (Read more about our automated notifications.

  • Mobilize will also continue to check for “Completed” and “No-Show” statuses in VAN for three days after the event, and we will update the status in Mobilize if either of those is set.

Setup and Configuration

Get an API key

To set up a new VAN integration, we will need a VAN API key, which can be requested from VAN directly.

Once you have obtained an API key, go to the VAN Settings tab in your dashboard, enter it into the VAN API key field, and click Connect VAN account. Once your VAN API key has been synced, you will need to configure event types, roles, and statuses (below).

Configuring Event Types, Roles, and Statuses

All events created in VAN must have a VAN Event Type, which can only be created in the VAN UI. Learn more about VAN Event Types in the NGP help center (requires ActionID).

⚠️ NOTE: Event Types used by the Mobilize integration cannot require a location, and must be able to support multiple shifts.

Once your event types are set up correctly in VAN, you will configure a mapping from Mobilize Event Types to VAN event types through your VAN settings page:

This will include setting the VAN role to use for attendees (and optionally hosts), as well as the statuses to use for registered, canceled, and confirmed signups.

If any of your VAN Event Types are not showing up, check with VAN support to make sure you’ve configured them to be accessible through the API.

Promoted Events and Signups

You may also choose to sync events you promote and the signups you recruit to those events to your VAN committee. This helps you keep track of the actions your supporters take for partner events that you're promoting to your feed.

Once promoted events have at least one signup via your Mobilize feed, the promoted event is synced to VAN the same way as events you own, except for promoting events across the firewall (see below). This prevents creating a large number of potentially empty events in your VAN committee.

If you wish to sync promoted events and signups, you must configure a separate set of Event Type, Role, and Status mappings for promoted events:

⚠️ Note that if you do not configure a given event type for promoted events, those events and their signups will not be synced to your VAN Committee.

Source Codes for Promoted Events

We will create a unique VAN Code (Source Code) for each organization you promote, and add the Code to that organization’s events when it syncs to your VAN, so you can identify the original event owner.

Activist Codes and Survey Questions

Finally, you may wish to set up an activist code and/or survey response to be applied to contact records in your VAN Committee when they take certain actions on Mobilize. You may set a different activist code for your signups to events and your signups to your generic lead form.

If any of your VAN Activist Codes are not showing up, check with VAN support to make sure you’ve configured them to be accessible through the API. Activist Codes must also be active and set to "be able to be applied or removed".

Learn more about Activist Codes in the NGP help center (requires ActionID)

Data Masking Across the Firewall

Mobilize enforces restrictions on what data can be shared between independent expenditure and coordinated-side entities. It is applied when a you promote an organization across the firewall, and it works in the following way:

  • For signups that you recruit to a promoted event, we will create a “masked” representation of the promoted event in your VAN and sync masked representations of the signups to that event.

  • The event title and details will be marked “[Redacted].” The only details that will appear on the event are the date/time and event type.

  • The Signup model will continue to have the first name, last name, phone number, email, and zip code of the user.

Changelog (April 2020 onwards)

Psst: Head to the What's New page for more Mobilize news and product updates!

June 2021

  • Petitions, pledges, and interest forms will no longer sync Events and Signups to VAN. This is to improve data integrity and prevent long-running "anytime" actions from creating large numbers of events and skewing Event signup and attendance data. Instead, we recommend configuring an Activist Code to be applied for any supporter signing up for one of these actions in the action's Custom VAN Settings.

April 2021

  • 🐛 Bug Fixed (VAN Integration): RecruitedBy and CanvassedBy data entered in VAN for a signup will no longer be modified or removed when a signup is updated in Mobilize. Signup updates are synced to VAN whenever a volunteer checks in for a shift or responds to the post-shift survey, or when an organizer or volunteer host updates the signup in the Mobilize dashboard.

February 2021

  • You can now set a VAN Activist Code for individual events and petitions. Using an Activist Code allows you to more easily build a list of supporters in EveryAction who have taken a specific action on Mobilize, while reducing the number of "events" created in VAN for low-lift actions like petitions. You'll find the new Activist Code sync option under "Customize VAN Settings" when creating a new event, petition, or online action.

April 2020

  1. When a signup is synced from Mobilize to VAN, we will now check whether there is a pre-existing persons record in MyCampaign. If a match is found, Mobilize will not sync the ZIP code for the record, to maintain pre-existing address information in MyCampaign. If a person is not found, we will create a new person in MyCampaign including the ZIP code associated with the signup in Mobilize.

    This change should reduce the chance of Mobilize ZIP data overwriting full addresses in MyCampaign, but will mean that where a contact exists without complete address information, ZIP codes will not be added or updated in the VAN record.

  2. We improved the resilience of the VAN Sync for certain scenarios where moving a timeslot from one day to another would prevent signups associated with that event or timeslot from syncing from Mobilize to VAN.

Did this answer your question?