Communication List Mapping

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

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

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

Support Contacts

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