​

Constituent Mapping

This document details the comprehensive mapping between WeGive donor records and Bloomerang constituent objects, covering both individual and organization types.

​

Overview

Bloomerang uses the Constituent object to represent all contacts, including individual donors, volunteers, board members, and organizations. WeGive maps these to the Donor object with appropriate type distinctions.

​

Individual Constituent Mapping

​

Core Fields

WeGive Field	Bloomerang Field	Type	Required	Transformation
id	Correlation ID	String	No	Stored in WeGive bloomerang_id
first_name	FirstName	String	Yes*	Default “FNU” if empty
middle_name	MiddleName	String	No	Direct mapping
last_name	LastName	String	Yes*	Default “LNU” if empty
email_1	PrimaryEmail.Value	String	No	Email validation
mobile_phone	PrimaryPhone.Number	String	No	Phone formatting

*Either FirstName or LastName is required in Bloomerang

​

Extended Fields

WeGive Field	Bloomerang Field	Transformation	Notes
donor_type	Type	Set to “Individual”	Always Individual for person records
created_at	DateCreated	ISO 8601 format	Read-only in Bloomerang
updated_at	LastModified	ISO 8601 format	Updated on sync

​

Contact Information Mapping

​

Email Addresses

• Primary Email: Main contact email address
• Secondary Email: Additional email addresses (work, personal, etc.)
• Email Types: Categorized as personal, work, or other
• Validation: Email format validation ensures data quality

​

Phone Numbers

• Primary Phone: Main contact number (usually mobile)
• Secondary Phone: Additional numbers (home, work, etc.)
• Phone Types: Categorized as mobile, home, work, or other
• Format Flexibility: Accepts various phone number formats

​

Address Mapping

Address information synchronizes between both systems with these considerations:

• Street Address: Multiple address lines are combined into a single field in Bloomerang
• Geographic Data: City, state, and postal code transfer directly
• Country Information: Defaults to “United States” if not specified
• Address Types: Categorized as home, work, or business addresses
• International Support: Full support for international address formats

​

Organization Constituent Mapping

​

Core Fields

WeGive Field	Bloomerang Field	Type	Required	Transformation
id	Correlation ID	String	No	Stored in WeGive bloomerang_id
name	FullName	String	Yes	Direct mapping
organization_type	Type	String	Yes	Set to “Organization”

​

Organization Information

Organization donors sync from WeGive to Bloomerang with their complete business information, including:

• Organization Name: The full legal or common name of the organization
• Business Address: Complete mailing address information
• Contact Details: Primary phone and email for the organization
• Organization Type: Categorized appropriately in Bloomerang

​

Data Transformation Rules

​

Name Handling

Individual Names:

• If a donor’s first name is missing, it defaults to “FNU” (First Name Unknown)
• If a donor’s last name is missing, it defaults to “LNU” (Last Name Unknown)
• Middle names transfer directly when available
• Either first name or last name is required in Bloomerang

Organization Names:

• Organization names transfer directly from WeGive to Bloomerang
• The constituent type is automatically set to “Organization”

​

Contact Information Processing

Email Validation:

• Email addresses are validated for proper format before syncing
• Invalid email addresses are skipped and won’t sync to Bloomerang
• Primary email becomes the main contact email in Bloomerang

Phone Number Handling:

• Phone numbers accept various formats and are preserved as entered
• International phone numbers with country codes are supported
• Mobile phones are set as the primary contact number by default

​

Address Processing

Address Synchronization:

• Multiple address lines are combined into a single street address field
• Complete address information transfers including city, state, and postal code
• Country defaults to “United States” if not specified
• International addresses are fully supported

​

Sync Operations

​

Push Operation (WeGive → Bloomerang)

Creating New Constituents: When a new donor is created in WeGive, the system automatically creates a corresponding constituent record in Bloomerang with:

• Proper constituent type (Individual or Organization)
• Complete name information with required field defaults
• Primary contact information (email and phone)
• Mailing address when available
• Automatic linking between the two systems

Updating Existing Constituents: When donor information is updated in WeGive, those changes sync to the corresponding Bloomerang constituent record, updating all mapped fields while preserving the connection between systems.

​

Pull Operation (Bloomerang → WeGive)

Importing Constituents: When importing constituent data from Bloomerang into WeGive:

• Individual constituents become individual donors with proper name mapping
• Organization constituents become organization donors
• Contact information transfers including email and phone numbers
• Address information syncs completely
• System maintains the connection for future synchronization

​

Duplicate Detection and Matching

​

Matching Strategy

Primary Matching (in order of preference):

1. Bloomerang ID: Exact match using stored bloomerang_id
2. Email Address: For individuals, match on primary email
3. Name + Address: For organizations, match on name and address
4. Name Only: Fallback for partial matches

​

Conflict Resolution

Data Update Rules:

• Push Operations (WeGive → Bloomerang): WeGive data takes precedence and overwrites Bloomerang data
• Pull Operations (Bloomerang → WeGive): Bloomerang data takes precedence and updates WeGive records
• Automatic Sync: The most recently modified record takes precedence

Field-Level Behavior:

• Contact Information: Always updates with the latest available data
• Name Fields: Updates only when the target field is empty to avoid overwriting existing data
• Addresses: Complete address replacement occurs during sync

​

Validation Rules

​

Required Field Validation

Bloomerang Requirements:

• Individual Constituents: Either first name or last name must be provided
• Organization Constituents: Full organization name is required
• Contact Information: Email addresses must be in valid format
• Phone Numbers: Must contain at least 10 digits to be considered valid

​

Data Quality Checks

Email Validation:

• All email addresses are validated for proper format before syncing
• Invalid emails are rejected and will not transfer between systems

Phone Number Standards:

• Phone numbers must contain at least 10 digits
• Various formatting styles are accepted (spaces, dashes, parentheses)
• International numbers with country codes are supported

​

Sync Behavior and Error Handling

​

Common Issues and Resolutions

Validation Issues:

• Missing Names: When names are missing, defaults are applied (“FNU” for first name, “LNU” for last name)
• Invalid Emails: Invalid email addresses are automatically excluded from sync
• Duplicate Records: System uses matching logic to prevent duplicate creation

Sync Limitations:

• Records must meet minimum field requirements to sync successfully
• Invalid data is automatically cleaned or excluded
• Connection issues may delay sync but will retry automatically

​

Automatic Data Correction

Name Handling:

• Missing first names default to “FNU” (First Name Unknown)
• Missing last names default to “LNU” (Last Name Unknown)
• This ensures all records meet Bloomerang’s requirements

Contact Information:

• Invalid email addresses are excluded from sync to maintain data quality
• Phone numbers are cleaned but original formatting is preserved where possible

​

Sync Performance and Timing

​

Batch Processing

Efficient Synchronization:

• Constituent data syncs in batches to ensure optimal performance
• Large datasets are processed in manageable chunks
• System includes automatic rate limiting to respect API limits
• Failed records are logged and can be retried

​

Data Consistency

Sync Reliability:

• Constituent information is cached briefly to improve performance
• System maintains connection integrity between WeGive and Bloomerang
• Regular validation ensures data quality across both platforms
• Automatic retry mechanisms handle temporary connection issues

This constituent mapping ensures reliable synchronization of donor information between WeGive and Bloomerang, maintaining data integrity while providing customers with seamless access to their supporter information across both platforms.