​

Integration Nuances

This document outlines important behaviors, limitations, and considerations when using the WeGive Bloomerang integration.

​

Data Flow Overview

The WeGive Bloomerang integration provides seamless bidirectional synchronization between your platforms using:

• Bloomerang API v2: Industry-standard RESTful API
• Real-time Sync: Immediate updates for critical data changes
• Batch Processing: Efficient handling of large data sets
• Rate Limiting: Respectful API usage (1000 requests per hour)

​

Sync Timing and Frequency

​

Automatic Synchronization

Real-time Events:

• New donations are immediately sent to Bloomerang
• Donor profile updates sync within minutes
• Fund changes propagate automatically

Scheduled Operations:

• Bulk data imports run on configurable schedules
• Historical data sync occurs during off-peak hours
• Error recovery processes run automatically

​

Data Handling

​

What Gets Synchronized

From WeGive to Bloomerang:

• New donor profiles (individuals and organizations)
• Donation transactions with payment details
• Fund and designation information
• Contact information updates

From Bloomerang to WeGive:

• Existing constituent records
• Historical donation data
• Fund structures and categories
• Updated contact information

​

Data Matching and Deduplication

Smart Matching Logic:

• Email addresses for individual donors
• Organization names for corporate donors
• Prevents duplicate record creation
• Maintains data integrity across platforms

Conflict Resolution:

• Most recent update takes precedence
• Manual review flagging for complex conflicts
• Automatic retry for temporary sync issues

​

Important Behaviors

​

Name Handling

Individual Donors:

• If first name is missing, defaults to “FNU” (First Name Unknown)
• If last name is missing, defaults to “LNU” (Last Name Unknown)
• This ensures all records meet Bloomerang requirements

Organization Donors:

• Full organization name is required
• Duplicate organization names are handled automatically

​

Payment Method Mapping

Supported Payment Types:

• Credit/debit cards → CreditCard in Bloomerang
• Bank transfers/ACH → EFT in Bloomerang
• Checks → Check in Bloomerang
• Cash donations → Cash in Bloomerang
• Other methods → None in Bloomerang

​

Fund Designations

Default Fund Behavior:

• All transactions must have a fund designation
• If no fund is specified, uses your configured default fund
• Multiple fund allocations are supported for split gifts

​

Address Synchronization

Address Formatting:

• Street address lines are combined in Bloomerang
• Country defaults to “United States” if not specified
• International addresses are supported

​

Limitations and Considerations

​

API Rate Limits

Bloomerang Limits:

• 1000 API requests per hour
• Automatic retry with exponential backoff
• Large syncs may take longer due to rate limiting

​

Data Volume Considerations

Initial Sync:

• Large datasets (10,000+ records) may take several hours
• Sync occurs in background without affecting daily operations
• Progress tracking available in integration logs

Ongoing Sync:

• Real-time for individual transactions
• Batch processing for bulk updates
• Minimal impact on system performance

​

Data Requirements

Required Fields:

• Donors must have either first name or last name (individuals)
• Organizations must have a name
• Transactions must have an amount and date
• At least one fund must exist for transaction mapping

​

Sync Direction Considerations

Bidirectional Sync Caution:

• Carefully consider which direction to enable for each data type
• Bidirectional sync can lead to data ping-ponging if not configured properly
• Test thoroughly before enabling full bidirectional sync

Recommended Approach:

• Start with WeGive → Bloomerang push only
• Add pull operations after validating data quality
• Enable bidirectional sync only when necessary

​

Error Handling

​

Common Sync Issues

Authentication Errors:

• Invalid API key - regenerate in Bloomerang settings
• Expired credentials - rotate API keys regularly

Data Validation Errors:

• Missing required fields - check data completeness
• Invalid email formats - clean email data before sync
• Duplicate records - review matching criteria

Network Issues:

• Connection timeouts - automatic retry handles most cases
• Service unavailable - sync resumes when service is restored

​

Automatic Recovery

Built-in Resilience:

• Failed records are queued for retry
• Exponential backoff prevents API overload
• Manual retry options available in dashboard

​

Error Notifications

Alert Types:

• Critical errors appear in dashboard immediately
• Email notifications for sustained failures
• Weekly summary reports for integration health

​

Best Practices

​

Data Quality

Before Integration:

• Clean duplicate records in both systems
• Standardize naming conventions
• Validate email addresses and phone numbers
• Ensure consistent fund structures

Ongoing Maintenance:

• Monitor integration logs weekly
• Review and resolve sync conflicts promptly
• Maintain clean data in both systems
• Regular backup of critical data

​

Performance Optimization

Sync Configuration:

• Enable only necessary sync directions
• Use scheduled sync for large historical imports
• Monitor API usage to stay within limits
• Configure appropriate batch sizes

​

Security Considerations

API Key Management:

• Store API keys securely
• Rotate keys quarterly
• Monitor for unexpected API usage
• Restrict access to integration settings

Data Privacy:

• Ensure compliance with data protection regulations
• Understand data residency requirements
• Review data sharing agreements
• Maintain audit trails

​

Troubleshooting Tips

​

Sync Performance

Slow Initial Sync:

• Normal for large datasets
• Monitor progress in integration logs
• Consider syncing in smaller batches
• Sync during off-peak hours

Real-time Sync Delays:

• Check network connectivity
• Verify API key is valid
• Review rate limiting status
• Check Bloomerang service status

​

Data Accuracy

Missing Records:

• Verify sync direction settings
• Check data meets requirements
• Review matching criteria
• Look for validation errors in logs

Duplicate Records:

• Review matching logic
• Check for email address conflicts
• Verify organization name uniqueness
• Consider manual deduplication

​

Integration Monitoring

Regular Health Checks:

• Test connection monthly
• Review error rates and trends
• Monitor sync success percentages
• Validate data accuracy periodically

This understanding of integration nuances will help you successfully implement and maintain the WeGive Bloomerang integration while avoiding common pitfalls and ensuring optimal performance.