You've decided you want to capitalize on the Virtuous open API - yay for integrated tech! We've put together this article for you to go over some of our integration best practices (and WHY they're our best practices).
Table of Contents
- Why Can't I Import These as Gifts?
- Using Custom Collections to show the Data
- Creating and Integrating
- Updating the Collection
Why Can't I Import These as Gifts?
Virtuous as a Responsive Fundraising platform is built around the idea of building relationships with donors and building a holistic understanding of donors. Tracking and reporting gifts is critical to understand the impact of fundraising efforts. However, products, services and other purchases are not considered donations which means if they were added as gifts, you would have no way of filtering out these transactions for giving totals. This would apply to many places in Virtuous like the giving overview on the contact record or in reporting when you are searching for statistics like “Life to Date Giving.”
Using Custom Collections to show the Data
The best way to track purchases/services is to carry that data into Custom Collections instead of gifts. Having their own designated entity that a user can query, export, and even trigger automations for follow-up communication! Custom Collections are a group of custom fields that can have multiple entries. (Think about it as a spreadsheet- instead of overwriting data, we're just adding a new line.) At a high level, Custom Collections can be created on the Contact or Individual level (when trying to decide where it should live think about the data that you're collecting, is it about one person or any person in that record). You can also have different field types which makes it easier to query on the data later.
Here is what a collection might look like on a contact record:
Creating and Integrating
The first thing you'll need to do is to go into Virtuous (Settings--> Data Customization--> Custom Fields and Collections --> Custom Collections) to create the collection. There is not an API endpoint to create the collection so you will need to do this step first. If you have multiple collections to create at once, you can use the bulk data tools to create custom collections as well (be sure to download the template and guide to make sure you're adding all necessary information).
Once you've created the custom collection, you can start adding values to the collection. Now, to save time and frustration, be sure to use the endpoint to connect this import to the Gift and Contact Import tool. Be sure to send: Contact Information, Reference Source or ID (you can reference this in the future to directly write to the record), and Custom Collection information on the Gift Transaction or Contact transaction end point, the ID of the collection will be returned to you to store for later reference if you plan to update the collection later.
By going through the transaction tool, Virtuous will try to identify if the record exists, if there is any different information, or if the contact is new altogether, giving the user to ensure a proper match and determine any updates before importing into the database which will append the collection data. This helps to ensure data health in Virtuous.
Updating the Entry
Collections allow you to have multiple entries, so if you want to record the history of each collection submission, just post a new collection and it will add to the list. If you need to update an existing collection entry, Each Collection has an ID, and then each separate entry on a Collection, or Collection Instance, has a unique CollectionInstanceId. If you want to update a specific instance, that’s this endpoint.
That endpoint requires the CollectionInstanceId. You will get the ID for an instance returned when creating an instance via the API, or you can get it by looking for a Contact by Reference Source & Reference ID.
Need More?
Check out these articles for more information on Custom Collections.
How Do I Create a Custom Collection?
How Do I Import Custom Collection Data?