Integration Nuances

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

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

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

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

Caution

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

WeGive to DonorPerfect

• WeGive stores amounts in cents (integer)
• DonorPerfect uses dollars (decimal)
• Automatic conversion: amount / 100
• Fee deduction applied before conversion

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)

Import Process

• Uses created_date and modified_date for filtering
• Processes records in ID order for consistency
• Pagination prevents timeout issues
• Only syncs donors with valid email addresses

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_id for tracking

Duplicate Handling

Caution

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

Fields that don’t sync to DonorPerfect:

• Custom donor profile fields
• Advanced tribute information
• Detailed payment method data
• WeGive-specific metadata

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

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

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

1. Clean Existing Data
2. Remove duplicate donors and standardize formats before integration
3. Validate Email Addresses
4. Ensure all donors have valid, unique email addresses
5. Organize Fund Structure
6. Set up clear GL code organization in DonorPerfect
7. Test with Sample Data
8. 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

Caution

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

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

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

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 support@wegive.com.