Data Model

This page describes the canonical Virtuous CRM+ data model: the core resources, how they relate, and the architectural patterns that shape how partner integrations should read from and write to the platform. Each major resource has its own concept page that goes deeper; this page is the orientation.

​

The core resources

The CRM+ API exposes a relatively small set of first-class resources. Almost every partner integration touches some subset of these:

---

​

How the resources relate

The Contact, Gift, and Project resources form the spine of the model. Most partner integrations operate on this triangle: donors (Contacts), their giving (Gifts), and what those gifts fund (Projects, grouped under Campaigns). A few key relationships to internalize:

• A Contact is not a person. A Contact is the household or organization record. The people inside a Contact are ContactIndividuals. A household Contact named “Wayne Family” might contain two ContactIndividuals (Bruce and Selina); an organization Contact named “Wayne Enterprises” might contain ContactIndividuals for the donor-facing employees. Sending personal name fields (firstName, lastName) to the Contact resource is one of the most common partner-integration mistakes — they belong on ContactIndividual.
• A Gift can fund multiple Projects. A donor giving $500 might split it as$300 to “Clean Water” and $200 to “Education.” Each split is a separate GiftDesignation. A gift always has at least one designation.
• Campaigns are organizing context, not the funding destination. Money flows to Projects (via GiftDesignations), not directly to Campaigns. Campaigns are read-only from the API — they are managed inside the Virtuous UI.
• RecurringGifts and Pledges generate Gifts. A RecurringGift is the schedule; each successful payment on that schedule becomes a Gift. A Pledge is a future commitment; each payment toward the pledge is a Gift.

---

​

The two patterns for writing data into Virtuous

CRM+ exposes two architecturally different ways to create Contacts and Gifts from external systems. The choice of pattern matters more than any individual field decision — it determines whether your integration produces duplicates, whether it benefits from Virtuous’s matching logic, and how soon the records appear in the UI.

​

Pattern 1: Transaction (recommended for partners)

The Transaction endpoints — POST /api/Contact/Transaction for contacts and POST /api/v2/Gift/Transaction for gifts — place incoming records into a holding state. A nightly batch processes them with Virtuous’s matching algorithms: contact deduplication by email, phone, address, and reference IDs; recurring-gift matching; designation resolution; and pledge-payment association. The Transaction pattern is asynchronous — the API accepts your payload and returns success without immediately producing a visible Contact or Gift record. The actual creation happens during the nightly batch run.

​

Pattern 2: Direct create

The direct endpoints — POST /api/Contact and POST /api/Gift — create records synchronously and bypass the matching pipeline. The record appears immediately in the UI with the exact fields you provided. This pattern is appropriate when you have already independently verified that no duplicate exists (for example, you have a verified Virtuous Contact ID for the donor and you are explicitly creating a related record on that Contact). It is not appropriate for general donor data sync from external systems — partners using direct create without their own matching logic routinely produce duplicate Contacts. The Transactions concept page goes into the transaction pattern in detail, including the nightly batch lifecycle, the import-review workflow, and how to detect transactions that failed to match a Contact.

---

​

How to read data out of Virtuous

Reading data uses three patterns, each suited to different scenarios:

• Get by ID — GET /api/Contact/{contactId}, GET /api/Gift/{giftId}, etc. Returns one record by its primary key. Used when you already know the Virtuous ID — typically because you stored it on a previous sync.
• Query with filters — POST /api/Contact/Query, POST /api/Gift/Query, etc. Returns a paginated, filtered list. Used for incremental sync (e.g., “all Contacts modified after timestamp X”) and bulk export. See Pagination and Filtering.
• Look up by external reference — GET /api/Contact/ByReference/{referenceId} and POST /api/Contact/Find. Used to translate an external system’s identifier (a Stripe customer ID, an Eventbrite registration email) into a Virtuous Contact ID. Critical for sync workflows that need to find the Virtuous record corresponding to an external one.

For real-time event-driven workflows, the Webhooks pattern replaces polling — Virtuous pushes record-change events to your endpoint as they happen.

---

​

Resource identifiers

Every resource has a numeric id field as its primary key. IDs are unique within an organization but not unique across organizations — a Contact with id: 4821 in one nonprofit’s Virtuous instance is unrelated to a Contact with id: 4821 in another nonprofit’s instance. Partner integrations that serve multiple nonprofit customers must scope stored Virtuous IDs by customer. Storing just (contactId: 4821) in your database is not enough — you need (customerId: "acme-org", contactId: 4821) to disambiguate. Some resources also carry external reference identifiers — see the Relationships and IDs concept page for how contactReferences and transactionSource/transactionId work as the bridge between Virtuous IDs and your platform’s IDs.

---

​

Where to go next

The remaining Core Concepts pages cover each major area in detail. Read them in order if you are new to Virtuous; jump to the specific page if you are building a focused integration.