Virtuous API Guide

Learn everything you need to get started along with common best practices.

Getting Started

If this is your first time, there are just a few quick steps to getting started with the Virtuous API.

1) Best Practices

Be sure to read over our best practices and learn about our rate limits before jumping in.

2) Learn How To Authenticate

Authentication with Virtuous is fairly standard and uses OAuth with refresh tokens. You can learn anything you need to know about authenticating with the Virtuous API here.

3) Start Interacting with the API

Nearly anything you can do within Virtuous can be done through our API. Our API docs are complete with each endpoint and its corresponding request, response and expected method type. You can see our full API documentation here

Best Practices

Hey you're reading the best practices? Good on you! We have just a few tips to follow to ensure a great experience with our 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. You can learn more about our webhooks here

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. You can read more about them here.

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


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

Common Questions

  • 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. 🙌

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.

tl;dr: use the transaction endpoints and webhooks.