Virtuous CRM+ includes an open API that allows your organization to connect CRM+ with external systems and processes. An Application Programming Interface (API) is a set of defined rules that allows different software applications to communicate with each other. The Virtuous CRM+ API is commonly used to build integrations between systems, automate workflows, and enable third-party developers to extend native CRM+ functionality. Using the API can save time, reduce errors, and support innovation.
Table of Contents
Overview
Before working with the Virtuous CRM+ API it's recommended to review the API documentation in detail. This article is a high level summary of the material available in the linked API documentation.
You can access the full API documentation via this link. Here, you can find guidance for use of Webhooks, Bulk Endpoints, common workflows, integration recipes, and more. Use the search bar for key works or ask the AI assistant for help.
Authentication
Every CRM+ API request must include a valid Bearer token in the Authorization header. The API supports two token types: API Keys for server-to-server integrations which do not require refresh tokens, and OAuth refresh tokens for integrations that act on behalf of a specific Virtuous user.
For most integrations, use an API Key. OAuth tokens are appropriate when your integration needs to perform actions as a specific Virtuous user. Click here to learn more about Authentication.
Error Responses
If a call to an endpoint fails for one reason or another, be sure to read the returned message. Our API endpoints use standard error codes with error messages in response payloads to help with troubleshooting. 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. Click here to learn more about how to handle errors.
Rate Limits
We have a rate limit of 5,000 requests per hour to prevent erroneous use of the API. The rate limit is scoped to the your organization, not to individual API Keys or OAuth tokens. Every credential issued from your organization draws from the same 5,000-per-hour bucket. If your have multiple integrations ( a marketing tool, a finance sync, internal scripts) all using the API, all of those callers share a single limit.
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 (5,000/hour).
- X-RateLimit-Remaining: The total limit remaining.
- X-RateLimit-Reset: The timestamp of when the limit resets.
Learn more about the rate limit here.
Core Concepts
Before building with the CRM+ API, it's worth familiarizing yourself with how Virtuous CRM+ structures its data. The Core Concepts section of the API documentation covers the foundational building blocks of CRM+: the data model that connects Contacts, Gifts, and Projects; how money flows from a Gift through Funds, Campaigns, and Designations; how records are identified and related to each other; the lifecycle states that control how records behave; and the Transaction pattern used to import data safely from external systems. Reading through these pages before working with the API helps you avoid common integration mistakes — like creating duplicate Contacts or misrouting gift designations — and gives you a clear mental model of how your data maps to CRM+. Click here to view the Core Concepts.
Bulk and Query Endpoints
When querying for or updating multiple objects, use bulk endpoints rather than making individual requests. For example, use the Gift Query endpoint to retrieve all Gifts in a batch rather than querying each Gift individually, or use the Project bulk update endpoint rather than updating each project one at a time. This keeps your request count well below the rate limit. Click here to learn more ways to stay within the rate limit.
Transaction Endpoints
Virtuous strongly recommends using the Gift and Contact Transaction endpoints instead of creating Gifts and Contacts directly. There are three core benefits:
- Contact matching: The Transaction endpoints match incoming contacts against existing records using email, phone, address, name, and external reference identifiers. Creating contacts directly bypasses this logic and is likely to produce duplicates.
- Validation: Transaction endpoints validate contacts, gifts, premiums, and designations before allowing data to enter the organization's database.
- Gift matching: When a Gift is submitted through the Gift Transaction endpoint, it is processed with intelligent matching to determine whether the gift should be associated with a Recurring Gift or a Pledge Payment, and which Contact it belongs to. If a matching Contact cannot be determined, the gift is placed into a "needs update" queue for a user to resolve.
Virtuous is not responsible for data cleanup resulting from mistakes made when creating Gifts and Contacts directly.
How Transaction Endpoints Work
Instead of directly creating records, Transaction Endpoints use the following logic:
- Transactions are submitted to the API and placed in a holding state.
- At midnight, transactions are bundled into an import (batch) in the Gift and Contact Import Tool based on the source they were submitted with.
- Imports are processed using Virtuous CRM+'s matching algorithm.
- Your organization reviews the imported transactions and selects Run.
- When the import runs, Gifts and Contacts are created and webhooks are sent to all subscribers.
Note: The Transaction endpoints do not create Gifts and Contacts in real time; they process them in a nightly batch. To know when Gifts and Contacts are created, use webhooks. Webhooks notify you of all created records, not just the ones submitted through your integration.
Click here to learn more about Transaction Endpoints.
Workflows and Recipes
Once you're comfortable with the data structure, the Workflows and Recipes sections provide practical guidance for building with the API. Workflows are step-by-step walkthroughs of common tasks like creating a Contact, recording a donation, querying records, or handling duplicates that show exactly which endpoints to call and in what order. Find workflows for each task here.
Recipes take a higher-level view, walking through complete end-to-end integration patterns for specific real-world scenarios like syncing donations from Stripe, building a nightly data sync, or importing historical gift data. If you're starting a new integration, Recipes are a good place to see how the pieces fit together before diving into the individual Workflow pages. Click here to view the recipes.
Webhooks
CRM+ webhooks deliver real-time notifications to a URL you control when records in a nonprofit’s Virtuous organization change. They are the recommended pattern for partner integrations that need to react to events — new Gifts, updated Contacts, deleted Projects — without polling the API on a schedule. Webhooks also do not count against your hourly rate limit. Click here to learn more about webhooks.