If you want to build an integration that creates or transfers only the Contact information (no associated transaction data), this article will walk you through some key insights and best practices. If you're looking for a solution for creating Contacts related to a Gift, see Gift Imports. There you can create both the Contact and the Gift together.

Article Table of Contents

API vs Webhooks
How Contact Records are Structured
Creating New Contact Records
Syncing Contact Records to Another System

API vs Webhooks

If you haven’t already, check out our general API Quick Guide to get started then check out the more in-depth API Documentation for an overview of use and features for accessing data when you call on it. There may be cases where based on actions you want the integration to be sent those updates. That’s where Webhooks are great if you want to send contacts for example created in Virtuous, over to another platform. You can also learn more about our webhooks feature in this help article.

You will want to check out the above linked articles to learn general function and best practices. That being said, let’s dive into best practices when building an integration involving contacts in Virtuous.

How Contact Records are Structured

We advise checking out the Virtuous Academy to learn about Contacts more in-depth, but it’s important to know that Virtuous has Contact records that can be Household, Organization, or Foundation Types (or a custom subtype) and that contact can have multiple individuals. Some data like addresses and tags lives on the contact level, where email address and phone number for example live on the individual level.

Creating Contacts in Virtuous

Suggested and Required Fields
Contact Creation Options

Option 1 (Best Practice)
Option 2 (Next Best Step)
Option 3 (NOT Advised...but possible)

Suggested and Required Fields

When creating contacts, Virtuous requires:

• Contact Type (Is it a Household, Organization, Foundation or a custom type)
• Contact Name (Required if Organization or Foundation)
• First Name
• Last Name

Reference Source and ID

Though not technically required, when integrating, you should absolutely add a Reference Source and Reference ID which can be used to identify the records in Virtuous on the front end, and referenced by the integration moving forward for appending or changing data directly.

• Reference Source (they system it came from)
• Reference ID (usually the ID of the record in the original system.)

We also strongly advise these fields where available:

• Email
• Phone
• Address

Among the additional fields, it’s helpful to see the full relationship within Virtuous and would be good to also include:

• Tags (Groups used for targeting and segmenting audiences)
• Email Lists
• Event Attendance
• Volunteer Hours

Lastly, this integration document provides an in-depth guide to creating Contacts.

Contact Creation Options

Option 1 (Best Practice)

Send the data to our transaction tool.

The best practice in Virtuous and the easiest to build out in an integration is to create contacts through our import tool.

Using the transaction/import tool will allow Virtuous to match to existing contact records for you with built in matching logic. If the contact record exists already but there is new information the record will be flagged for review. Making sure that data is clean going in the first time, reducing duplicates and ensuring clean data. This step is critical both for data cleanliness and saving time during the build since you would be using Virtuous’ matching and import logic that comes out of the box. Be sure to include the data mentioned above, especially reference ID so you can reference this ID in the future.

Option 2 (Best Next Step)

Import with option 1 and update subsequent data directly.

Once the data is created with option 1, and you’ve added a reference source and ID. Now that the reference ID is stored, you can directly update other associated data related to the contact without having to go through the import tool by looking up the Virtuous ID through the Reference ID. This should only be data does not need to be verified. If there is a need to validate the data before import revert back to using he import tool. Let’s say I have a flag for receiving our newsletter, I can directly add that tag to the contact record. However, user entered information like First and Last Name I would want to still use the transaction tool since they could have misspelled their name, or provided invalid data. Giving a Virtuous user a chance to verify first.

Option 3 (NOT Advised...but possible)

Search for existing records, match and create contacts.

It may be tempting to have the integration do all the work and have those contacts added to the database without going through our import tool. We don’t advise this approach for a couple reasons.

Building matching logic can be time consuming and complex to build out, it’s also easy to create duplicate records, match to the wrong records, and cause major data cleanup down the road. Basically trying to replicate and build out what already is existing with our import tool. We’ve also found that this approach can often cascade with complexity of scenarios and often times leads to poor results and a lot of time wasted.

Later on if you do have updates you want to make to the contact record remember, if you’ve sent over the Reference Source and ID you now have a way to identify that contact record in the future to make updates through our end point to look up contacts by reference ID.

Syncing Contact Records to Another System

In cases where the data flows into Virtuous to create new contacts and now you want to sync those contacts to another system. You could use export through our API, but we would instead advise using our webhooks instead. You can learn more about our webhooks here. Basically when contact is created, a webhook will fire off that your integration can pick up to gather the info and send it somewhere else.

Check out these other articles to learn more about other best practices surrounding related contact data:

Gift Integration

Campaign Integration

Non-Donation Item Integration

Custom Event Integration