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

# Fund Mapping

> Detailed field mapping between WeGive funds and Blackbaud Raiser's Edge NXT funds

# Fund Data Mapping

This document details the field-level mappings between WeGive fund records and Blackbaud Raiser's Edge NXT fund records.

## Object Overview

### WeGive Fund Object

* **Purpose**: Represents giving categories and designations in the WeGive platform
* **API Endpoint**: `/funds/{fund}`
* **Unique Identifier**: WeGive fund ID
* **Management**: Controls donation categorization and reporting

### Blackbaud Fund Object

* **Purpose**: Represents funds, designations, and giving categories in Raiser's Edge NXT
* **API Endpoint**: `fundraising/v1/funds/{fund_id}`
* **Unique Identifier**: Blackbaud fund ID
* **Financial Management**: Controls gift designations and financial reporting

## Core Fund Mapping

### Basic Fund Information

| WeGive Field  | Blackbaud Field        | Data Type | Direction | Required | Notes                                        |
| ------------- | ---------------------- | --------- | --------- | -------- | -------------------------------------------- |
| `id`          | Correlation ID storage | String    | Both      | No       | Stored in custom field or external reference |
| `name`        | `description`          | String    | Both      | Yes      | Fund display name                            |
| `code`        | `fund_code`            | String    | Both      | No       | Short fund identifier                        |
| `type`        | `type`                 | String    | Both      | No       | Fund category classification                 |
| `status`      | `status`               | String    | Both      | No       | Active, Inactive, or Restricted              |
| `goal`        | `goal.value`           | Decimal   | Both      | No       | Fundraising goal amount                      |
| `description` | `long_description`     | Text      | Both      | No       | Detailed fund description                    |

### Fund Classification

| WeGive Field  | Blackbaud Field | Data Type | Direction | Required | Notes                               |
| ------------- | --------------- | --------- | --------- | -------- | ----------------------------------- |
| `category`    | `category`      | String    | Both      | No       | Operating, Capital, Endowment, etc. |
| `subcategory` | `subcategory`   | String    | Both      | No       | Detailed classification             |
| `restricted`  | `is_restricted` | Boolean   | Both      | No       | Whether fund has donor restrictions |
| `endowment`   | `is_endowment`  | Boolean   | Both      | No       | Endowment fund designation          |
| `appeal_code` | `appeal_id`     | String    | Both      | No       | Associated appeal or campaign       |

### Financial Information

| WeGive Field    | Blackbaud Field   | Data Type | Direction | Required | Notes                |
| --------------- | ----------------- | --------- | --------- | -------- | -------------------- |
| `target_amount` | `goal.value`      | Decimal   | Both      | No       | Fundraising target   |
| `raised_amount` | Calculated field  | Decimal   | Pull Only | No       | Total raised to date |
| `balance`       | `current_balance` | Decimal   | Pull Only | No       | Current fund balance |
| `spent_amount`  | Calculated field  | Decimal   | Pull Only | No       | Total expenditures   |

### Fund Status and Lifecycle

| WeGive Field | Blackbaud Field     | Data Type | Direction | Required | Notes                       |
| ------------ | ------------------- | --------- | --------- | -------- | --------------------------- |
| `active`     | `status` = "Active" | Boolean   | Both      | No       | Fund accepting donations    |
| `start_date` | `start_date`        | Date      | Both      | No       | Fund activation date        |
| `end_date`   | `end_date`          | Date      | Both      | No       | Fund closure date           |
| `created_at` | `date_added`        | DateTime  | Both      | No       | Fund creation timestamp     |
| `updated_at` | `date_modified`     | DateTime  | Both      | No       | Last modification timestamp |

## Fund Type Mapping

### Standard Fund Types

| WeGive Type   | Blackbaud Type | Description                    |
| ------------- | -------------- | ------------------------------ |
| `general`     | `Unrestricted` | General operating funds        |
| `restricted`  | `Restricted`   | Donor-restricted funds         |
| `capital`     | `Capital`      | Building and capital campaigns |
| `endowment`   | `Endowment`    | Permanent endowment funds      |
| `scholarship` | `Scholarship`  | Educational scholarships       |
| `program`     | `Program`      | Specific program funding       |
| `emergency`   | `Emergency`    | Emergency or disaster relief   |
| `memorial`    | `Memorial`     | Memorial and tribute funds     |

### Fund Status Values

| WeGive Status | Blackbaud Status | Description                   |
| ------------- | ---------------- | ----------------------------- |
| `active`      | `Active`         | Currently accepting donations |
| `inactive`    | `Inactive`       | Not accepting new donations   |
| `suspended`   | `Suspended`      | Temporarily unavailable       |
| `closed`      | `Closed`         | Permanently closed            |
| `merged`      | `Merged`         | Merged into another fund      |

## Campaign and Appeal Integration

### Campaign Linkage

| WeGive Field    | Blackbaud Field       | Data Type | Direction | Required | Notes                   |
| --------------- | --------------------- | --------- | --------- | -------- | ----------------------- |
| `campaign_id`   | `default_campaign_id` | String    | Both      | No       | Associated campaign     |
| `campaign_name` | Derived from campaign | String    | Both      | No       | Campaign display name   |
| `appeal_id`     | `default_appeal_id`   | String    | Both      | No       | Default appeal for fund |
| `appeal_name`   | Derived from appeal   | String    | Both      | No       | Appeal display name     |

### Marketing and Attribution

| WeGive Field   | Blackbaud Field | Data Type | Direction | Required | Notes                     |
| -------------- | --------------- | --------- | --------- | -------- | ------------------------- |
| `source_code`  | `source_code`   | String    | Both      | No       | Marketing source tracking |
| `package_code` | `package_id`    | String    | Both      | No       | Direct mail package       |
| `segment_code` | `segment_id`    | String    | Both      | No       | Donor segment targeting   |

## Financial Reporting Configuration

### Accounting Integration

| WeGive Field   | Blackbaud Field     | Data Type | Direction | Required | Notes                  |
| -------------- | ------------------- | --------- | --------- | -------- | ---------------------- |
| `gl_account`   | `gl_account_number` | String    | Both      | No       | General ledger account |
| `cost_center`  | `cost_center`       | String    | Both      | No       | Cost center allocation |
| `department`   | `department_code`   | String    | Both      | No       | Department attribution |
| `project_code` | `project_id`        | String    | Both      | No       | Project tracking code  |

### Tax and Compliance

| WeGive Field         | Blackbaud Field     | Data Type | Direction | Required | Notes                         |
| -------------------- | ------------------- | --------- | --------- | -------- | ----------------------------- |
| `tax_deductible`     | `is_tax_deductible` | Boolean   | Both      | No       | Tax deductibility status      |
| `grant_eligible`     | `grant_eligible`    | Boolean   | Both      | No       | Foundation grant eligibility  |
| `irs_classification` | `irs_code`          | String    | Both      | No       | IRS charitable classification |

## Custom Fields and Attributes

### Extended Fund Information

| WeGive Field    | Blackbaud Field   | Data Type | Direction | Required | Notes                         |
| --------------- | ----------------- | --------- | --------- | -------- | ----------------------------- |
| `custom_fields` | `attributes`      | Object    | Both      | No       | Organization-specific fields  |
| `tags`          | `fund_codes`      | Array     | Both      | No       | Fund categorization tags      |
| `keywords`      | `search_keywords` | Array     | Both      | No       | Search and filtering keywords |
| `display_order` | `sort_order`      | Integer   | Both      | No       | Display ordering preference   |

### Stewardship and Recognition

| WeGive Field         | Blackbaud Field      | Data Type | Direction | Required | Notes                      |
| -------------------- | -------------------- | --------- | --------- | -------- | -------------------------- |
| `recognition_name`   | `recognition_name`   | String    | Both      | No       | Name for donor recognition |
| `public_description` | `public_description` | Text      | Both      | No       | Public-facing description  |
| `internal_notes`     | `internal_notes`     | Text      | Both      | No       | Staff-only notes           |
| `donor_benefits`     | `benefits`           | Text      | Both      | No       | Donor benefit description  |

## Data Transformation Rules

### Name and Description Handling

**Fund Names**

* Preserve original formatting and capitalization
* Maximum length: 255 characters
* Special characters allowed and preserved
* Duplicate name detection across systems

**Fund Descriptions**

* HTML markup removed for compatibility
* Maximum length: 4000 characters
* Line breaks preserved where possible
* Rich text formatting converted to plain text

### Amount and Financial Data

**Currency Handling**

* All amounts stored in organization's base currency
* Multi-currency support for international organizations
* Exchange rates captured at time of creation
* Historical rate preservation for reporting

**Goal and Target Processing**

* Goals rounded to nearest dollar
* Percentage completion calculated automatically
* Progress tracking updated with each gift
* Historical goal changes maintained

### Date and Time Processing

**Fund Lifecycle Dates**

* Start dates cannot be in the past when creating new funds
* End dates must be after start dates
* Timezone conversion for international organizations
* Date validation ensures logical sequence

**Status Change Tracking**

* Status change history maintained
* Automatic timestamp recording
* User attribution for manual changes
* Audit trail for compliance

## Sync Behavior

### Create Operations

**New WeGive Fund → Blackbaud Fund**

1. Validate fund data and requirements
2. Check for duplicate fund names or codes
3. Create fund record in Blackbaud
4. Set initial status and configuration
5. Store correlation ID for future updates
6. Configure default campaign/appeal linkage

**New Blackbaud Fund → WeGive Fund**

1. Extract fund information and attributes
2. Map to WeGive fund format
3. Preserve fund classification and status
4. Create WeGive fund record
5. Store correlation ID and external references

### Update Operations

**Bidirectional Updates**

* Fund name and description changes
* Status updates (active/inactive)
* Goal and target modifications
* Campaign and appeal associations
* Custom field and attribute updates

**Restricted Updates**

* Fund codes typically immutable after creation
* Status changes may require administrative approval
* Goal reductions may require audit justification
* Major description changes logged for review

### Archive and Closure Operations

**Fund Closure Process**

* Status change to "Closed" or "Archived"
* Final gift acceptance date recording
* Balance transfer to successor fund (if applicable)
* Historical data preservation
* Donor notification of fund closure

## API Examples

### Create Fund Record

**WeGive to Blackbaud Fund Creation**

```json theme={null}
POST /fundraising/v1/funds
{
  "description": "Annual Operating Fund",
  "fund_code": "AOP2024",
  "type": "Unrestricted",
  "status": "Active",
  "goal": {
    "value": 100000.00,
    "currency": "USD"
  },
  "long_description": "Support for general operating expenses and program delivery",
  "category": "Operating",
  "is_restricted": false,
  "is_tax_deductible": true,
  "start_date": "2024-01-01",
  "end_date": "2024-12-31",
  "gl_account_number": "4010-001",
  "default_campaign_id": "annual-campaign-2024"
}
```

### Update Fund Status

**Blackbaud to WeGive Fund Status Sync**

```json theme={null}
PUT /funds/{fund_id}
{
  "name": "Annual Operating Fund",
  "status": "active",
  "goal": 100000.00,
  "raised_amount": 25000.00,
  "progress_percentage": 25.0,
  "updated_at": "2024-03-15T10:30:00Z",
  "blackbaud_fund_id": "12345678-1234-1234-1234-123456789abc"
}
```

### Fund with Campaign Integration

**Complex Fund with Campaign Linkage**

```json theme={null}
{
  "description": "Building Campaign - Phase 1",
  "fund_code": "BUILD01",
  "type": "Capital",
  "status": "Active",
  "goal": {"value": 500000.00, "currency": "USD"},
  "category": "Capital",
  "is_restricted": true,
  "default_campaign_id": "building-campaign-2024",
  "default_appeal_id": "phase-1-appeal",
  "attributes": [
    {
      "attribute_category": "Building Project",
      "string_value": "New Community Center"
    },
    {
      "attribute_category": "Architect",
      "string_value": "Smith & Associates"
    }
  ],
  "gl_account_number": "1510-001",
  "project_id": "PROJ-2024-001"
}
```

## Error Handling and Validation

### Required Field Validation

**Critical Fields**

* Fund name/description must not be empty
* Fund code must be unique within organization
* Status must be valid enumerated value
* Goal amount must be positive if specified
* Date ranges must be logical (start before end)

**Data Quality Checks**

* Name length validation (max 255 characters)
* Code format validation (alphanumeric plus hyphens)
* Amount precision validation (2 decimal places)
* Date format validation (ISO 8601)
* Status transition validation

### Common Error Scenarios

**Duplicate Fund Names**

* Error: Fund name already exists
* Resolution: Append identifier or modify name
* Action: Queue for administrative review

**Invalid Fund Codes**

* Error: Fund code format invalid or duplicate
* Resolution: Generate alternative code or modify
* Action: Log warning and use system-generated code

**Date Range Validation**

* Error: End date before start date
* Resolution: Adjust dates or use open-ended range
* Action: Log error and notify administrators

### Retry and Recovery Logic

**Temporary Failures**

* Network timeouts: Retry with exponential backoff
* Rate limiting: Respect retry-after headers
* Server errors: Retry up to 3 times with delays

**Permanent Failures**

* Validation errors: Log and skip record
* Authorization errors: Alert system administrators
* Data conflicts: Queue for manual resolution

## Performance Optimization

### Batch Processing

**Fund Creation Batches**

* Process up to 50 funds per API call
* Validate all fund data before batch submission
* Handle partial batch failures gracefully
* Progress tracking and status reporting

**Update Optimization**

* Delta sync for changed records only
* Timestamp-based change detection
* Bulk update operations where supported
* Minimized API calls through intelligent batching

### Caching Strategies

**Reference Data Caching**

* Fund information cached for 30 minutes
* Campaign and appeal data cached for 15 minutes
* Status and type lookups cached for 2 hours
* GL account mappings cached for 1 hour

**Performance Monitoring**

* Average fund sync time tracking
* API response time monitoring
* Error rate alerting by fund type
* Cache hit ratio optimization

## Reporting and Analytics

### Fund Performance Metrics

**Sync Statistics**

* Total funds synchronized per period
* Success/failure rates by fund type
* Average sync time per fund
* Peak processing periods

**Data Quality Metrics**

* Validation error rates by field
* Missing required field frequency
* Duplicate detection accuracy
* Status transition compliance

### Financial Analytics

**Fund Performance Tracking**

* Goal achievement rates by fund type
* Average time to reach funding goals
* Donation frequency by fund
* Donor retention by fund category

**Comparative Analysis**

* Fund performance across systems
* Discrepancy identification and resolution
* ROI analysis by fund type
* Cost-per-dollar-raised calculations

## Fund Hierarchy and Relationships

### Parent-Child Fund Relationships

| WeGive Field      | Blackbaud Field     | Data Type | Direction | Required | Notes                    |
| ----------------- | ------------------- | --------- | --------- | -------- | ------------------------ |
| `parent_fund_id`  | `parent_fund_id`    | String    | Both      | No       | Parent fund relationship |
| `child_funds`     | `sub_funds`         | Array     | Both      | No       | Child fund listings      |
| `hierarchy_level` | Calculated          | Integer   | Both      | No       | Fund hierarchy depth     |
| `rollup_totals`   | `include_in_rollup` | Boolean   | Both      | No       | Include in parent totals |

### Fund Groupings and Categories

| WeGive Field      | Blackbaud Field      | Data Type | Direction | Required | Notes                        |
| ----------------- | -------------------- | --------- | --------- | -------- | ---------------------------- |
| `fund_group`      | `fund_group_id`      | String    | Both      | No       | Fund grouping classification |
| `reporting_group` | `reporting_category` | String    | Both      | No       | Financial reporting group    |
| `display_group`   | `display_category`   | String    | Both      | No       | Public display grouping      |

## Best Practices

### Fund Management

1. **Consistent Naming**: Use standardized fund naming conventions
2. **Clear Descriptions**: Provide detailed fund purposes and restrictions
3. **Regular Review**: Periodically review fund performance and status
4. **Proper Classification**: Use appropriate fund types and categories

### Data Quality

1. **Validation Rules**: Implement comprehensive validation before sync
2. **Duplicate Prevention**: Check for existing funds before creation
3. **Regular Audits**: Compare fund data between systems regularly
4. **Cleanup Procedures**: Maintain procedures for fund merging and closure

### Performance Optimization

1. **Batch Operations**: Use batch processing for bulk fund operations
2. **Selective Sync**: Only sync changed fund records
3. **Caching Strategy**: Cache frequently accessed fund data
4. **Monitoring**: Track fund sync performance and errors

### Compliance and Security

1. **Access Control**: Limit fund modification permissions
2. **Audit Trail**: Maintain complete change history
3. **Approval Workflows**: Require approval for significant changes
4. **Backup Strategy**: Regular backups of fund configuration

## Troubleshooting Guide

### Common Sync Issues

**Fund Creation Failures**

* Verify fund name uniqueness
* Check fund code format and availability
* Validate goal amounts and date ranges
* Confirm user permissions for fund creation

**Status Update Problems**

* Review status transition rules
* Check for active donations preventing closure
* Verify user authorization for status changes
* Validate date constraints for status changes

**Goal and Financial Discrepancies**

* Compare calculation methods between systems
* Check for currency conversion issues
* Verify gift allocation and rollup logic
* Review date range filters for calculations

### Data Quality Issues

**Missing Fund Information**

* Check field mapping completeness
* Verify data availability in source system
* Review sync scope and filtering rules
* Validate required field population

**Inconsistent Classifications**

* Review fund type and category mappings
* Check for custom field configuration differences
* Validate enumerated value consistency
* Confirm hierarchy relationship accuracy

### Performance Problems

**Slow Fund Processing**

* Optimize batch sizes for fund volume
* Review API response times and bottlenecks
* Check network connectivity and latency
* Monitor system resource utilization

**High Error Rates**

* Analyze error patterns and common causes
* Review data validation rule effectiveness
* Check system capacity and rate limits
* Validate integration configuration settings

## Support Resources

### Documentation References

* [Blackbaud Fund API Documentation](https://developer.blackbaud.com/skyapi/docs/services/56b766a2069a0509c8f1c5c1)
* [WeGive Fund API Documentation](https://api.wegive.com/docs/funds)
* [Campaign Mapping Documentation](/blackbaud/data-mapping/campaign)
* [Gift Mapping Documentation](/blackbaud/data-mapping/gift)

### Support Contacts

* **WeGive Support**: [support@wegive.com](mailto:support@wegive.com)
* **Blackbaud Developer Support**: [Developer Community](https://community.blackbaud.com/developer)
* **Financial Systems Integration**: Available for complex fund management scenarios