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.

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.