> ## 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.

# Campaign Attribution

> How a gift traces back through the campaign hierarchy — from Segment to Communication to Campaign.

<Note>
  **Grain:** `CAMPAIGNS` — one row per campaign. `COMMUNICATIONS` — one row per channel within a campaign. `SEGMENTS` — one row per recipient subgroup within a communication.
</Note>

When a gift is recorded, it carries a `SEGMENT_KEY` that links it to the marketing chain that solicited it. Following that key up through `SEGMENTS` → `COMMUNICATIONS` → `CAMPAIGNS` reveals which campaign drove the gift and how much each segment raised.

> **Key rule:** The hierarchy flows top-down at setup but is queried bottom-up from the gift. Start at `GIFTS.SEGMENT_KEY`, then join upward to reach campaign totals.

```mermaid theme={null}
flowchart TD
    CAMPAIGNS:::hub

    CAMPAIGNS -->|"CAMPAIGN_KEY"| COMMUNICATIONS
    COMMUNICATIONS -->|"COMMUNICATION_KEY"| SEGMENTS
    SEGMENTS -->|"SEGMENT_KEY"| GIFTS
    CONTACTS -->|"CONTACT_KEY"| GIFTS

    classDef hub fill:#00A3E0,color:#ffffff,stroke:#081F2C
    classDef entity fill:#CEE7F2,color:#243746,stroke:#41B6E6
    class COMMUNICATIONS,SEGMENTS,GIFTS,CONTACTS entity
```

> **Solid lines** — required join (FK always populated). **Dotted lines** — optional join (FK is nullable; always use `LEFT JOIN`).

## **Table columns**

**Tables on this page:** [<u>CAMPAIGNS</u>](https://github.com/jgunkelvirtuous/mintlify-virtuous-data-documentation/blob/main/data-models/reference/campaign-attribution.mdx#campaigns) · [<u>COMMUNICATIONS</u>](https://github.com/jgunkelvirtuous/mintlify-virtuous-data-documentation/blob/main/data-models/reference/campaign-attribution.mdx#communications) · [<u>SEGMENTS</u>](https://github.com/jgunkelvirtuous/mintlify-virtuous-data-documentation/blob/main/data-models/reference/campaign-attribution.mdx#segments) · [<u>GIFTS (boundary)</u>](https://github.com/jgunkelvirtuous/mintlify-virtuous-data-documentation/blob/main/data-models/reference/campaign-attribution.mdx#gifts) · [<u>CONTACTS (boundary)</u>](https://github.com/jgunkelvirtuous/mintlify-virtuous-data-documentation/blob/main/data-models/reference/campaign-attribution.mdx#contacts)

#### **CAMPAIGNS**

One row per top-level marketing initiative. For all campaign-related tables including emails and events, see [<u>Campaigns — extended reference</u>](https://github.com/jgunkelvirtuous/mintlify-virtuous-data-documentation/blob/main/data-models/reference/campaigns).

| **Column**             | **Type**  | **Notes**                                                            |
| :--------------------- | :-------- | :------------------------------------------------------------------- |
| `CAMPAIGN_KEY`         | TEXT      | Primary key                                                          |
| `NAME`                 | TEXT      | Campaign name (e.g. "End of Year 2025")                              |
| `START_DATE_TIME_UTC`  | TIMESTAMP | Campaign start date                                                  |
| `END_DATE_TIME_UTC`    | TIMESTAMP | Campaign end date                                                    |
| `GIVING_GOAL`          | NUMBER    | Dollar goal for the campaign                                         |
| `CAMPAIGN_IS_DELETED`  | BOOLEAN   | Soft delete flag — always filter `WHERE CAMPAIGN_IS_DELETED = FALSE` |
| `CAMPAIGN_IS_ARCHIVED` | BOOLEAN   | Campaign is archived                                                 |

#### **COMMUNICATIONS**

One row per channel within a campaign (e.g. Direct Mail, Email Blast). Contains pre-aggregated performance totals.

| **Column**                 | **Type** | **Notes**                              |
| :------------------------- | :------- | :------------------------------------- |
| `COMMUNICATION_KEY`        | TEXT     | Primary key                            |
| `CAMPAIGN_KEY`             | TEXT     | FK → CAMPAIGNS                         |
| `NAME`                     | TEXT     | Communication name                     |
| `COMMUNICATION_TYPE_NAME`  | TEXT     | Channel type (e.g. Email, Direct Mail) |
| `TOTAL_GIFTS`              | NUMBER   | Total number of gifts received         |
| `TOTAL_GIFT_AMOUNT`        | NUMBER   | Total dollar amount of gifts received  |
| `AVERAGE_GIFT_AMOUNT`      | NUMBER   | Average gift amount                    |
| `COMMUNICATION_IS_DELETED` | BOOLEAN  | Soft delete flag                       |

#### **SEGMENTS**

One row per recipient subgroup within a communication. `SEGMENT_KEY` is the FK carried on `GIFTS` — it is the entry point for all campaign attribution queries.

| **Column**           | **Type** | **Notes**                                            |
| :------------------- | :------- | :--------------------------------------------------- |
| `SEGMENT_KEY`        | TEXT     | Primary key — also FK on `GIFTS.SEGMENT_KEY`         |
| `COMMUNICATION_KEY`  | TEXT     | FK → COMMUNICATIONS                                  |
| `NAME`               | TEXT     | Segment name (e.g. "Board Members", "Lapsed Donors") |
| `CODE`               | TEXT     | Segment code for mail/print processing               |
| `TOTAL_GIFTS`        | NUMBER   | Total gifts attributed to this segment               |
| `TOTAL_GIFT_AMOUNT`  | NUMBER   | Total gift revenue attributed to this segment        |
| `SEGMENT_IS_DELETED` | BOOLEAN  | Soft delete flag                                     |

#### **GIFTS**

`GIFTS` appears in this diagram as the attribution target — the transaction that carries `SEGMENT_KEY` back to the campaign hierarchy. The full gift structure is documented in [<u>Gifts — extended reference</u>](https://github.com/jgunkelvirtuous/mintlify-virtuous-data-documentation/blob/main/data-models/reference/gifts).

| **Column**        | **Type**  | **Notes**                                        |
| :---------------- | :-------- | :----------------------------------------------- |
| `GIFT_KEY`        | TEXT      | Primary key                                      |
| `CONTACT_KEY`     | TEXT      | FK → CONTACTS — the giving unit                  |
| `SEGMENT_KEY`     | TEXT      | FK → SEGMENTS — campaign attribution entry point |
| `GIFT_DATE_UTC`   | TIMESTAMP | Date the gift was made                           |
| `AMOUNT`          | NUMBER    | Total gift amount                                |
| `GIFT_IS_DELETED` | BOOLEAN   | Soft delete flag                                 |

#### **CONTACTS**

`CONTACTS` appears in this diagram as the giving unit linked to each gift. The full contacts structure is documented in [<u>Contacts — extended reference</u>](https://github.com/jgunkelvirtuous/mintlify-virtuous-data-documentation/blob/main/data-models/reference/contacts).

| **Column**           | **Type** | **Notes**            |
| :------------------- | :------- | :------------------- |
| `CONTACT_KEY`        | TEXT     | Primary key          |
| `NAME`               | TEXT     | Contact display name |
| `CONTACT_IS_DELETED` | BOOLEAN  | Soft delete flag     |

<Tip>
  **Data freshness:** These tables sync continuously from Virtuous CRM. Typical lag is under 4 hours. To check when a record was last updated, inspect the `SF__ROW_SYNCED_DATE_TIME_UTC` column on any table.
</Tip>