Virtuous API Guide

Virtuous CRM has an open API available for your organization to work with. An Application Programming Interface (API) is a set of defined rules that allows different software applications to communicate with each other. The Virtuous API acts as an intermediary, allowing your organization to access specific functionalities or data from VCRM to interface with external systems and processes. The VCRM API is commonly used when building integrations between systems, automating workflows, or enabling third-party developers to extend the native functionality of the VCRM application. By providing streamlined and standardized access to complex systems, using the Virtuous CRM API can save time, reduce errors, and foster innovation.

Table of Contents 

1. Getting Started 
2. Best Practices 
3. Rate Limits
4. Transaction Endpoints 

Getting Started

Before working with the Virtuous API it's recommended to review the API documentation in detail. This article is a high level summary of the material available in the linked API documentation. 

You can access the full API documentation via this link. Here, you can find guidance for use of Webhooks, Obsolete Endpoints, Bulk Endpoints, and more. 

Learn How To Authenticate

Authentication with Virtuous is fairly standard and uses OAuth with refresh tokens. 

Start Interacting with the API

Much of what you can do within Virtuous CRM can be done through the Virtuous CRM API. The API docs are complete with each endpoint and its corresponding request, response and expected method type. 

Best Practices

There are just a few tips to follow to ensure a great experience when working with the Virtuous CRM API.

1) Webhooks

Want to know when an object like a Contact, Gift or Project is updated? Use our webhooks! Don't query for updated gifts, or recent gifts when we will tell you when something has been updated or created in real time. 

2) Obsolete Endpoints

Endpoints that have been obsoleted will be marked with "(obsolete)" and shouldn't be used (I know I know, might seem obvious right?). They will be removed in future releases.

3) Bulk Endpoints

Anytime you're querying for objects, or updating a group of objects, use our bulk endpoints. For example, if you want to query for all gifts in a batch, use the gift query endpoint and search by the batch rather than querying for each gift in a batch. Another example would be when updating a list of projects, use our project bulk update endpoint rather than updating each project individually.

4) Read the Response

If a call to an endpoint fails for one reason or another, be sure to read the returned message. Almost anytime you receive a status code other than 200 (success) you should receive a message explaining why that code was received. Please check these and make the corrections prior to reaching out to support.

5) Use the Transaction Endpoints

We highly recommend using the Gift and Contact transaction endpoints instead of creating Gifts and Contacts directly. 

Rate Limits

Beginning in March 2019, we're introducing rate limiting to prevent erroneous use of the API. The majority of users won't be affected by this change, and if you follow the best practices you shouldn't be either!

Request Rate Limits

• Per Hour: 1,500

If you're wondering how to determine how many requests you've used in a given period, we've got you covered. The following headers will be returned with each request.

• X-RateLimit-Limit: The total rate limit (1,500/hour).
• X-RateLimit-Remaining: The total limit remaining.
• X-RateLimit-Reset: The timestamp of when the limit resets.

Transaction Endpoints

Benefits of Transaction Endpoints 

• Contact Matching: The transaction endpoints will match contacts based on their addresses, emails, phones, references, and name. If you choose to create a contact directly, you are likely to create duplicates.
• Validation: the transaction endpoints will provide validation for the contacts, gifts, premiums, designations, etc. and will not allow duplicate or bad data to enter the organization's database.
• Gift Matching: when a Gift goes through the Gift Transaction tool, it will be processed will intelligent matching to determine if the gift should be associated with a Recurring Gift Payment, or a Pledge Payment. It will also identify which Contact the Gift belongs to. If it cannot determine a matching Contact, it will be placed into the _needs update_ bucket for a user to determine where it goes.
• Summary: There are many benefits including intelligent matching in the transactions endpoints and it's nearly impossible to provide the same level of data integrity when you create Gifts and Contacts directly. We are not responsible for data cleanup if a mistake is made when creating Gifts and Contacts directly.

Troubleshooting 

Why don't I get a response when sending Gifts or Contacts to the transaction endpoints? The transaction endpoints do not create Gifts and Contacts in real time, but rather they process them after the fact. If you need to know when Gifts and Contacts are created, use webhooks. Webhooks are helpful because they will notify you of any Gifts or Contacts that are created, not just the ones you create. 

For more guidance on working with Webhooks, check out this Support Article. 

How the Transaction Endpoints Work

1. Transactions are posted to the API and are set to a holding state.
2. At midnight, transactions are bundled into imports based on the source they were posted with.
3. Imports are processed.
4. The organization reviews the imported transactions, and then clicks run.
5. When the import is run, we will create the actual Gifts and send webhooks to each webhook subscriber.