​

Constituent Data Mapping

​

Object Overview

​

WeGive Donor Object

• Purpose: Represents individual donors and organizations in the WeGive platform
• Types: Individual donors and organization donors
• API Endpoint: /donors/{donor}
• Unique Identifier: WeGive donor ID

​

Blackbaud Constituent Object

• Purpose: Represents individuals, organizations, and households in Raiser’s Edge NXT
• Types: Individual, Organization, Household
• API Endpoint: constituent/v1/constituents/{constituent_id}
• Unique Identifier: Blackbaud constituent ID

​

Individual Constituent Mapping

​

Basic Information

​

Professional Information

​

Contact Information

​

Email Addresses

{
  "address": "[email protected]",
  "type": "Email",
  "primary": true,
  "do_not_email": false
}

​

Phone Numbers

{
  "number": "555-123-4567",
  "type": "Mobile",
  "primary": true,
  "do_not_call": false
}

​

Addresses

{
  "address_lines": "123 Main Street",
  "city": "Anytown",
  "state": "CA",
  "postal_code": "12345",
  "country": "United States",
  "type": "Home",
  "primary": true,
  "do_not_mail": false
}

​

Communication Preferences

​

Custom Fields

​

Organization Constituent Mapping

​

Basic Information

​

Contact Information

​

Industry Information

​

Household Constituent Mapping

​

WeGive Integration Note

​

Household Information (Read-Only from Blackbaud)

​

Data Transformation Rules

​

Name Handling

• Empty First Name: Default to “FNU” (First Name Unknown)
• Empty Last Name: Default to “LNU” (Last Name Unknown)
• Name Formatting: Preserve capitalization and spacing
• Special Characters: Handle apostrophes, hyphens, and accents

• Required Field: Organization name must not be empty
• Legal Suffixes: Preserve Inc., LLC, Corp., etc.
• DBA Names: Store “doing business as” names in alternate name field

​

Contact Information Validation

• Must be valid email format
• Maximum 255 characters
• Duplicate email checking across constituents
• Case-insensitive matching

• Flexible input format acceptance
• Standardized storage format
• International number support
• Extension handling

• USPS address validation (where applicable)
• International address support
• PO Box detection and handling
• Geocoding for mapping applications

​

Data Quality Controls

• Email address matching (primary method)
• Name + address combination matching
• Phone number matching as secondary
• Manual merge queue for potential duplicates

• Default values for missing required fields
• Data validation before sync
• Error reporting for invalid data
• Skip records with critical missing data

​

Sync Behavior

​

Create Operations

1. Validate required fields
2. Check for existing constituent (email match)
3. Create new constituent record
4. Store correlation ID
5. Create associated contact records (address, phone, email)
6. Apply communication preferences

1. Determine constituent type (individual/organization)
2. Extract contact information
3. Create WeGive donor record
4. Store correlation ID
5. Apply communication preferences

​

Update Operations

• Last-modified timestamp comparison
• Field-level change detection
• Selective field updates
• Conflict resolution logging

• Contact information: Most recent update wins
• Communication preferences: Preserve opt-out status
• Custom fields: Configurable precedence rules
• Names: Manual review for significant changes

​

Delete Operations

• WeGive: Mark donor as inactive
• Blackbaud: Mark constituent as inactive
• Preserve historical transaction data
• Maintain audit trail

​

API Examples

​

Create Individual Constituent

POST /constituent/v1/constituents
{
  "type": "Individual",
  "first": "John",
  "last": "Smith", 
  "email": {
    "address": "[email protected]",
    "type": "Email",
    "primary": true
  },
  "phone": {
    "number": "555-123-4567",
    "type": "Home",
    "primary": true
  },
  "address": {
    "address_lines": "123 Main Street",
    "city": "Anytown",
    "state": "CA",
    "postal_code": "12345",
    "country": "United States",
    "type": "Home",
    "primary": true
  }
}

​

Update Constituent

PUT /donors/{donor_id}
{
  "first_name": "John",
  "last_name": "Smith",
  "email_1": "[email protected]",
  "mobile_phone": "555-123-4567",
  "mailing_address": {
    "line_1": "123 Main Street",
    "city": "Anytown",
    "state": "CA",
    "postal_code": "12345",
    "country": "United States"
  },
  "blackbaud_id": "12345678-1234-1234-1234-123456789abc"
}

​

Error Handling

​

Common Validation Errors

• Error: First name or last name missing
• Resolution: Use default values (FNU/LNU)
• Action: Log warning and continue

• Error: Email address format invalid
• Resolution: Skip email field
• Action: Log error and continue without email

• Error: Email address already exists
• Resolution: Update existing record instead
• Action: Link to existing constituent

​

Retry Logic

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

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

​

Monitoring and Reporting

​

Sync Metrics

• Constituent creation success rate
• Update operation success rate
• Data validation pass rate
• Duplicate detection accuracy

• Average sync time per record
• API response time monitoring
• Batch processing efficiency
• Error resolution time

​

Data Quality Reports

• Orphaned correlation IDs
• Incomplete contact information
• Communication preference mismatches
• Custom field mapping accuracy

• Failed sync operations
• Data validation failures
• Duplicate detection results
• Manual review queue status

​

Best Practices

​

Data Management

1. Clean Source Data: Ensure quality before sync
2. Regular Audits: Monitor data consistency
3. Backup Strategy: Maintain data backups
4. Documentation: Keep field mapping records current

​

Performance Optimization

1. Batch Processing: Use appropriate batch sizes
2. Rate Limiting: Respect API limits
3. Caching: Cache frequently accessed data
4. Monitoring: Track performance metrics

​

Security Considerations

1. Data Encryption: Encrypt sensitive data in transit and at rest
2. Access Control: Limit sync permissions
3. Audit Logging: Maintain complete audit trails
4. Compliance: Follow data protection regulations

​

Troubleshooting Guide

​

Common Issues

• Check network connectivity
• Verify API credentials
• Review rate limiting status
• Validate data format

• Compare field mappings
• Check transformation rules
• Review conflict resolution
• Validate correlation IDs

• Monitor batch sizes
• Check API response times
• Review error rates
• Optimize sync timing

​

Support Resources

• WeGive Support: [email protected]
• Integration Documentation: Data Mapping Overview
• Blackbaud Documentation: Sky API Constituent Documentation