The Virtuous API uses the REST 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 on authenticated endpoints to ensure tokens are never shared with the public internet. All API responses, including errors, return JSON.
\nThere is no test mode with our API.
\nWe strongly encourage you to download Postman and use our collection to get started. You can download the complete API collection to run and mock in Postman.
\nAll API requests must be made over HTTPS. Calls made over plain HTTP will fail. API requests without authentication will also fail.
\nPassing appropriate headers for the API call is important in order to receive good responses back from the API.
\nThere are two authentication methods for the API and both have their benefits.
\nAPI Keys: recommended for integrations and syncs. Tokens are static and last 15 years.
\nOAuth Tokens: recommended for user-based interactions. Tokens last 15 days and can be refreshed with a refresh token that lasts 365 days.
\nAPI 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\".
\n![](\"https://cdn.virtuoussoftware.com/images/postman/api-keys-1.PNG\")
\n\nEnter 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.
\n![](\"https://cdn.virtuoussoftware.com/images/postman/exampletoken.png\")
\n\nYou can use this token with the authorization header as shown below.
\nAuthorization: {{vault:bearer-token}}
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.
\ncurl -d \"grant_type=password&username=YOUR_EMAIL&password=YOUR_PASSWORD\" -X POST 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.
\nTo request a new Token use the refresh_token from your original Token response as follows:
\ncurl -d \"grant_type=refresh_token&refresh_token=REFRESH_TOKEN\" -X POST https://api.virtuoussoftware.com/Token
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.
\nThe 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
\nIf the verification code and user credentials are correct, you will receive a token as seen in the Token authentication above.
\nTo request a new Token after the user enters the verification code, add an OTP header:
\ncurl -d \"grant_type=password&username=YOUR_EMAIL&password=YOUR_PASSWORD&otp=YOUR_OTP\" -X POST https://api.virtuoussoftware.com/Token
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!
\nHourly Request Limit: 1,500
\nIf 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.
\nX-RateLimit-Limit: The total rate limit (1,500/hour).
\nX-RateLimit-Remaining: The total limit remaining.
\nX-RateLimit-Reset: The unix timestamp of when the limit resets.
\nHey, 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.
\nWant 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.
\nEndpoints 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.
\nAnytime 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.
\nIf 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.
\nWe 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.
\nTransactions are posted to the API and are set to a holding state.
\nAt midnight, transactions are bundled into imports based on the source they were posted with.
\nImports are processed.
\nThe organization reviews the imported transactions, and then clicks run.
\nWhen the import is run, we will create the actual Gifts and send webhooks to each webhook subscriber.
\nContact 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.
\nValidation: 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.
\nGift 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.
\nSummary: 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.
\nVirtuous 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.
\n//load the form embed in the HTML where you would like it displayed\n//default values and success event can be loaded in the header or footer\nlet VirtuousForms = VirtuousForms || {};\nVirtuousForms.settings = {\n firstName: 'DEFAULT_VALUE',\n lastName: 'DEFAULT_VALUE',\n email: 'DEFAULT_VALUE',\n onSuccess: function(response) {\n //track event here....\n }\n};\n\nUsername
\n","type":"text"},{"key":"password","value":"SomeFancyGoodPassword","description":"Password
\n","type":"text"},{"key":"otp","value":"012345","description":"Only required when 2FA is enabled for the user
\n","type":"text"}]},"url":"https://api.virtuoussoftware.com/Token","auth":{"type":"bearer","bearer":{"token":"(Required) The contact Id.
\n","type":"text/plain"},"type":"any","value":"(Required) The reference source.
\n","type":"text/plain"},"type":"any","value":"(Required) The reference identifier.
\n","type":"text/plain"},"type":"any","value":"