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

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

<Warning>
  **Email Requirement**: Donors must have valid email addresses to sync. Records without emails are skipped during import.
</Warning>

## Personal Information

### Name Fields

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

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

### Contact Information

#### Phone Numbers

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

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

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

<Note>
  **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.
</Note>

### Address Validation

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

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

## Data Flow Patterns

### WeGive to DonorPerfect (Export)

<Steps>
  <Step title="Donor Creation">
    New WeGive donors automatically create DonorPerfect records
  </Step>

  <Step title="Profile Updates">
    Changes to WeGive donor profiles sync to DonorPerfect
  </Step>

  <Step title="Type Detection">
    Donor type (individual vs. organization) automatically mapped
  </Step>

  <Step title="ID Assignment">
    DonorPerfect assigns new donor ID, stored back in WeGive
  </Step>
</Steps>

### DonorPerfect to WeGive (Import)

<Steps>
  <Step title="Email Matching">
    Existing DonorPerfect donors matched by email address
  </Step>

  <Step title="Profile Import">
    Contact and address information imported to WeGive
  </Step>

  <Step title="Type Mapping">
    DonorPerfect donor types converted to WeGive format
  </Step>

  <Step title="Relationship Linking">
    DonorPerfect ID stored for future synchronization
  </Step>
</Steps>

## API Operations

### DonorPerfect API Actions

<AccordionGroup>
  <Accordion title="Create/Update Donor">
    **Action**: `dp_savedonor`

    **Required Parameters**:

    * `@donor_id` (for updates, empty for new)
    * `@first_name` and `@last_name` (individuals)
    * `@last_name` (organizations)
    * `@email` (required)
    * `@donor_type` ('IN' or 'CO')
    * `@user_id` (set to "WeGive")
  </Accordion>

  <Accordion title="Query Donors">
    **SQL Query Example**:

    ```sql theme={null}
    SELECT donor_id, first_name, last_name, email, 
           address, city, state, zip, mobile_phone, home_phone
    FROM dp 
    WHERE email IS NOT NULL 
      AND email != ''
      AND created_date >= 'YYYY-MM-DD'
    ORDER BY donor_id
    ```
  </Accordion>
</AccordionGroup>

### Error Handling

<Warning>
  **Common Error Scenarios**:
</Warning>

| 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

<CardGroup cols={2}>
  <Card title="Before Sync" icon="check-circle">
    * Validate all email addresses
    * Standardize name formatting
    * Clean duplicate records
    * Review address information
  </Card>

  <Card title="Ongoing Maintenance" icon="refresh">
    * Monitor sync error logs
    * Update invalid email addresses
    * Resolve duplicate conflicts
    * Maintain address accuracy
  </Card>
</CardGroup>

### Data Validation Rules

<AccordionGroup>
  <Accordion title="Required Field Validation">
    **Before Sync Checks**:

    * Email address format and uniqueness
    * Name fields populated appropriately
    * Donor type correctly identified
    * Required fields not empty
  </Accordion>

  <Accordion title="Data Quality Checks">
    **Automatic Corrections**:

    * Email format standardization
    * Phone number cleaning
    * Name case correction
    * Address standardization
  </Accordion>
</AccordionGroup>

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

<Note>
  **Custom Fields**: Standard integration includes core fields. Contact [support@wegive.com](mailto:support@wegive.com) to configure custom field mappings specific to your DonorPerfect setup.
</Note>

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

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

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

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

## Related Documentation

<CardGroup cols={2}>
  <Card title="Transaction Mapping" href="/donorperfect/data-mapping/transaction">
    Learn how donor transactions are mapped
  </Card>

  <Card title="Configuration Guide" href="/donorperfect/configuration-options">
    Configure donor sync settings
  </Card>
</CardGroup>

For additional help with donor data mapping, contact our support team at [support@wegive.com](mailto:support@wegive.com).