Integration Nuances
Understand platform-specific behaviors, limitations, and best practices for the DonorPerfect integration.
DonorPerfect Integration Nuances
Understanding the specific behaviors and limitations of the DonorPerfect integration will help you optimize your setup and avoid common issues. This guide covers platform-specific considerations and best practices.
Platform-Specific Behaviors
DonorPerfect API Characteristics
XML-Based Communication
XML-Based Communication
Legacy API Format
DonorPerfect uses XML-based API communication:
- All data is exchanged in XML format
- Automatic conversion to/from JSON happens behind the scenes
- Some data type limitations due to XML parsing
- Requires specific date and number formatting
SQL Query Interface
SQL Query Interface
Direct Database Access
The integration uses SQL queries for data retrieval:
- Supports complex filtering and sorting
- Allows efficient incremental synchronization
- Requires understanding of DonorPerfect database structure
- Limited by DonorPerfect’s query security restrictions
Rate Limiting
Rate Limiting
API Usage Limits
DonorPerfect enforces API usage limits:
- Request throttling prevents system overload
- Automatic retry logic handles rate limit responses
- Large data sets may require extended sync times
- Peak usage times may affect sync performance
Data Format Requirements
Date Formatting
Critical: DonorPerfect requires dates in MM/DD/YYYY format. Other formats will cause sync failures.
| Data Type | WeGive Format | DonorPerfect Format | Notes |
|---|---|---|---|
| Transaction Date | ISO 8601 | MM/DD/YYYY | Automatic conversion |
| Donor Birth Date | YYYY-MM-DD | MM/DD/YYYY | Optional field |
| Pledge Start Date | Timestamp | MM/DD/YYYY | Required for pledges |
Currency Handling
Amount Conversion
Amount Conversion
WeGive to DonorPerfect
- WeGive stores amounts in cents (integer)
- DonorPerfect uses dollars (decimal)
- Automatic conversion:
amount / 100 - Fee deduction applied before conversion
Currency Support
Currency Support
Multi-Currency Considerations
- DonorPerfect supports USD by default
- Other currencies sync as-is with currency field
- Exchange rate conversion not automatic
- Consider manual currency handling for international gifts
Text Field Limitations
| Field Type | Character Limit | Handling |
|---|---|---|
| Gift Narrative | 255 characters | Automatic truncation |
| Donor Notes | 8,000 characters | Full text support |
| Address Lines | 50 characters each | Line splitting for long addresses |
Synchronization Behaviors
Incremental Sync Logic
Data Pull (DonorPerfect → WeGive)
Data Pull (DonorPerfect → WeGive)
Import Process
- Uses
created_dateandmodified_datefor filtering - Processes records in ID order for consistency
- Pagination prevents timeout issues
- Only syncs donors with valid email addresses
Data Push (WeGive → DonorPerfect)
Data Push (WeGive → DonorPerfect)
Export Process
- Triggered by new transactions in WeGive
- Creates DonorPerfect records if they don’t exist
- Updates existing records when matches found
- Uses WeGive system as
user_idfor tracking
Duplicate Handling
Duplicate Prevention: The integration prevents duplicates by checking existing DonorPerfect IDs, but initial setup requires clean data to avoid issues.
Duplicate Detection Methods:
- Email address matching for donors
- DonorPerfect ID tracking for existing records
- Transaction ID correlation for gifts
- Manual review recommended for initial sync
Field Mapping Limitations
Hardcoded Values
Some values are hardcoded due to DonorPerfect requirements:
| Field | WeGive Value | DonorPerfect Value | Reason |
|---|---|---|---|
| Country | Various | ”US” | System limitation |
| Record Type | N/A | ”G” (Gift) | Required classification |
| Frequency | Various | ”M” (Monthly) | Simplified mapping |
| User ID | System | ”WeGive” | Integration tracking |
Missing Field Support
Unsupported WeGive Fields
Unsupported WeGive Fields
Fields that don’t sync to DonorPerfect:
- Custom donor profile fields
- Advanced tribute information
- Detailed payment method data
- WeGive-specific metadata
Unsupported DonorPerfect Fields
Unsupported DonorPerfect Fields
DonorPerfect fields not imported to WeGive:
- Volunteer tracking data
- Detailed relationship information
- Custom code tables
- Historical gift modifications
Performance Considerations
Large Database Handling
Initial Sync Performance
Initial Sync Performance
First-Time Setup
Organizations with large databases should expect:
- Extended initial sync times (hours for 10k+ records)
- Potential temporary performance impacts
- Recommendation to schedule during off-peak hours
- Progress monitoring through dashboard
Ongoing Sync Efficiency
Ongoing Sync Efficiency
Regular Operations
After initial setup:
- Incremental syncs complete quickly (minutes)
- Real-time donation processing
- Minimal system impact during normal operations
- Automatic optimization of query performance
Memory and Processing
- Batch Processing: Large datasets processed in manageable chunks
- Memory Management: Automatic cleanup prevents memory issues
- Error Recovery: Failed batches retry automatically
- Progress Tracking: Real-time status updates in dashboard
Best Practices
Data Preparation
Clean Existing Data
Remove duplicate donors and standardize formats before integration
Validate Email Addresses
Ensure all donors have valid, unique email addresses
Organize Fund Structure
Set up clear GL code organization in DonorPerfect
Test with Sample Data
Use a subset of data for initial testing and validation
Ongoing Management
Regular Monitoring
Check sync status weekly and address any errors promptly
Data Quality Maintenance
Maintain clean data in both systems to prevent sync issues
Performance Optimization
Monitor sync times and adjust batch sizes if needed
Error Resolution
Address sync errors quickly to maintain data consistency
Common Limitations
Technical Limitations
These limitations are inherent to the DonorPerfect API and cannot be modified:
- XML Format: All data must be XML-compatible
- Date Format: Strict MM/DD/YYYY requirement
- Field Length: Character limits vary by field type
- Query Complexity: Some complex queries not supported
Business Logic Limitations
- Single Currency: Primary support for USD transactions
- Simplified Recurring: Monthly frequency assumption
- Anonymous Handling: Limited anonymous gift customization
- Tribute Information: Basic tribute/memorial support only
Troubleshooting Common Issues
Sync Failures
API Authentication Errors
API Authentication Errors
Symptoms: “Invalid API key” or “Unauthorized” errors
Solutions:
- Verify API key is correct and active
- Check API key permissions in DonorPerfect
- Ensure account has integration access enabled
Data Format Errors
Data Format Errors
Symptoms: “Invalid date format” or “Field validation” errors
Solutions:
- Check date formats meet MM/DD/YYYY requirement
- Verify required fields are populated
- Review character limits for text fields
Duplicate Record Issues
Duplicate Record Issues
Symptoms: “Duplicate donor” or “Record already exists” errors
Solutions:
- Clean duplicate records before initial sync
- Verify email addresses are unique
- Review donor matching logic
Next Steps
Data Mapping Reference
Detailed field mapping documentation
Get Support
Contact our team for integration assistance
Understanding these nuances will help you successfully implement and maintain your DonorPerfect integration. For additional support or questions about specific behaviors, contact our support team at [email protected].