> ## Documentation Index
> Fetch the complete documentation index at: https://wegive.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# 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

<AccordionGroup>
  <Accordion title="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
  </Accordion>

  <Accordion title="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
  </Accordion>

  <Accordion title="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
  </Accordion>
</AccordionGroup>

## Data Format Requirements

### Date Formatting

<Warning>
  **Critical**: DonorPerfect requires dates in MM/DD/YYYY format. Other formats will cause sync failures.
</Warning>

| 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

<AccordionGroup>
  <Accordion title="Amount Conversion">
    **WeGive to DonorPerfect**

    * WeGive stores amounts in cents (integer)
    * DonorPerfect uses dollars (decimal)
    * Automatic conversion: `amount / 100`
    * Fee deduction applied before conversion
  </Accordion>

  <Accordion title="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
  </Accordion>
</AccordionGroup>

### 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

<AccordionGroup>
  <Accordion title="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
  </Accordion>

  <Accordion title="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
  </Accordion>
</AccordionGroup>

### Duplicate Handling

<Warning>
  **Duplicate Prevention**: The integration prevents duplicates by checking existing DonorPerfect IDs, but initial setup requires clean data to avoid issues.
</Warning>

**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

<AccordionGroup>
  <Accordion title="Unsupported WeGive Fields">
    Fields that don't sync to DonorPerfect:

    * Custom donor profile fields
    * Advanced tribute information
    * Detailed payment method data
    * WeGive-specific metadata
  </Accordion>

  <Accordion title="Unsupported DonorPerfect Fields">
    DonorPerfect fields not imported to WeGive:

    * Volunteer tracking data
    * Detailed relationship information
    * Custom code tables
    * Historical gift modifications
  </Accordion>
</AccordionGroup>

## Performance Considerations

### Large Database Handling

<AccordionGroup>
  <Accordion title="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
  </Accordion>

  <Accordion title="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
  </Accordion>
</AccordionGroup>

### 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

<Steps>
  <Step title="Clean Existing Data">
    Remove duplicate donors and standardize formats before integration
  </Step>

  <Step title="Validate Email Addresses">
    Ensure all donors have valid, unique email addresses
  </Step>

  <Step title="Organize Fund Structure">
    Set up clear GL code organization in DonorPerfect
  </Step>

  <Step title="Test with Sample Data">
    Use a subset of data for initial testing and validation
  </Step>
</Steps>

### Ongoing Management

<CardGroup cols={2}>
  <Card title="Regular Monitoring" icon="chart-line">
    Check sync status weekly and address any errors promptly
  </Card>

  <Card title="Data Quality Maintenance" icon="shield-check">
    Maintain clean data in both systems to prevent sync issues
  </Card>

  <Card title="Performance Optimization" icon="gauge-high">
    Monitor sync times and adjust batch sizes if needed
  </Card>

  <Card title="Error Resolution" icon="wrench">
    Address sync errors quickly to maintain data consistency
  </Card>
</CardGroup>

## Common Limitations

### Technical Limitations

<Warning>
  These limitations are inherent to the DonorPerfect API and cannot be modified:
</Warning>

* **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

<AccordionGroup>
  <Accordion title="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
  </Accordion>

  <Accordion title="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
  </Accordion>

  <Accordion title="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
  </Accordion>
</AccordionGroup>

## Next Steps

<CardGroup cols={2}>
  <Card title="Data Mapping Reference" href="/donorperfect/data-mapping/overview">
    Detailed field mapping documentation
  </Card>

  <Card title="Get Support" href="mailto:support@wegive.com">
    Contact our team for integration assistance
  </Card>
</CardGroup>

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](mailto:support@wegive.com).