Reference

The Virtuous API uses the [REST](http://en.wikipedia.org/wiki/Representational_State_Transfer) architectural style. Our API has predictable, resource-oriented URLs and uses HTTP response codes to indicate API errors. We use built-in HTTP features, like HTTP verbs, which off-the-shelf HTTP clients understand. We do _not_ support [cross-origin resource sharing](http://en.wikipedia.org/wiki/Cross-origin_resource_sharing) on authenticated endpoints to ensure tokens are never shared with the public internet. All API responses, including errors, return JSON. There is no test mode with our API. We strongly encourage you to download [Postman](http://getpostman.com/downloads) and use our collection to get started. You can download the complete API collection to run and mock in Postman. # Authentication All API requests must be made over HTTPS. Calls made over plain HTTP will fail. API requests without authentication will also fail. Passing appropriate headers for the API call is important in order to receive good responses back from the API. There are two authentication methods for the API and both have their benefits. 1. API Keys: recommended for integrations and syncs. Tokens are static and last 15 years. 2. OAuth Tokens: recommended for user-based interactions. Tokens last 15 days and can be refreshed with a refresh token that lasts 365 days. ## How to use API Keys API Keys can be created in the Virtuous UI and do not expire. To create a token, login to Virtuous and then navigate to the API Keys section and click to "Create a Key". Enter a name for the key, choose a permission group, and click save. You will now have the option to view and copy the API Key. You can use this token with the authorization header as shown below. `Authorization: {{vault:bearer-token}}` ## How to use OAuth Tokens To fetch a token, the email address and password need to be URL encoded prior to the string construction to allow any special characters that may be present in your password. `curl -d "grant_type=password&username=YOUR_EMAIL&password=YOUR_PASSWORD" -X POST` [https://api.virtuoussoftware.com/Token](https://api.virtuoussoftware.com/Token) When fetching a token, a refresh token will also be returned. This should be stored and used to fetch new tokens whenever your token expires. To request a new Token use the **refresh_token** from your original Token response as follows: `curl -d "grant_type=refresh_token&refresh_token=REFRESH_TOKEN" -X POST` [https://api.virtuoussoftware.com/Token](https://api.virtuoussoftware.com/TokenOAuth) When fetching a token for a user with Two-Factor Authentication, you will receive a 202 (Accepted) response stating that a verification code is required. The user will then need to enter the verification code that was sent to their phone. You will then request the token again but this time you will pass in an OTP (one-time-password) header with the verification code received If the verification code and user credentials are correct, you will receive a token as seen in the Token authentication above. To request a new Token after the user enters the verification code, add an OTP header: `curl -d "grant_type=password&username=YOUR_EMAIL&password=YOUR_PASSWORD&otp=YOUR_OTP" -X POST` [https://api.virtuoussoftware.com/Token](https://api.virtuoussoftware.com/Token) # Rate Limits Virtuous utilizes throttling to prevent erroneous use of the API. The majority of users won't be affected by this, and if you follow the best practices you shouldn't be either! **Hourly Request Limit:** 1,500 If you're wondering how to **determine the number of requests used**, 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 unix timestamp of when the limit resets. # 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 new or updated gifts. Use webhooks and we'll tell you when something has been created or updated in real-time. [You can learn more about our webhooks here.](https://support.virtuous.org/hc/en-us/articles/360051385392-How-Do-I-Integrate-with-Virtuous-Webhooks-) #### 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 for Gifts and Contacts We highly recommend using the Gift and Contact transaction endpoints instead of creating Gifts and Contacts directly to avoid duplication of Contacts. Learn more about this under Import Tool Endpoints. # Import Tool Endpoints #### How the Import 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. #### Benefits - **Contact Matching:** The transaction endpoints will match contacts based on their addresses, emails, phones, references, and names. 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.](https://app.virtuoussoftware.com/Generosity/Webhook) Webhooks are helpful because they will notify you of _any_ Gifts or Contacts that are created, not just the ones you create. 🙌 # Virtuous Forms Virtuous Forms allow users to set default values, override settings, and expose an onSuccess event. The success event can be used to track the event with Facebook Pixel, Google Analytics or to display a custom message. ``` javascript //load the form embed in the HTML where you would like it displayed //default values and success event can be loaded in the header or footer let VirtuousForms = VirtuousForms || {}; VirtuousForms.settings = { firstName: 'DEFAULT_VALUE', lastName: 'DEFAULT_VALUE', email: 'DEFAULT_VALUE', onSuccess: function(response) { //track event here.... } }; ```