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

# Communication List Mapping

> Detailed field mapping between WeGive segments and Blackbaud Raiser's Edge NXT communication lists

# Communication List Data Mapping

This document details the field-level mappings between WeGive segment/list records and Blackbaud Raiser's Edge NXT communication list records.

## Object Overview

### WeGive Segment Object

* **Purpose**: Represents donor segments and communication lists in the WeGive platform
* **API Endpoint**: `/segments/{segment}`
* **Unique Identifier**: WeGive segment ID
* **Marketing**: Controls donor targeting and communication preferences

### Blackbaud Communication List Object

* **Purpose**: Represents donor segments and communication lists in Raiser's Edge NXT
* **API Endpoint**: `constituent/v1/constituentlists/{list_id}`
* **Unique Identifier**: Blackbaud list ID
* **Donor Management**: Controls donor grouping and communication targeting

## Core Communication List Mapping

### Basic List 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`        | `name`                 | String    | Both      | Yes      | List display name                            |
| `description` | `description`          | Text      | Both      | No       | Detailed list description                    |
| `type`        | `type`                 | String    | Both      | No       | Static, Dynamic, Smart, Query                |
| `status`      | `status`               | String    | Both      | No       | Active, Inactive, Archived                   |
| `created_at`  | `date_added`           | DateTime  | Both      | No       | List creation timestamp                      |
| `updated_at`  | `date_modified`        | DateTime  | Both      | No       | Last modification timestamp                  |

### List Configuration

| WeGive Field   | Blackbaud Field | Data Type | Direction | Required | Notes                               |
| -------------- | --------------- | --------- | --------- | -------- | ----------------------------------- |
| `category`     | `category`      | String    | Both      | No       | List category classification        |
| `purpose`      | `purpose`       | String    | Both      | No       | Fundraising, Events, Communications |
| `visibility`   | `is_public`     | Boolean   | Both      | No       | Public or private list              |
| `owner_id`     | `owner_id`      | String    | Both      | No       | List owner/manager                  |
| `member_count` | `count`         | Integer   | Both      | No       | Number of list members              |

### List Type Mapping

| WeGive Type | Blackbaud Type | Description                     |
| ----------- | -------------- | ------------------------------- |
| `static`    | `Static`       | Manually maintained member list |
| `dynamic`   | `Query`        | Query-based dynamic membership  |
| `smart`     | `Smart`        | Rule-based automatic membership |
| `imported`  | `Static`       | Imported from external source   |
| `event`     | `Event`        | Event-specific attendee list    |
| `campaign`  | `Campaign`     | Campaign-specific target list   |

### List Status Values

| WeGive Status | Blackbaud Status | Description              |
| ------------- | ---------------- | ------------------------ |
| `active`      | `Active`         | Currently in use         |
| `inactive`    | `Inactive`       | Not currently in use     |
| `archived`    | `Archived`       | Historical/archived list |
| `draft`       | `Draft`          | Under development        |
| `scheduled`   | `Scheduled`      | Scheduled for future use |

## Member Management

### List Membership

| WeGive Field   | Blackbaud Field | Data Type | Direction | Required | Notes                          |
| -------------- | --------------- | --------- | --------- | -------- | ------------------------------ |
| `members`      | `constituents`  | Array     | Both      | No       | List of constituent IDs        |
| `member_count` | `count`         | Integer   | Both      | No       | Total number of members        |
| `add_date`     | `date_added`    | DateTime  | Both      | No       | Date constituent added to list |
| `source`       | `source`        | String    | Both      | No       | How constituent was added      |

### Membership Operations

| WeGive Field      | Blackbaud Field      | Data Type | Direction | Required | Notes                      |
| ----------------- | -------------------- | --------- | --------- | -------- | -------------------------- |
| `add_members`     | Add operation        | Array     | Both      | No       | Constituents to add        |
| `remove_members`  | Remove operation     | Array     | Both      | No       | Constituents to remove     |
| `member_history`  | `membership_history` | Array     | Both      | No       | Membership change history  |
| `bulk_operations` | Batch operations     | Object    | Both      | No       | Bulk add/remove operations |

## Communication Preferences

### Contact Preferences

| WeGive Field    | Blackbaud Field | Data Type | Direction | Required | Notes                       |
| --------------- | --------------- | --------- | --------- | -------- | --------------------------- |
| `email_enabled` | `allow_email`   | Boolean   | Both      | No       | Email communication allowed |
| `mail_enabled`  | `allow_mail`    | Boolean   | Both      | No       | Direct mail allowed         |
| `phone_enabled` | `allow_phone`   | Boolean   | Both      | No       | Phone contact allowed       |
| `sms_enabled`   | `allow_sms`     | Boolean   | Both      | No       | SMS communication allowed   |

### Communication Frequency

| WeGive Field        | Blackbaud Field     | Data Type | Direction | Required | Notes                        |
| ------------------- | ------------------- | --------- | --------- | -------- | ---------------------------- |
| `email_frequency`   | `email_frequency`   | String    | Both      | No       | Email frequency preference   |
| `mail_frequency`    | `mail_frequency`    | String    | Both      | No       | Mail frequency preference    |
| `contact_frequency` | `contact_frequency` | String    | Both      | No       | Overall contact frequency    |
| `do_not_contact`    | `do_not_contact`    | Boolean   | Both      | No       | Complete contact suppression |

### Frequency Mapping

| WeGive Frequency | Blackbaud Frequency | Description              |
| ---------------- | ------------------- | ------------------------ |
| `daily`          | `Daily`             | Daily communications     |
| `weekly`         | `Weekly`            | Weekly communications    |
| `monthly`        | `Monthly`           | Monthly communications   |
| `quarterly`      | `Quarterly`         | Quarterly communications |
| `annually`       | `Annually`          | Annual communications    |
| `never`          | `None`              | No communications        |

## Segmentation and Targeting

### Demographic Criteria

| WeGive Field   | Blackbaud Field       | Data Type | Direction | Required | Notes                  |
| -------------- | --------------------- | --------- | --------- | -------- | ---------------------- |
| `age_range`    | `age_criteria`        | Object    | Both      | No       | Age-based targeting    |
| `gender`       | `gender_criteria`     | String    | Both      | No       | Gender-based targeting |
| `location`     | `geographic_criteria` | Object    | Both      | No       | Geographic targeting   |
| `income_level` | `income_criteria`     | Object    | Both      | No       | Income-based targeting |

### Giving Behavior Criteria

| WeGive Field       | Blackbaud Field      | Data Type | Direction | Required | Notes                     |
| ------------------ | -------------------- | --------- | --------- | -------- | ------------------------- |
| `giving_level`     | `giving_range`       | Object    | Both      | No       | Gift amount criteria      |
| `giving_frequency` | `frequency_criteria` | String    | Both      | No       | Giving frequency criteria |
| `last_gift_date`   | `last_gift_criteria` | Object    | Both      | No       | Recency criteria          |
| `total_giving`     | `lifetime_giving`    | Object    | Both      | No       | Lifetime giving criteria  |
| `fund_affinity`    | `fund_criteria`      | Array     | Both      | No       | Fund preference criteria  |

### Engagement Criteria

| WeGive Field               | Blackbaud Field      | Data Type | Direction | Required | Notes                          |
| -------------------------- | -------------------- | --------- | --------- | -------- | ------------------------------ |
| `event_attendance`         | `event_criteria`     | Object    | Both      | No       | Event participation            |
| `volunteer_history`        | `volunteer_criteria` | Object    | Both      | No       | Volunteer engagement           |
| `communication_engagement` | `engagement_score`   | Decimal   | Both      | No       | Communication engagement level |
| `website_activity`         | `online_activity`    | Object    | Both      | No       | Website interaction            |

## Query and Filter Configuration

### Dynamic List Queries

| WeGive Field         | Blackbaud Field    | Data Type | Direction | Required | Notes                              |
| -------------------- | ------------------ | --------- | --------- | -------- | ---------------------------------- |
| `query_criteria`     | `query_definition` | Object    | Both      | No       | Query definition for dynamic lists |
| `filter_logic`       | `filter_logic`     | String    | Both      | No       | AND/OR logic for criteria          |
| `exclusion_criteria` | `exclusion_rules`  | Object    | Both      | No       | Criteria to exclude constituents   |
| `refresh_frequency`  | `update_frequency` | String    | Both      | No       | How often to refresh membership    |

### Smart List Rules

| WeGive Field      | Blackbaud Field  | Data Type | Direction | Required | Notes                        |
| ----------------- | ---------------- | --------- | --------- | -------- | ---------------------------- |
| `smart_rules`     | `smart_criteria` | Array     | Both      | No       | Automated membership rules   |
| `rule_priority`   | `rule_order`     | Integer   | Both      | No       | Rule execution priority      |
| `rule_conditions` | `conditions`     | Object    | Both      | No       | Conditional logic for rules  |
| `auto_update`     | `auto_refresh`   | Boolean   | Both      | No       | Automatic membership updates |

## Campaign and Event Integration

### Campaign Association

| WeGive Field   | Blackbaud Field       | Data Type | Direction | Required | Notes                     |
| -------------- | --------------------- | --------- | --------- | -------- | ------------------------- |
| `campaign_id`  | `default_campaign_id` | String    | Both      | No       | Associated campaign       |
| `appeal_id`    | `default_appeal_id`   | String    | Both      | No       | Default appeal for list   |
| `package_code` | `package_id`          | String    | Both      | No       | Direct mail package       |
| `source_code`  | `source_code`         | String    | Both      | No       | Marketing source tracking |

### Event Integration

| WeGive Field        | Blackbaud Field      | Data Type | Direction | Required | Notes                         |
| ------------------- | -------------------- | --------- | --------- | -------- | ----------------------------- |
| `event_id`          | `event_id`           | String    | Both      | No       | Associated event              |
| `attendee_status`   | `attendance_status`  | String    | Both      | No       | Registered, Attended, No-show |
| `registration_date` | `registration_date`  | Date      | Both      | No       | Event registration date       |
| `table_assignment`  | `seating_assignment` | String    | Both      | No       | Table or seating assignment   |

## Custom Fields and Attributes

### Extended List Information

| WeGive Field     | Blackbaud Field   | Data Type | Direction | Required | Notes                         |
| ---------------- | ----------------- | --------- | --------- | -------- | ----------------------------- |
| `custom_fields`  | `attributes`      | Object    | Both      | No       | Organization-specific fields  |
| `tags`           | `list_codes`      | Array     | Both      | No       | List categorization tags      |
| `keywords`       | `search_keywords` | Array     | Both      | No       | Search and filtering keywords |
| `priority_level` | `priority`        | String    | Both      | No       | List priority ranking         |

### Compliance and Privacy

| WeGive Field     | Blackbaud Field   | Data Type | Direction | Required | Notes                    |
| ---------------- | ----------------- | --------- | --------- | -------- | ------------------------ |
| `gdpr_compliant` | `gdpr_status`     | Boolean   | Both      | No       | GDPR compliance status   |
| `consent_date`   | `consent_date`    | Date      | Both      | No       | Date consent was given   |
| `opt_in_source`  | `opt_in_method`   | String    | Both      | No       | How consent was obtained |
| `privacy_level`  | `privacy_setting` | String    | Both      | No       | Privacy level setting    |

## Data Transformation Rules

### Name and Description Processing

**List Names**

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

**List Descriptions**

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

### Membership Processing

**Member Synchronization**

* Constituent ID validation before adding
* Duplicate membership prevention
* Batch processing for large member lists
* Incremental updates for efficiency

**Membership History**

* Complete audit trail of membership changes
* Date/time stamps for all operations
* User attribution for manual changes
* Automatic change logging for system updates

### Query and Criteria Processing

**Dynamic Query Conversion**

* WeGive filter criteria mapped to Blackbaud queries
* Complex logic preserved where possible
* Unsupported criteria flagged for manual review
* Query optimization for performance

## Sync Behavior

### Create Operations

**New WeGive Segment → Blackbaud Communication List**

1. Validate list data and requirements
2. Check for duplicate list names
3. Create list record in Blackbaud
4. Set initial configuration and criteria
5. Store correlation ID for future updates
6. Sync initial membership if provided

**New Blackbaud Communication List → WeGive Segment**

1. Extract list information and configuration
2. Map to WeGive segment format
3. Preserve query criteria and membership rules
4. Create WeGive segment record
5. Store correlation ID and external references

### Update Operations

**Bidirectional Updates**

* List name and description changes
* Configuration and criteria updates
* Membership additions and removals
* Status and visibility changes
* Communication preference updates

**Membership Synchronization**

* Real-time membership updates for critical lists
* Batch processing for large membership changes
* Incremental sync for efficiency
* Conflict resolution for concurrent updates

### Archive and Deletion Operations

**List Archival Process**

* Status change to "Archived"
* Membership preservation for historical reference
* Query criteria maintained for documentation
* Access restriction implementation

## API Examples

### Create Communication List

**WeGive to Blackbaud List Creation**

```json theme={null}
POST /constituent/v1/constituentlists
{
  "name": "Major Donor Prospects 2024",
  "description": "High-capacity donors for major gift cultivation",
  "type": "Query",
  "status": "Active",
  "category": "Fundraising",
  "purpose": "Major Gift Cultivation",
  "is_public": false,
  "query_definition": {
    "criteria": [
      {
        "field": "lifetime_giving",
        "operator": "greater_than",
        "value": 10000
      },
      {
        "field": "last_gift_date", 
        "operator": "within_months",
        "value": 24
      }
    ],
    "logic": "AND"
  },
  "communication_preferences": {
    "allow_email": true,
    "allow_mail": true,
    "email_frequency": "Monthly"
  }
}
```

### Update List Membership

**Membership Synchronization**

```json theme={null}
PUT /segments/{segment_id}/members
{
  "add_members": [
    {
      "constituent_id": "12345678-1234-1234-1234-123456789abc",
      "source": "Query Refresh",
      "date_added": "2024-03-15T10:30:00Z"
    },
    {
      "constituent_id": "87654321-4321-4321-4321-cba987654321",
      "source": "Manual Addition",
      "date_added": "2024-03-15T10:30:00Z"
    }
  ],
  "remove_members": [
    {
      "constituent_id": "11111111-1111-1111-1111-111111111111",
      "reason": "Opt-out Request",
      "date_removed": "2024-03-15T10:30:00Z"
    }
  ]
}
```

### Smart List with Complex Criteria

**Advanced Segmentation Example**

```json theme={null}
{
  "name": "Lapsed Donor Reactivation",
  "type": "Smart",
  "smart_criteria": [
    {
      "rule_name": "Lapsed Major Donors",
      "conditions": {
        "lifetime_giving": {"min": 5000},
        "last_gift_date": {"months_ago": {"min": 12, "max": 36}},
        "total_gifts": {"min": 3}
      },
      "priority": 1
    },
    {
      "rule_name": "Previous Event Attendees",
      "conditions": {
        "event_attendance": {"years": [2022, 2023]},
        "last_gift_date": {"months_ago": {"min": 6, "max": 24}}
      },
      "priority": 2
    }
  ],
  "exclusion_rules": {
    "do_not_contact": true,
    "deceased": true,
    "email_opt_out": true
  },
  "auto_refresh": true,
  "update_frequency": "Weekly",
  "attributes": [
    {
      "attribute_category": "Campaign Type",
      "string_value": "Reactivation"
    },
    {
      "attribute_category": "Target Audience",
      "string_value": "Lapsed Donors"
    }
  ]
}
```

## Error Handling and Validation

### Required Field Validation

**Critical Fields**

* List name must not be empty
* List type must be valid enumerated value
* Status must be valid enumerated value
* Query criteria must be properly formatted for dynamic lists
* Member constituent IDs must exist and be valid

**Data Quality Checks**

* Name length validation (max 255 characters)
* Description length validation (max 4000 characters)
* Query syntax validation for dynamic lists
* Constituent ID validation for membership
* Communication preference validation

### Common Error Scenarios

**Invalid Query Criteria**

* Error: Query syntax or criteria invalid
* Resolution: Simplify query or use supported criteria
* Action: Log error and create static list instead

**Constituent Not Found**

* Error: Member constituent ID not found
* Resolution: Skip invalid members or create constituent
* Action: Log warning and continue with valid members

**Permission Errors**

* Error: Insufficient permissions for list operation
* Resolution: Verify user permissions or escalate
* Action: Queue for administrative review

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

**Membership Operations**

* Process membership changes in batches
* Group by operation type for efficiency
* Handle partial batch failures gracefully
* Progress tracking and status reporting

**Query Processing**

* Optimize query criteria for performance
* Cache frequently used query results
* Batch query execution where possible
* Monitor query execution times

### Caching Strategies

**List Data Caching**

* List information cached for 30 minutes
* Membership data cached for 15 minutes
* Query results cached for 10 minutes
* Communication preferences cached for 1 hour

**Performance Monitoring**

* Average list sync time tracking
* Query execution time monitoring
* Membership operation performance
* Cache hit ratio optimization

## Reporting and Analytics

### List Performance Metrics

**Engagement Analytics**

* Email open and click rates by list
* Response rates to direct mail campaigns
* Conversion rates from list communications
* Unsubscribe and opt-out rates

**Membership Analytics**

* List growth and churn rates
* Member lifecycle analysis
* Segmentation effectiveness
* Cross-list membership analysis

### Communication Effectiveness

**Campaign Performance**

* Response rates by list and campaign
* Revenue attribution to specific lists
* Cost-per-acquisition by list
* ROI analysis for list-based campaigns

**List Quality Metrics**

* Data accuracy and completeness
* Deliverability rates
* Engagement score trends
* Segment conversion rates

## Best Practices

### List Management

1. **Clear Naming**: Use descriptive, standardized list names
2. **Regular Maintenance**: Periodic review and cleanup of lists
3. **Criteria Documentation**: Document segmentation criteria clearly
4. **Privacy Compliance**: Ensure compliance with privacy regulations
5. **Performance Monitoring**: Track list performance and effectiveness

### Segmentation Strategy

1. **Purpose-Driven**: Create lists with specific communication purposes
2. **Behavioral Segmentation**: Use giving and engagement behavior
3. **Dynamic Updates**: Leverage dynamic lists for real-time segmentation
4. **Testing**: A/B test different segmentation approaches
5. **Integration**: Align with overall marketing and fundraising strategy

### Data Quality

1. **Validation Rules**: Implement comprehensive validation
2. **Regular Audits**: Periodic data quality reviews
3. **Duplicate Prevention**: Prevent duplicate list creation
4. **Consent Management**: Maintain proper consent records
5. **Cleanup Procedures**: Regular removal of invalid records

## Troubleshooting Guide

### Common Sync Issues

**List Creation Failures**

* Verify list name uniqueness
* Check query criteria syntax and validity
* Validate user permissions for list creation
* Confirm organization settings and limitations

**Membership Sync Problems**

* Review constituent ID validity
* Check for permission restrictions
* Validate bulk operation size limits
* Verify communication preference settings

**Query Performance Issues**

* Analyze query complexity and optimization
* Check for large dataset processing
* Review system resource availability
* Optimize criteria and logic structure

### Data Quality Issues

**Invalid Membership Data**

* Check constituent existence and status
* Verify membership criteria accuracy
* Review duplicate member detection
* Validate communication preferences

**Query Criteria Problems**

* Review criteria syntax and supported operators
* Check for field availability and permissions
* Validate date range and numeric criteria
* Confirm logical operators and combinations

### Performance Problems

**Slow List Processing**

* Optimize batch sizes for list operations
* Review query complexity and efficiency
* 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 Constituent List API Documentation](https://developer.blackbaud.com/skyapi/docs/services/56b76470069a0509c8f1c5b3)
* [WeGive Segment API Documentation](https://api.wegive.com/docs/segments)
* [Constituent Mapping Documentation](/blackbaud/data-mapping/constituent)
* [Campaign Mapping Documentation](/blackbaud/data-mapping/campaign)

### Support Contacts

* **WeGive Support**: [support@wegive.com](mailto:support@wegive.com)
* **Blackbaud Developer Support**: [Developer Community](https://community.blackbaud.com/developer)
* **Marketing Automation Support**: Available for advanced segmentation and list management scenarios