> ## Documentation Index
> Fetch the complete documentation index at: https://docs.virtuous.org/llms.txt
> Use this file to discover all available pages before exploring further.

# The Raise Data Model

> The resources Raise exposes, how they relate to each other, and how data flows from a donation event through the API to downstream products.

This page is the reference for how data is organized in Raise. The resources, their relationships, and the flow of a donation from form submission through Gift record creation are covered here. Later concept pages drill into specific resources; this page is the map.

## The resources

Raise exposes 15 resource families through the API. The ones partners interact with most often are organized into three layers — donor-side records, gift-side records, and the configuration that ties them to fundraising campaigns.

### Donor-side records

| Resource               | What it represents                                                                                                                     |
| ---------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
| **Donor**              | A person or organization that has given (or is being prepared to give). Carries identity, contact methods, addresses, and CRM linkage. |
| **DonorAddress**       | A physical address on a donor. Donors can have multiple addresses with one marked primary.                                             |
| **DonorContactMethod** | An email address or phone number on a donor. Donors can have multiple of each with one marked primary per type.                        |
| **DonorActivity**      | A log entry recording an interaction with a donor — note, status change, follow-up.                                                    |

### Gift-side records

| Resource                  | What it represents                                                                                               |
| ------------------------- | ---------------------------------------------------------------------------------------------------------------- |
| **Gift**                  | A single completed donation. Carries the amount, payment details, status, designations, premium, and tribute.    |
| **RecurringGift**         | A schedule that produces Gifts at a regular interval — monthly, quarterly, annually.                             |
| **GiftProjectAllocation** | The breakdown of a Gift across one or more Projects. Lives inside the Gift record, not as a standalone resource. |

### Campaign and form configuration

| Resource                                 | What it represents                                                                                                                          |
| ---------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
| **Campaign**                             | A top-level fundraising effort — an annual appeal, a capital campaign, a specific initiative. Owns DonationForms and Segments.              |
| **Segment**                              | A subdivision of a Campaign — typically one per appeal version or channel. Lets the customer report on which channel produced a given gift. |
| **Project**                              | A funding destination. Designations on Gifts point to Projects.                                                                             |
| **Premium**                              | A thank-you gift or benefit offered in exchange for a donation. Books, mugs, event tickets.                                                 |
| **MotivationCode / MotivationCodeGroup** | Codes used to track *why* a donation was given — useful for analyzing what drives donor response.                                           |
| **CustomField**                          | Org-defined fields that capture data outside the standard schema. Can apply to Donors or Gifts.                                             |
| **EmailList**                            | An email distribution list maintained in the customer's organization.                                                                       |
| **Activity**                             | Org-wide activity feed of recent events.                                                                                                    |

## Relationships at a glance

```mermaid theme={null}
graph TD
  Donor["Donor"]
  Address["DonorAddress"]
  Contact["DonorContactMethod"]
  Gift["Gift"]
  RG["RecurringGift"]
  Alloc["GiftProjectAllocation"]
  Campaign["Campaign"]
  Segment["Segment"]
  Project["Project"]
  Premium["Premium"]
  Form["DonationForm"]

  Donor -->|has many| Address
  Donor -->|has many| Contact
  Donor -->|has many| Gift
  Donor -->|has many| RG
  RG -->|generates many| Gift
  Gift -->|has many| Alloc
  Alloc -->|points to| Project
  Gift -->|may include| Premium
  Gift -->|originated from| Form
  Form -->|belongs to| Segment
  Segment -->|belongs to| Campaign
  Campaign -->|contains many| Form
```

The most important relationships:

* **A Donor is the parent of everything donation-related.** Every Gift belongs to exactly one Donor.
* **A RecurringGift is a schedule, not a payment.** It produces Gifts over time; each generated Gift has a `recurringGiftId` pointing back to the schedule.
* **A Gift designates to one or more Projects via GiftProjectAllocations.** A $500 gift split evenly between two Projects has two allocations of $250 each. Single-Project gifts have one allocation for the full amount.
* **A Gift originated from a Donation Form**, which lives under a Segment, which lives under a Campaign. This lets the customer trace any Gift back to the channel and campaign that produced it.

## The data flow

The most common partner-relevant flow is what happens when a donor completes a donation through a form:

```mermaid theme={null}
sequenceDiagram
  participant Donor
  participant Form as Donation Form<br/>(in the donor's browser)
  participant Raise as Raise API<br/>(prod-api.raisedonors.com)
  participant CRMP as CRM+<br/>(if the org uses it)

  Donor->>Form: Fills out form (amount, identity, payment)
  Form->>Raise: POST /api/Raise/give<br/>(DonatePaymentRequest)
  Raise->>Raise: Process payment via gateway
  Raise->>Raise: Create or match Donor
  Raise->>Raise: Create Gift record
  Raise->>Raise: Fire giftCreate webhook
  Note over Raise,CRMP: Platform-level sync (outside the API surface)
  Raise->>CRMP: Sync donor and gift data
```

A few things to call out about this flow:

* **`POST /api/Raise/give` is the single entry point** for new gifts. There is no `POST /api/Gift` — the only way to create a Gift record in Raise is via the `/api/Raise/give` donation submission path.
* **Donor matching is automatic.** The endpoint matches the incoming donor information against existing Donor records (typically by email) and creates a new Donor only if no match is found.
* **The webhook fires immediately** on Gift creation, not after the platform-level sync. Partners that subscribe to webhook events see gift activity in real-time.
* **The sync to CRM+ is a platform behavior**, not an API action. Your Raise integration doesn't call CRM+ directly. See [How Raise Data Flows to CRM+](/raise/concepts/data-flow-to-crm) for details.

## Gift creation paths

To be explicit about how Gifts come into existence in Raise — because this is one of the most distinctive aspects of the API:

| Source                                      | Endpoint or trigger                                                            |
| ------------------------------------------- | ------------------------------------------------------------------------------ |
| Donation through a Raise-hosted form        | `POST /api/Raise/give` (called by the form on submit)                          |
| Donation through an embedded or custom form | `POST /api/Raise/give` (called directly by the partner integration)            |
| Recurring gift payment processing           | Automatic — Raise's payment processor charges on schedule and creates the Gift |
| Manual entry by a customer's staff          | Through the Raise admin UI, not the API                                        |
| Import from another system                  | Through a customer's data import process (admin UI), not the API               |

There is no API endpoint for manually creating a Gift outside of `POST /api/Raise/give`. Integrations that need to record historical or back-dated gifts coordinate that through the customer's admin team using the platform's import tools.

## Identifiers used throughout the API

Several identifier types appear across the resources. Knowing what they mean helps when reading payloads:

| Identifier            | What it identifies                                                                 | Where it appears                                    |
| --------------------- | ---------------------------------------------------------------------------------- | --------------------------------------------------- |
| `id` (Donor)          | The internal Raise primary key for a Donor                                         | `Donor.id`, `Gift.donorId`, `RecurringGift.donorId` |
| `id` (Gift)           | The internal Raise primary key for a Gift                                          | `Gift.id`, return value from `POST /api/Raise/give` |
| `id` (RecurringGift)  | The internal Raise primary key for a recurring gift schedule                       | `RecurringGift.id`, `Gift.recurringGiftId`          |
| `crmKey`              | The donor's primary key in an external CRM (typically CRM+)                        | `Donor.crmKey`                                      |
| `crmSecondKey`        | A secondary CRM identifier                                                         | `Donor.crmSecondKey`                                |
| `transactionId`       | The payment processor's transaction reference                                      | `Gift.transactionId`                                |
| `authorizationNumber` | The payment gateway authorization number                                           | `Gift.authorizationNumber`                          |
| `donationId`          | An additional donation identifier (typically used for the donation flow's session) | `Gift.donationId`                                   |
| `paymentMethodId`     | The tokenized payment method                                                       | Request body on `POST /api/Raise/give`              |

The `crmKey` fields are the linkage point between Raise records and CRM+ records when a customer runs both products. The platform sync uses these to keep the two systems aligned.

## Lifecycle states across resources

Some resources have meaningful lifecycle states. The ones partner integrations encounter most:

| Resource          | States                                                               | Where to find                                                               |
| ----------------- | -------------------------------------------------------------------- | --------------------------------------------------------------------------- |
| **Donor**         | `isArchived`, `isGDPRDeleted`, `isTestMode` boolean flags            | Top-level fields on DonorModel                                              |
| **Gift**          | `status` (enum) + `statusText` (display string), `canRefund` boolean | Top-level fields on GiftModel                                               |
| **RecurringGift** | Active / cancelled state with associated dates                       | RecurringGiftModel — see [Recurring Gifts](/raise/concepts/recurring-gifts) |
| **Campaign**      | Sync toggle (`canSync`), publish state                               | CampaignModel — see [Campaigns](/raise/concepts/campaigns)                  |

The `Gift.status` is an integer enum without documented labels in the spec — the `statusText` field provides the human-readable display version. Partner integrations should rely on `statusText` for display and on the documented status enum once published. See [Statuses and Lifecycle States](/raise/concepts/statuses-and-lifecycle-states) for the catalog.

## Test mode

Raise resources carry an `isTestMode` flag throughout — on Donors, Gifts, and the donation submission request itself. Donations submitted with `isTestMode: true` do not charge real payment methods and the resulting records are flagged as test data.

The flag is set per-record, not per-organization — meaning the same organization can carry both real and test records. Filtering by `isTestMode` is a common reporting pattern to exclude development activity from production metrics.

See [Base URLs and Environments — Working against production with care](/raise/base-urls#working-against-production-with-care) for the broader pattern.

## Where to go next

<CardGroup cols={2}>
  <Card title="Donors" icon="user" href="/raise/concepts/donors">
    The Donor resource in depth — identity, addresses, contact methods, merge and transfer operations.
  </Card>

  <Card title="Gifts" icon="hand-holding-dollar" href="/raise/concepts/gifts">
    The Gift resource in depth — the unique creation path through `/api/Raise/give` and the read-only Gift endpoints.
  </Card>

  <Card title="Donation Forms" icon="file-lines" href="/raise/concepts/donation-forms">
    The most distinctive Raise concept — forms, their configuration, and the publish-and-embed lifecycle.
  </Card>

  <Card title="How Raise Data Flows to CRM+" icon="arrow-right-arrow-left" href="/raise/concepts/data-flow-to-crm">
    The platform-level sync between Raise and CRM+ for customers running both products.
  </Card>
</CardGroup>