Donors - Virtuous API Docs

The Donor is Raise’s primary donor-side record. Every Gift, RecurringGift, and donor-related activity attaches to a Donor. The resource has a richer surface than most others in the API — over 30 dedicated endpoints span basic CRUD, sub-resources for addresses and contact methods, lifecycle operations (archive, merge), and specialized operations (transfer a Gift between Donors). This page covers the resource shape, the sub-resource pattern Raise uses for addresses and contact methods, and the operations that don’t map to plain CRUD.

The Donor record

The core fields on a Donor record:

Identity

Field	Type	Description
`id`	integer	The Raise primary key. Assigned at creation, immutable after.
`name`	string	Display name. For households, typically `"FirstName LastName"`; for organizations, the organization name.
`title`	string	Optional title — Dr., Rev., etc.
`firstName`	string	Given name.
`middleName`	string	Middle name.
`lastName`	string	Family name.
`suffix`	string	Suffix — Jr., III, etc.
`isOrganization`	boolean	`true` for organizational donors, `false` for individuals.
`organizationName`	string	The organization name when `isOrganization` is `true`.

Top-level contact

Field	Type	Description
`email`	string	The donor’s primary email — convenience field that mirrors the primary entry in `donorEmailAddresses[]`.
`phone`	string	The donor’s primary phone — convenience field that mirrors the primary entry in `donorPhoneNumbers[]`.

The top-level email and phone are convenience accessors. The authoritative storage for contact methods is in the sub-resource collections below — those collections support multiple entries per donor and explicit primary-marking.

Sub-resource collections

Collection	Description
`donorAddresses[]`	All addresses on the donor. One is typically marked primary.
`primaryAddress`	Convenience accessor pointing to the address with `isPrimary: true`.
`donorEmailAddresses[]`	All email addresses on the donor. One is typically marked primary.
`donorPhoneNumbers[]`	All phone numbers on the donor. One is typically marked primary.

Each entry in these collections is itself a typed sub-resource with its own ID and its own dedicated endpoints — see Sub-resource endpoints below.

Lifecycle and audit

Field	Type	Description
`createdDate`	string	When the donor record was created.
`modifiedDate`	string	When any field on the record was last changed. Read-only.
`isArchived`	boolean	`true` if the donor has been archived. Archived donors are hidden from normal views but the record still exists.
`isGDPRDeleted`	boolean	`true` if the donor has been deleted under a GDPR right-to-erasure request. The record is retained as a tombstone but personal data is removed.
`isTestMode`	boolean	`true` if the donor was created in test mode.
`notes`	string	Free-text notes — see Updating notes for the dedicated update endpoint.

External system linkage

Field	Type	Description
`crmKey`	string	The donor’s primary key in an external CRM — typically CRM+.
`crmSecondKey`	string	A secondary CRM identifier.
`crmKeyUrls`	object	A map of integration types to URL info, letting the customer’s UI link directly to the donor in each external system.

The crmKey fields are the linkage Raise uses to keep records aligned with CRM+ when a customer runs both products. Partner integrations don’t typically write these directly — they’re populated by the platform-level sync. See How Raise Data Flows to CRM+.

Reading Donors

Raise exposes three patterns for reading Donor records, each suited to a different use:

Pattern	Endpoint	Use
List all	`GET /api/Donor/list`	Paginated list of all donors. Supports `Filter`, `Skip`, `Take`, `SortBy`, `Descending`, `IncludeDetails`.
Query by structured filter	`POST /api/Donor/query`	Advanced filtering with `groups[]` of `conditions[]` — see Pagination and Filtering.
Search by free text	`GET /api/Donor/search`	Free-text search. Matches on donor ID, name, email, and phone.
Get by ID	`GET /api/Donor/{donorId}`	A single donor with all sub-resources included.

For list-and-export workflows, Donor/list with IncludeDetails=false is the cheapest. For complex segmentation, Donor/query with structured filters. For interactive type-ahead in a UI, Donor/search. Several donor sub-resources have dedicated paginated endpoints:

Endpoint	Returns
`GET /api/Donor/{donorId}/gifts`	All Gifts by this donor
`GET /api/Donor/{donorId}/recurringgifts`	All RecurringGifts by this donor
`GET /api/Donor/{donorId}/projects`	Projects this donor has supported
`GET /api/Donor/{donorId}/donor-fields`	Custom field values on the donor
`GET /api/Donor/{donorId}/responses`	Donor responses (associated with custom fields)
`GET /api/Donor/{donorId}/campaign-statistics`	Per-campaign giving summary
`GET /api/Donor/{donorId}/segment-statistics`	Per-segment giving summary
`GET /api/Donor/{donorId}/motivation-statistics`	Per-motivation-code giving summary

The statistics endpoints aggregate the donor’s giving over time — useful for donor analytics workflows without needing to query the full Gift history.

Creating and updating Donors

Donor records can be created directly via the API. Most partner integrations don’t create Donors directly — they let the POST /api/Raise/give donation submission path create donors as part of the donation flow. But for integrations syncing donors from another system without a corresponding gift, the direct create endpoint is available.

The Raise spec does not show a dedicated top-level POST /api/Donor endpoint. Donor creation in practice happens either through the donation submission path (POST /api/Raise/give) or through dedicated bulk-import tools in the admin UI. For partner integrations that need to create donors independently of a gift, confirm the current approach with the platform team — the spec’s donor-creation surface may evolve as part of the v2 overhaul.

Updating a Donor

PUT /api/Donor/{id} and PATCH /api/Donor/{id} update a donor:

Method	Behavior
`PUT /api/Donor/{id}`	Documented in the spec summary as “Update an existing donor (full update).” Send the complete donor record.
`PATCH /api/Donor/{id}`	Same endpoint, PATCH semantics. Send only the fields to change.

The dual PUT/PATCH support on the same endpoint is unusual — most Raise endpoints expose just one. For partner integrations, prefer PATCH for partial updates to minimize the risk of inadvertently clearing fields with a full-replace PUT.

cURL

# Update just the donor's email via PATCH
curl -X PATCH https://prod-api.raisedonors.com/api/Donor/12345 \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "bruce.wayne@updated.example"
  }'

Updating notes

Donor notes have a dedicated update endpoint separate from the main donor PUT:

cURL

curl -X PUT https://prod-api.raisedonors.com/api/Donor/12345/notes \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "notes": "Donor prefers email contact; no phone calls" }'

Using the dedicated endpoint is preferred over including notes in a general PUT — it scopes the change cleanly to the notes field and produces a clearer audit trail.

Sub-resource endpoints

Raise treats addresses and contact methods as first-class sub-resources of a donor. Each has its own ID, its own dedicated endpoints, and operates independently of the parent donor PUT.

Addresses

Endpoint	Method	Use
`POST /api/Donor/{id}/address`	POST	Create a new address on a donor
`GET /api/Donor/{id}/address/list`	GET	List all addresses on a donor
`GET /api/Donor/{id}/address/{addressId}`	GET	Get a specific address
`PATCH /api/Donor/{id}/address/{addressId}`	PATCH	Partial update of an address
`PUT /api/Donor/{id}/address/{addressId}/update`	PUT	Full update of an address
`DELETE /api/Donor/{id}/address/{addressId}/delete`	DELETE	Remove an address from a donor
`PUT /api/Donor/{id}/address/{addressId}/set-primary`	PUT	Mark this address as the donor’s primary

Setting an address as primary automatically unmarks any previously-primary address — exactly one address can be primary at a time.

Contact methods

Contact methods cover both emails and phone numbers under a unified resource. Each method has a type indicating which:

Endpoint	Method	Use
`POST /api/Donor/{id}/contact-method`	POST	Create a new email or phone contact method
`GET /api/Donor/{id}/contact-method/list`	GET	List all contact methods
`GET /api/Donor/{id}/contact-method/email-addresses`	GET	List only email-type contact methods
`GET /api/Donor/{id}/contact-method/phone-numbers`	GET	List only phone-type contact methods
`GET /api/Donor/{id}/contact-method/{contactMethodId}`	GET	Get a specific contact method
`PUT` or `PATCH/api/Donor/{id}/contact-method/{contactMethodId}`	PUT/PATCH	Update a contact method
`DELETE /api/Donor/{id}/contact-method/{contactMethodId}`	DELETE	Remove a contact method
`PUT /api/Donor/{id}/contact-method/{contactMethodId}/set-primary`	PUT	Mark as primary

There are also typed convenience endpoints (POST /api/Donor/{id}/email, POST /api/Donor/{id}/phone, etc.) that operate on the same underlying contact-method records but with explicit email-only or phone-only paths. Use whichever pattern is more natural for your integration.

Special operations

A few Donor operations don’t map to plain CRUD and have dedicated endpoints.

Merge

cURL

curl -X PUT https://prod-api.raisedonors.com/api/Donor/merge \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "sourceDonorId": 12345,
    "targetDonorId": 67890
  }'

Merging two donor records combines them — typically the source record’s data is folded into the target and the source is marked archived (or otherwise made inactive). The Raise API exposes this directly, which is different from CRM+‘s model where merges happen in the UI.

Confirm the exact request body shape for PUT /api/Donor/merge against the live API before relying on it in production. The endpoint description says “Merge two donors” but the OpenAPI spec doesn’t detail the merge behavior — particularly around what happens to the source donor’s Gifts, RecurringGifts, and sub-resources after merge.

Transfer a gift to another donor

If a Gift was attributed to the wrong donor, transfer it without deleting and recreating:

cURL

curl -X PUT https://prod-api.raisedonors.com/api/Donor/transfer-gift \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "giftId": 9876,
    "newDonorId": 67890
  }'

The Gift’s donorId is updated to the new donor and the Gift remains otherwise intact — same amount, date, designations, payment record. PUT /api/Donor/transfer-recurring-gift performs the equivalent operation for a RecurringGift schedule.

Activities

Donor activities are log entries — interaction notes, status updates, follow-up records:

Endpoint	Method	Use
`POST /api/Donor/{id}/activity`	POST	Create a new activity entry
`POST /api/Donor/{id}/activities`	POST	Get a paginated list of activities (uses POST despite being a read because of the query body)

Use activities to track integration-managed interactions — when your integration sent the donor a thank-you email, when an automated follow-up sequence was triggered, etc. These show up in the donor’s history alongside manual entries from the customer’s staff.

Generate a personalized donation page

cURL

curl -X POST https://prod-api.raisedonors.com/api/Donor/12345/generate-page \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "campaignId": 5678
  }'

Generates a hosted donation page personalized to the donor — typically a URL that can be sent in an email or text message, pre-filling the donor’s identity so they need only enter the donation amount and payment method. Useful for renewal campaigns and major-donor cultivation.

Donor data privacy

Two donor-data privacy concerns are worth flagging: The isGDPRDeleted flag on a Donor record indicates the donor has been deleted under a GDPR right-to-erasure request. The record is retained as a tombstone (the id continues to exist so historical Gift references don’t break) but personal data is removed. Partner integrations that store Donor data locally should respect this flag — when a donor sync detects isGDPRDeleted: true, the local record should be reduced to the tombstone state, with personal data deleted on the partner side.

Test mode separation

Donors created with isTestMode: true are flagged as test data. Production reports should filter to isTestMode: false. See Base URLs and Environments — Working against production with care.

Where to go next

Gifts

The Gift resource and the donation submission path that creates Donors as a side effect.

Create or Find a Donor

The workflow for ensuring a donor exists before submitting a donation.

Query Donors by Filters

Use the structured query pattern to find specific donor segments.

How Raise Data Flows to CRM+

The platform-level sync that keeps Raise Donors aligned with CRM+ Contacts.

​The Donor record

​Identity

​Top-level contact

​Sub-resource collections

​Lifecycle and audit

​External system linkage

​Reading Donors

​Reading related records for a donor

​Creating and updating Donors

​Updating a Donor

​Updating notes

​Sub-resource endpoints

​Addresses

​Contact methods

​Special operations

​Archive

​Merge

​Transfer a gift to another donor

​Activities

​Generate a personalized donation page

​Donor data privacy

​GDPR right-to-erasure

​Test mode separation

​Where to go next

Gifts

Create or Find a Donor

Query Donors by Filters

How Raise Data Flows to CRM+

The Donor record

Identity

Top-level contact

Sub-resource collections

Lifecycle and audit

External system linkage

Reading Donors

Reading related records for a donor

Creating and updating Donors

Updating a Donor

Updating notes

Sub-resource endpoints

Addresses

Contact methods

Special operations

Archive

Merge

Transfer a gift to another donor

Activities

Generate a personalized donation page

Donor data privacy

GDPR right-to-erasure

Test mode separation

Where to go next