Many state/regional/national associations find that one of the challenges of managing their membership data is how they go about collecting the data from their affiliated associations. If your association's membership is made of members of affiliated organizations, then the Novi API Feed feature may be just the ticket for streamlining the loading of membership data into your system. 

What is an API?

An API, or Application Programming Interface, is just a fancy technical term that means we also have an interface to allow other computer systems to view an association's membership data just like we have an interface for your members to view their Novi data (the member compass). 

This interface is fully controlled by the source association, and only consumers that they grant access will be able to use the interface. If an association you wish to receive data from is running on Novi, then they can provide your association with a security key we call an "API Key" that will allow you to setup a link between your Novi member database and their Novi member database.

How do I get started?

Before you can get rolling with sharing membership data, the Novi team will need to enable the API features for your site. If these features are not yet enabled for your site, contact our team and we can turn them on for you.

The next step in using a Novi API Feed is to get an API Key from the source association you want to retrieve member data from. This security key will be unique to your relationship with their association, and should be treated just as you would a password because this key is what grants access to the source data.

How do I use an API Key?

Once you have the API Key from the source association, you'll need to setup a new "Novi API Feed" to consume the data. To get started with that, click on "Novi API Feeds" in your association settings menu.

This will bring you to the main "Novi API Feeds" screen. To add your first API feed from here, simply click "Add Novi API Feed" in the upper right hand corner.

You'll now be shown a screen that allows you to enter the following details about the API Feed you'll be consuming - 

  • Name - This will help you identify where membership data is coming from throughout Novi. We usually recommend making this the name of the source association.
  • API Key - The unique security key provided to you by the source association
  • Source URL - The URL of the source association's Novi web-site (this is usually the source association's main homepage)
  • Webhook URL - This field is merely for reference.  This is the URL that the source association should place into their API Key setup so that they can send ongoing customer updates to your organization.

Once you enter the basic information about the API Feed, you'll either see a message that says "Connection to {Association} validated", or you'll receive an error. If you get an error, don't worry - the message should help you or the Novi team determine the problem. If you can't figure it out on your own, feel free to reach out to our team.

Once your connection is validated, you'll first see a list of "System Fields" that are provided to you by the source association. All of these fields will be automatically copied to members in your database when a sync is run. The provided list here is fully controlled by their admins, so you may not receive every single field that you have configured in your Novi setup.

Scrolling down a bit further you'll find two more areas that require information from you -

  • Custom Field Mapping - This section allows you to map any custom fields provided by the source association to custom fields inside your Novi system. Simply look at the source field name & type and determine if there is a match in your system, and select the name of the matching field from the drop down. When a sync runs, data from the source custom field will be copied into the mapped custom field for incoming members. If there are any fields left as "Not Mapped", the data will not be copied into your member database.
  • Member Type Mapping - This section allows you to map Member Types coming from the source association to member types in your system. When new customers coming in via an API feed sync, they will be assigned to the member type you choose. If you choose "Not Mapped" for any member types, then the members will come in as a "Non Dues-Paying Member", and all other field data will continue to be copied.

After you've configured all the mappings to your liking, click "Save & Close" to add the new API feed to your system. You'll now find yourself back at the main Novi API Feed screen, with the new feed listed in front of you.

You'll find several options on this screen for interacting with your newly added Novi API Feed.

  • Active - This column allows you to control whether the specific Novi API Feed is currently turned on. If active is checked - Novi will be actively listening for changes from the source association and will update your member data accordingly (see "How does the data sync work?" below for more details).
  • Edit - This allows you back into the configuration & mapping options you just setup when adding the new Novi API Feed
  • Sync - This will run a full sync of all available data from the source association, updating all matching members in your data. This treats all data from the source association as if it is the newest data available - and any data received from the source will override the data on your local database matching record. NOTE: Full syncs can take a long time (up to a full day) to run depending on how many customers you are receiving from your source.
  • Delete - This will fully delete the specified Novi API Feed from your system and no further updates will be received from the source association. NOTE: We recommend deactivating feeds instead of deleting them - that way you don't lose the historical information about your previous syncs. 
  • Feed Members - This link will take you to a grid that lists the members associated with the feed, as well as any errors that may have occurred during the sync process.

How does the data sync work?

Member Matching
The first thing to understand about the sync is how it matches up members from the source association to your existing membership data. Our matching method is pretty specific, looking for exact matches in all of the following -

  • Name - Exact Match
  • First Name/Last Name/Suffix - Only for "people" records - Exact Match in all 3
  • Zip Code (Billing & Shipping Address)

If Novi finds a match on the above fields, then we'll store a permanent relationship between the matching record in your database and the record from the source association. This means that in the future if the source association updates the name, you'll receive the updates as well! This also allows us to track the changes historically on your member records. For more information on that and how to see your matches, see "How do I tell if one of my members has been updated?" below.

Note: An empty value on the affiliate side will not overwrite a value with information on your website.

Membership Dates
If a local copy of a member at your organization is receiving updates from multiple active sources, the local copy will mirror whichever source last updated that member.  However, this is not the case for membership dates.  When updated member data comes in from a feed, the membership since date of the local copy will be set to the earliest member since date among all sources of that member.  Likewise, the membership expiration date will be set to the latest member expiration date among all sources of that member.  In so doing, the local copy of the member will have member benefits so long as that member has benefits in at least one of the source associations.

Sync Methods
There are two primary methods that Novi API Feeds use to pull data from your source association -

  1. Manual Sync - This is when you run a "sync" from the Novi API Feeds main screen. This will pull all available data from the source association, updating all matching members in your data. We really only recommend using this when you first setup a Novi API Feed as your "initial" sync tool.  Note that you can sync individual members from the "Feed Members" screen, though it's usually only necessary if there were errors in the sync process.
  2. Near Real Time Updates (Webhooks) - Once you have an active API Feed connection, Novi will be actively listening for changes that are made in the source association member data. If a change is detected, we'll automatically go pull the latest information about the changed member and update your member database. This method is the preferred method for ongoing updates - you don't even have to go run a sync to get the latest data!

Information Updates

When you run an initial sync, and a member in your website matches with a member in the source website, the information on the record will come from the Source - even if you already have information on your pre-existing record - so that you have the most up-to-date info to begin with.

However, any syncs after that will only look for changes on a field-by-field basis, meaning that, for example, if you change a record's phone number in your website after the initial sync has occurred, the handshake will not override what you have input into the record.

To see changes that were made to a record by the sync, you can take a look at the record's audit log.

Another example would be: 

  • Initial sync brings in ABC Company from the source (AAGO) with email of "member@myplace.com" and phone of "1-123-456-7890".
  • You change the email to "member@mynewplace.com" on your website, but the source email stays the same
  • Source admin changes phone to "1-987-654-3210"
  • Sync runs for the source and brings over the change, so only the phone number will be updated in your site
  • New customer values are: Your site - "member@mynewplace.com" & "1-987-654-3210" and Source - "member@myplace.com" & "1-987-654-3210"

How do I tell if one of my members has been updated?

On each of your member records, you'll be able to view any Novi API Feed source association matches that are updating your data. To view this data, click on the "Settings" tab on the member detail screen, and scroll down until you see "Novi API Feed Sources".

In this section you'll see any Novi API Feeds that have a match for the member you are currently viewing. You'll also be able to see when we last received an update from the source association.

Another extremely powerful tool here is the "Active" setting on each API Feed Source. If a source on a member is active, then any updates received from the source association will be copied to the member record. If the source is not active (unchecked) your member record will not be updated when an update is received from the source. This can be a really helpful tool if you want to have more control over the data for a specific member but want to still keep your Novi API Feed active for other member updates.

An important note here about members with multiple Novi API Feed sources - If you are receiving data updates from multiple associations, then a member could match to multiple source members. If this happens, the Novi API Feed that is updated most recently will have the "winning" data and will override any data that doesn't match that was received from the other sources. If you don't want this to happen, you can turn off all but one source using the active toggle.

How can I see the list of members that a given feed is providing?

On the Novi API Feeds page, click on "Feed Members" to view the members associated with that feed.  You can click the "Sync" button to sync data for one member at a time.  Statuses will be displayed in real time.

If a record is removed from a source...

If a record is fully removed from a source, i.e. the record is deactivated in the site its coming from, the feed source status will show this record as "Removed from feed."

These removed records do not count in sync status total counts, and are not considered errors, so will not appear when you click "Show Errors Only."

If the record comes from multiple sources, it will no longer receive updates from the source it was removed from, only the remaining.

Merging Duplicates

Because our matching logic is very specific, it is very possible that you'll wind up with duplicate records when you first sync with a new Novi API Feed. Think for example about a company named "Acme Inc." - this would only match if the name was entered exactly the same in your source If instead they have "Acme Incorporated", then no match would be found when the sync runs. 

For added data integrity, after matching names, we also check the records' zip codes. If they do not match, then we will bring in the duplicate record to allow your team to put your eyes on them.

Duplicates brought in from the feed can be quickly identified by the " - {association name}" added to the imported customer names.

If a duplicate happens like this - don't panic! The "Merge Customers" tool in Novi is designed for this very situation. If you are unfamiliar with this functionality, there are other articles to help you through the details. For the purposes of Novi API Feeds however, the important thing to note is that all the Novi API Feed Sources will be copied to the main record during the merge process. This means after you merge the duplicate once - all future updates will automatically flow from the source association to the correct member record.

You will also be able to edit the name to remove the " - {association name}" which was added to the imported customer names.  Just make sure that the name you choose no longer conflicts with the one being sent in from your feed source.

Questions?

The API functionality is one of the more advanced features that Novi provides, but also one of the most powerful for associations that have other affiliated associations or systems to share data with. If you have any questions about what can be done using this functionality, please feel free to contact the Novi team.

Did this answer your question?