Learn everything you need to get started along with common best practices.
If this is your first time, there are just a few quick steps to getting started with the Virtuous API.
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.
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
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.
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
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.
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.
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.
We highly recommend using the Gift and Contact transaction endpoints instead of creating Gifts and Contacts directly. You can read more about them here.
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!
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.
tl;dr: use the transaction endpoints and webhooks.