Summary

MobilizeAmerica allows organizations to configure an integration with NGP VAN / EveryAction 8. Our integration syncs events, people, and signups from a single Mobilize Organization to a single VAN committee. Data is synced in realtime, triggered on creation or update of any event, user, or signup in Mobilize. By default we sync just the data for your owned events, but can also configure the ability to sync data for promoted events. All data is synced to the committee’s MyCampaign mode — data is never synced to or from MyVoters.

Note: We will refer in this documentation to the integration as “VAN,” and we have primarily tested the integration with VoteBuilder, but have been told by NGP VAN that the integration is the same and functions correctly and identically with EveryAction 8, VoteBuilder, and NGP 8. This integration will not work with NGP 7 or EveryAction 7.


***

NEW: VAN integration change log

Check out the VAN integration changelog to stay up to date on all major changes to the Mobilize/VAN integration (from April 2020 onwards).


***

Data Sync

Below are the data models we sync to VAN, and their corresponding concepts in Mobilize.

Syncing Events, Times, and Locations

  • All owned Mobilize events will be synced to VAN
  • In Mobilize an Event may have one or many Times across multiple days. In VAN an event must exist on only one day, so a Mobilize Event with many Times will create multiple VAN events. If the Mobilize Event Times are on the same day, they will be grouped into a single VAN event with multiple shifts.
  • 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.
  • Note that all events created by Mobilize must be edited in Mobilize, which will sync updates to VAN. We do not support editing Mobilize-created events directly in VAN; the edits will be overwritten the next time we sync the event.

Syncing Users

  • Every unique Mobilize User will be synced as a unique Person in VAN.
  • A User can be created in Mobilize from 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 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. 

Syncing Signups

  • For every User signed up to your Event in Mobilize, we will write a VAN Signup record 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.

Reading VAN Signup statuses into Mobilize

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

Promoted Events and Signups

You may also chose to sync the Events and Signups you are promoting through Mobilize to your VAN committee. Doing so works the same as syncing your owned Events and Signups, with the exception that Promoted Events won’t sync until they have at least one Promoted Signup from your Organization. This prevents creating a large number of potentially empty events in your VAN committee that you don’t control. 

With the exception of promoting events across the firewall (see below), events and signups you promote appear in VAN the same way as events and signups you own.

VAN Codes for Promoted Events

We will create a unique VAN 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.

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.

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, your Mobilize support contact will ask you to send it to us via OneTimeSecret and we will set it up for your Organization.

Configuring Event Types, Roles, and Statuses

All events in VAN must have a VAN event type, which can only be configured in the VAN UI. Once these event types are set up, 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, cancelled, and confirmed signups.

If you also wish to sync promoted signups, you must configure a separate set of mappings for promoted events:

Note that if you don’t configure a given event type for promoted events, signups to those events will not sync.

Finally, you may with to set up an activist code and/or survey response for the users that you sync from 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 event types or activist codes are not showing up, check with VAN support to make sure you’ve configured them to be accessible through the API.

Did this answer your question?