Donor Data Mapping
Detailed field mapping for donor profiles between WeGive and DonorPerfect systems.
Donor Data Mapping
This document provides comprehensive field mapping details for donor profiles between WeGive and DonorPerfect. The integration supports both individual donors and organizational donors with automatic type detection.
DonorPerfect Table Reference
Primary Table: dp (Donor Profile)
WeGive Model: DonorProfile
Sync Direction: Bidirectional (WeGive ↔ DonorPerfect)
Core Identity Fields
Primary Keys and Identification
| WeGive Field | DonorPerfect Field | Type | Notes |
|---|---|---|---|
dp_id | @donor_id | Integer | Auto-generated DonorPerfect ID |
email_1 | @email | String | Primary matching field for imports |
id | user_id | String | Always set to “WeGive” for tracking |
Email Requirement: Donors must have valid email addresses to sync. Records without emails are skipped during import.
Personal Information
Name Fields
Individual Donors
Individual Donors
For donors with donor_type = 'individual':
| WeGive Field | DonorPerfect Field | Type | Max Length | Required |
|---|---|---|---|---|
first_name | @first_name | String | 50 | Yes |
last_name | @last_name | String | 50 | Yes |
middle_name | Not mapped | String | - | No |
DonorPerfect Type: Set to 'IN' (Individual)
Organizational Donors
Organizational Donors
For donors with donor_type = 'organization':
| WeGive Field | DonorPerfect Field | Type | Max Length | Required |
|---|---|---|---|---|
organization_name | @last_name | String | 50 | Yes |
first_name | @first_name | String | 50 | No |
DonorPerfect Type: Set to 'CO' (Company/Organization)
Contact Information
Phone Numbers
Phone Field Mapping
Phone Field Mapping
| WeGive Field | DonorPerfect Field | Type | Format | Notes |
|---|---|---|---|---|
mobile_phone | @mobile_phone | String | Digits only | Primary mobile number |
home_phone | @home_phone | String | Digits only | Residential phone |
office_phone | @business_phone | String | Digits only | Work/business phone |
fax | @fax_phone | String | Digits only | Fax number |
Phone Number Processing
Phone Number Processing
Automatic Formatting:
- Strips all non-digit characters
- Validates US phone number format
- Handles international numbers as-is
- Empty fields sync as null/empty
Email Addresses
| WeGive Field | DonorPerfect Field | Type | Validation | Notes |
|---|---|---|---|---|
email_1 | @email | String | Email format | Primary email, required for sync |
email_2 | Not mapped | String | - | Secondary emails not synced |
Address Information
Mailing Address Mapping
The integration maps the primary mailing address from WeGive to DonorPerfect:
| WeGive Field | DonorPerfect Field | Type | Max Length | Notes |
|---|---|---|---|---|
mailingAddress.address_1 | @address | String | 50 | Primary address line |
mailingAddress.address_2 | @address2 | String | 50 | Secondary address line |
mailingAddress.city | @city | String | 30 | City name |
mailingAddress.state | @state | String | 2 | State/province code |
mailingAddress.zip | @zip | String | 20 | Postal/ZIP code |
mailingAddress.country | @country | String | 3 | Always set to “US” |
Country Limitation: The integration currently hardcodes country as “US” due to DonorPerfect configuration. International addresses sync with country field as “US” but retain original address information.
Address Validation
Address Processing Rules
Address Processing Rules
Automatic Handling:
- Long address lines are truncated to field limits
- Empty address components sync as null
- Address standardization applied where possible
- Full address required for complete sync
Missing Address Handling
Missing Address Handling
Partial Address Sync:
- Donors without complete addresses still sync
- Available address components are mapped
- Missing fields left empty in DonorPerfect
- No validation errors for incomplete addresses
Data Flow Patterns
WeGive to DonorPerfect (Export)
Donor Creation
New WeGive donors automatically create DonorPerfect records
Profile Updates
Changes to WeGive donor profiles sync to DonorPerfect
Type Detection
Donor type (individual vs. organization) automatically mapped
ID Assignment
DonorPerfect assigns new donor ID, stored back in WeGive
DonorPerfect to WeGive (Import)
Email Matching
Existing DonorPerfect donors matched by email address
Profile Import
Contact and address information imported to WeGive
Type Mapping
DonorPerfect donor types converted to WeGive format
Relationship Linking
DonorPerfect ID stored for future synchronization
API Operations
DonorPerfect API Actions
Create/Update Donor
Create/Update Donor
Action: dp_savedonor
Required Parameters:
@donor_id(for updates, empty for new)@first_nameand@last_name(individuals)@last_name(organizations)@email(required)@donor_type(‘IN’ or ‘CO’)@user_id(set to “WeGive”)
Query Donors
Query Donors
SQL Query Example:
Error Handling
Common Error Scenarios:
| Error Type | Cause | Resolution |
|---|---|---|
| Missing Email | Donor has no email address | Skip record, log warning |
| Invalid Email | Email format validation fails | Correct format and retry |
| Duplicate Email | Email already exists in DonorPerfect | Update existing record |
| Field Too Long | Text exceeds DonorPerfect limits | Truncate and sync |
| API Timeout | Large batch processing | Reduce batch size, retry |
Data Quality Considerations
Best Practices
Before Sync
- Validate all email addresses
- Standardize name formatting
- Clean duplicate records
- Review address information
Ongoing Maintenance
- Monitor sync error logs
- Update invalid email addresses
- Resolve duplicate conflicts
- Maintain address accuracy
Data Validation Rules
Required Field Validation
Required Field Validation
Before Sync Checks:
- Email address format and uniqueness
- Name fields populated appropriately
- Donor type correctly identified
- Required fields not empty
Data Quality Checks
Data Quality Checks
Automatic Corrections:
- Email format standardization
- Phone number cleaning
- Name case correction
- Address standardization
Sync Status and Monitoring
Integration Status Fields
| WeGive Field | Purpose | Values |
|---|---|---|
dp_id | DonorPerfect donor ID | Integer or null |
synced_at | Last sync timestamp | DateTime or null |
sync_status | Current sync state | ’pending’, ‘synced’, ‘error’ |
Monitoring Dashboard
The WeGive Dashboard provides real-time sync status:
- Sync Success Rate: Percentage of successful donor syncs
- Error Summary: Common error types and counts
- Last Sync Time: Most recent successful synchronization
- Pending Records: Number of donors awaiting sync
Advanced Configuration
Custom Field Mapping
Custom Fields: Standard integration includes core fields. Contact [email protected] to configure custom field mappings specific to your DonorPerfect setup.
Selective Sync Options
Configure which donor data synchronizes:
- New Donors Only: Sync only newly created donors
- All Updates: Sync all donor profile changes
- Contact Info Only: Sync contact details, skip address
- Custom Filter: Define specific sync criteria
Troubleshooting
Common Issues
Donors Not Syncing
Donors Not Syncing
Possible Causes:
- Missing or invalid email addresses
- Donor sync disabled in configuration
- API authentication issues
- DonorPerfect permissions problems
Solutions:
- Verify email address validity
- Check integration configuration
- Test API credentials
- Review DonorPerfect user permissions
Duplicate Donor Records
Duplicate Donor Records
Possible Causes:
- Multiple donors with same email
- Case sensitivity in email matching
- Previous sync interruptions
Solutions:
- Clean duplicate emails before sync
- Review email standardization
- Re-sync with cleaned data
Address Information Missing
Address Information Missing
Possible Causes:
- Incomplete address data in WeGive
- Field length limitations in DonorPerfect
- Address validation failures
Solutions:
- Complete address information
- Review field length limits
- Manually correct problematic addresses
Related Documentation
Transaction Mapping
Learn how donor transactions are mapped
Configuration Guide
Configure donor sync settings
For additional help with donor data mapping, contact our support team at [email protected].