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

# Bloomerang Data Mapping Overview

> Comprehensive mapping between Bloomerang CRM objects and WeGive donor platform data structures

# Data Mapping Overview

This document provides a comprehensive overview of how the WeGive donor platform maps to Bloomerang CRM objects, including standard Bloomerang objects and their relationships with WeGive API endpoints.

## Object Mapping Categories

The Bloomerang integration maps objects across two main categories:

1. **Bloomerang CRM Objects**
   * Core constituent management
   * Transaction and donation tracking
   * Fund and designation management

2. **WeGive Platform Objects**
   * Donor engagement platform
   * Payment processing system
   * Campaign and fundraising tools

## Core Object Mappings

### Constituent Management

| Bloomerang Object | Type         | WeGive Object        | API Endpoint      | Sync Direction |
| ----------------- | ------------ | -------------------- | ----------------- | -------------- |
| Constituent       | Individual   | Donor (Individual)   | `/donors/{donor}` | Bidirectional  |
| Constituent       | Organization | Donor (Organization) | `/donors/{donor}` | Bidirectional  |
| Address           | -            | Address              | Embedded in donor | Bidirectional  |
| Phone             | -            | Phone                | Embedded in donor | Bidirectional  |
| Email             | -            | Email                | Embedded in donor | Bidirectional  |

### Transaction Management

| Bloomerang Object | Type           | WeGive Object   | API Endpoint                     | Sync Direction |
| ----------------- | -------------- | --------------- | -------------------------------- | -------------- |
| Transaction       | Donation       | Transaction     | `/transactions/{transaction}`    | Bidirectional  |
| Transaction       | Pledge Payment | Transaction     | `/transactions/{transaction}`    | Bidirectional  |
| Transaction       | Recurring      | Transaction     | `/transactions/{transaction}`    | Bidirectional  |
| Designation       | -              | Fund Allocation | `/fund_allocations/{allocation}` | Bidirectional  |

### Fund Management

| Bloomerang Object | Type | WeGive Object | API Endpoint    | Sync Direction |
| ----------------- | ---- | ------------- | --------------- | -------------- |
| Fund              | -    | Fund          | `/funds/{fund}` | Bidirectional  |

## Bloomerang Object Details

### Constituent Object

The Constituent object in Bloomerang represents both individual donors and organizations:

#### Individual Constituent Fields

* **Basic Information**: First name, middle name, last name
* **Contact Details**: Primary email and phone number
* **Address Information**: Complete mailing address
* **Identification**: Unique Bloomerang ID for tracking

#### Organization Constituent Fields

* **Organization Name**: Full legal or business name
* **Address Information**: Primary business address
* **Identification**: Unique Bloomerang ID for tracking

### Transaction Object

The Transaction object represents all financial interactions and includes:

* **Financial Details**: Donation amount, date, and payment method
* **Donor Link**: Connection to the constituent who made the donation
* **Fund Designation**: Which fund(s) the donation supports
* **Transaction Status**: Whether the donation was successful or refunded
* **Processing Information**: Fees and reference numbers

### Fund Object

The Fund object represents giving categories and designations with:

* **Fund Information**: Name, description, and current status
* **Financial Goals**: Target amounts and progress tracking
* **Category Classification**: Type of fund (general, restricted, etc.)
* **Organization**: Display order and management settings

## WeGive Object Mappings

### Donor Object Mapping

#### Individual Donor to Bloomerang Constituent

| WeGive Field      | Bloomerang Field         | Transformation         | Required |
| ----------------- | ------------------------ | ---------------------- | -------- |
| `id`              | Stored as correlation ID | -                      | No       |
| `first_name`      | `FirstName`              | Default "FNU" if empty | Yes      |
| `middle_name`     | `MiddleName`             | Direct mapping         | No       |
| `last_name`       | `LastName`               | Default "LNU" if empty | Yes      |
| `email_1`         | `PrimaryEmail.Value`     | Email validation       | No       |
| `mobile_phone`    | `PrimaryPhone.Number`    | Phone formatting       | No       |
| `mailing_address` | `PrimaryAddress`         | Address object         | No       |

#### Organization Donor to Bloomerang Constituent

| WeGive Field      | Bloomerang Field         | Transformation | Required |
| ----------------- | ------------------------ | -------------- | -------- |
| `id`              | Stored as correlation ID | -              | No       |
| `name`            | `FullName`               | Direct mapping | Yes      |
| `mailing_address` | `PrimaryAddress`         | Address object | No       |

### Transaction Object Mapping

#### WeGive Transaction to Bloomerang Transaction

| WeGive Field    | Bloomerang Field         | Transformation              | Required |
| --------------- | ------------------------ | --------------------------- | -------- |
| `id`            | Stored as correlation ID | -                           | No       |
| `amount`        | `Amount`                 | Cents to dollars conversion | Yes      |
| `created_at`    | `Date`                   | Timezone conversion         | Yes      |
| `owner` (donor) | `AccountId`              | Linked constituent          | Yes      |
| `fund`          | `Designations.FundId`    | Fund mapping                | Yes      |
| `source_type`   | `Method`                 | Payment method mapping      | Yes      |
| `status`        | `IsRefunded`             | Status to boolean           | No       |

#### Payment Method Mapping

| WeGive Source Type | Bloomerang Method | Description                   |
| ------------------ | ----------------- | ----------------------------- |
| `card`             | `CreditCard`      | Credit/debit card payments    |
| `bank`             | `EFT`             | Electronic fund transfers     |
| `check`            | `Check`           | Check payments                |
| `cash`             | `Cash`            | Cash donations                |
| `other`            | `None`            | Other/unknown payment methods |

### Fund Object Mapping

#### WeGive Fund to Bloomerang Fund

| WeGive Field    | Bloomerang Field         | Transformation       | Required |
| --------------- | ------------------------ | -------------------- | -------- |
| `id`            | Stored as correlation ID | -                    | No       |
| `name`          | `Name`                   | Direct mapping       | Yes      |
| `bloomerang_id` | `Id`                     | External ID tracking | No       |

## Data Synchronization Rules

### Correlation ID Management

**Primary Keys:**

* WeGive uses `bloomerang_id` fields to track Bloomerang record IDs
* Bloomerang uses custom fields or notes to track WeGive IDs

**Matching Logic:**

1. **Exact ID Match**: Use correlation IDs when available
2. **Email Matching**: For donors without correlation IDs
3. **Name + Address**: Fallback for organizations
4. **Create New**: When no match found

### Sync Direction Rules

#### Push Operations (WeGive → Bloomerang)

* **New Records**: Create new Bloomerang records
* **Existing Records**: Update based on correlation ID
* **Data Precedence**: WeGive data overwrites Bloomerang data
* **Required Fields**: Ensure all Bloomerang required fields are populated

#### Pull Operations (Bloomerang → WeGive)

* **New Records**: Create new WeGive records
* **Existing Records**: Update based on correlation ID
* **Data Precedence**: Bloomerang data overwrites WeGive data
* **Field Mapping**: Transform Bloomerang format to WeGive format

### Conflict Resolution

**Duplicate Prevention:**

* Email address uniqueness for individual donors
* Organization name uniqueness for organization donors
* Transaction reference number tracking

**Update Strategy:**

* **Last Modified Wins**: Most recent update takes precedence
* **Field-Level Merging**: Specific field update rules
* **Manual Review**: Flag conflicts for administrative review

## API Endpoint Reference

### WeGive API Endpoints

#### Donor Management

* `GET /donors` - List all donors
* `GET /donors/{donor}` - Get specific donor
* `POST /donors` - Create new donor
* `PUT /donors/{donor}` - Update existing donor
* `DELETE /donors/{donor}` - Delete donor

#### Transaction Management

* `GET /transactions` - List all transactions
* `GET /transactions/{transaction}` - Get specific transaction
* `POST /transactions` - Create new transaction
* `PUT /transactions/{transaction}` - Update existing transaction

#### Fund Management

* `GET /funds` - List all funds
* `GET /funds/{fund}` - Get specific fund
* `POST /funds` - Create new fund
* `PUT /funds/{fund}` - Update existing fund

### Bloomerang API Endpoints

#### Constituent Management

* `GET /constituents` - List all constituents
* `GET /constituent/{id}` - Get specific constituent
* `POST /constituent` - Create new constituent
* `PUT /constituent/{id}` - Update existing constituent

#### Transaction Management

* `GET /transactions` - List all transactions
* `GET /transaction/{id}` - Get specific transaction
* `POST /transaction` - Create new transaction
* `PUT /transaction/{id}` - Update existing transaction

#### Fund Management

* `GET /funds` - List all funds
* `GET /fund/{id}` - Get specific fund
* `POST /fund` - Create new fund
* `PUT /fund/{id}` - Update existing fund

## Integration Notes

### Data Validation

**Required Field Validation:**

* Bloomerang requires at least FirstName OR LastName for individuals
* WeGive defaults empty names to "FNU" (First Name Unknown) and "LNU" (Last Name Unknown)
* Amount fields must be positive values
* Email fields must pass validation if provided

**Format Requirements:**

* Phone numbers: Flexible formatting, stored as provided
* Email addresses: Must be valid email format
* Dates: ISO 8601 format for API calls
* Amounts: Decimal format with 2 decimal places

### Performance Considerations

**Batch Processing:**

* Maximum 50 records per API call
* Rate limiting: 1000 requests per hour
* Pagination using skip/take parameters

**Error Handling:**

* Automatic retry for transient failures
* Detailed error logging for data validation issues
* Graceful degradation for partial failures

## Related Documentation

* [Constituent Mapping](./constituent)
* [Transaction Mapping](./transaction)
* [Fund Mapping](./fund)
* [Address Mapping](./address)

## Coming Soon

Future integration features under development:

* **Communication Preferences**: Sync email/phone preferences
* **Custom Fields**: Organization-specific field mapping
* **Pledge Management**: Enhanced pledge and commitment tracking
* **Event Integration**: Event registration and participation data