​

Communication List Data Mapping

​

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

​

List Configuration

​

List Type Mapping

​

List Status Values

​

Member Management

​

List Membership

​

Membership Operations

​

Communication Preferences

​

Contact Preferences

​

Communication Frequency

​

Frequency Mapping

​

Segmentation and Targeting

​

Demographic Criteria

​

Giving Behavior Criteria

​

Engagement Criteria

​

Query and Filter Configuration

​

Dynamic List Queries

​

Smart List Rules

​

Campaign and Event Integration

​

Campaign Association

​

Event Integration

​

Custom Fields and Attributes

​

Extended List Information

​

Compliance and Privacy

​

Data Transformation Rules

​

Name and Description Processing

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

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

​

Membership Processing

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

• 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

• 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

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

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

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

• 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

• Status change to “Archived”
• Membership preservation for historical reference
• Query criteria maintained for documentation
• Access restriction implementation

​

API Examples

​

Create Communication List

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

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

{
  "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

• 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

• 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

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

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

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

​

Retry and Recovery Logic

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

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

​

Performance Optimization

​

Batch Processing

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

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

​

Caching Strategies

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

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

​

Reporting and Analytics

​

List Performance Metrics

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

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

​

Communication Effectiveness

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

• 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

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

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

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

​

Data Quality Issues

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

• 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

• Optimize batch sizes for list operations
• Review query complexity and efficiency
• Check network connectivity and latency
• Monitor system resource utilization

• 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
• WeGive Segment API Documentation
• Constituent Mapping Documentation
• Campaign Mapping Documentation

​

Support Contacts

• WeGive Support: [email protected]
• Blackbaud Developer Support: Developer Community
• Marketing Automation Support: Available for advanced segmentation and list management scenarios