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

Validate list data and requirements
Check for duplicate list names
Create list record in Blackbaud
Set initial configuration and criteria
Store correlation ID for future updates
Sync initial membership if provided

New Blackbaud Communication List → WeGive Segment

Extract list information and configuration
Map to WeGive segment format
Preserve query criteria and membership rules
Create WeGive segment record
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

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

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

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

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

Segmentation Strategy

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

Data Quality

Validation Rules: Implement comprehensive validation
Regular Audits: Periodic data quality reviews
Duplicate Prevention: Prevent duplicate list creation
Consent Management: Maintain proper consent records
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

Support Contacts

WeGive Support: support@wegive.com
Blackbaud Developer Support: Developer Community
Marketing Automation Support: Available for advanced segmentation and list management scenarios

​Communication List Data Mapping

​Object Overview

​WeGive Segment Object

​Blackbaud Communication List Object

​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

​Membership Processing

​Query and Criteria Processing

​Sync Behavior

​Create Operations

​Update Operations

​Archive and Deletion Operations

​API Examples

​Create Communication List

​Update List Membership

​Smart List with Complex Criteria

​Error Handling and Validation

​Required Field Validation

​Common Error Scenarios

​Retry and Recovery Logic

​Performance Optimization

​Batch Processing

​Caching Strategies

​Reporting and Analytics

​List Performance Metrics

​Communication Effectiveness

​Best Practices

​List Management

​Segmentation Strategy

​Data Quality

​Troubleshooting Guide

​Common Sync Issues

​Data Quality Issues

​Performance Problems

​Support Resources

​Documentation References

​Support Contacts