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

# Constituent Mapping

> Detailed field mapping between WeGive donors and Blackbaud Raiser's Edge NXT constituents

# Constituent Data Mapping

This document details the field-level mappings between WeGive donor records and Blackbaud Raiser's Edge NXT constituent records.

## Object Overview

### WeGive Donor Object

* **Purpose**: Represents individual donors and organizations in the WeGive platform
* **Types**: Individual donors and organization donors
* **API Endpoint**: `/donors/{donor}`
* **Unique Identifier**: WeGive donor ID

### Blackbaud Constituent Object

* **Purpose**: Represents individuals, organizations, and households in Raiser's Edge NXT
* **Types**: Individual, Organization, Household
* **API Endpoint**: `constituent/v1/constituents/{constituent_id}`
* **Unique Identifier**: Blackbaud constituent ID

## Individual Constituent Mapping

### Basic Information

| WeGive Field     | Blackbaud Field        | Data Type | Direction | Required | Notes                           |
| ---------------- | ---------------------- | --------- | --------- | -------- | ------------------------------- |
| `id`             | Correlation ID storage | String    | Both      | No       | Stored in custom field or notes |
| `first_name`     | `first`                | String    | Both      | Yes      | Default "FNU" if empty          |
| `middle_name`    | `middle`               | String    | Both      | No       | Direct mapping                  |
| `last_name`      | `last`                 | String    | Both      | Yes      | Default "LNU" if empty          |
| `suffix`         | `suffix`               | String    | Both      | No       | Jr., Sr., III, etc.             |
| `title`          | `title`                | String    | Both      | No       | Mr., Mrs., Dr., etc.            |
| `nickname`       | `nickname`             | String    | Both      | No       | Preferred name                  |
| `gender`         | `gender`               | String    | Both      | No       | Male, Female, Other, Unknown    |
| `birthdate`      | `birthdate`            | Date      | Both      | No       | ISO 8601 format                 |
| `marital_status` | `marital_status`       | String    | Both      | No       | Single, Married, Divorced, etc. |

### Professional Information

| WeGive Field | Blackbaud Field | Data Type | Direction | Required | Notes              |
| ------------ | --------------- | --------- | --------- | -------- | ------------------ |
| `job_title`  | `job_title`     | String    | Both      | No       | Professional title |
| `employer`   | `employer`      | String    | Both      | No       | Company name       |
| `occupation` | `occupation`    | String    | Both      | No       | Job description    |

### Contact Information

#### Email Addresses

| WeGive Field | Blackbaud Field         | Data Type    | Direction | Required | Notes                 |
| ------------ | ----------------------- | ------------ | --------- | -------- | --------------------- |
| `email_1`    | Primary Email Address   | Email Object | Both      | No       | Primary contact email |
| `email_2`    | Secondary Email Address | Email Object | Both      | No       | Alternative email     |
| `email_3`    | Work Email Address      | Email Object | Both      | No       | Business email        |

**Email Address Object Structure (Blackbaud)**

```json theme={null}
{
  "address": "john@example.com",
  "type": "Email",
  "primary": true,
  "do_not_email": false
}
```

#### Phone Numbers

| WeGive Field   | Blackbaud Field | Data Type    | Direction | Required | Notes                |
| -------------- | --------------- | ------------ | --------- | -------- | -------------------- |
| `mobile_phone` | Primary Phone   | Phone Object | Both      | No       | Mobile/primary phone |
| `home_phone`   | Home Phone      | Phone Object | Both      | No       | Home phone           |
| `work_phone`   | Business Phone  | Phone Object | Both      | No       | Work phone           |

**Phone Object Structure (Blackbaud)**

```json theme={null}
{
  "number": "555-123-4567",
  "type": "Mobile",
  "primary": true,
  "do_not_call": false
}
```

#### Addresses

| WeGive Field      | Blackbaud Field  | Data Type      | Direction | Required | Notes                     |
| ----------------- | ---------------- | -------------- | --------- | -------- | ------------------------- |
| `mailing_address` | Primary Address  | Address Object | Both      | No       | Preferred mailing address |
| `home_address`    | Home Address     | Address Object | Both      | No       | Residential address       |
| `work_address`    | Business Address | Address Object | Both      | No       | Work address              |

**Address Object Structure (Blackbaud)**

```json theme={null}
{
  "address_lines": "123 Main Street",
  "city": "Anytown",
  "state": "CA",
  "postal_code": "12345",
  "country": "United States",
  "type": "Home",
  "primary": true,
  "do_not_mail": false
}
```

### Communication Preferences

| WeGive Field   | Blackbaud Field        | Data Type | Direction | Required | Notes            |
| -------------- | ---------------------- | --------- | --------- | -------- | ---------------- |
| `email_opt_in` | `do_not_email`         | Boolean   | Both      | No       | Inverted mapping |
| `sms_opt_in`   | `do_not_call` (mobile) | Boolean   | Both      | No       | Inverted mapping |
| `mail_opt_in`  | `do_not_mail`          | Boolean   | Both      | No       | Inverted mapping |
| `phone_opt_in` | `do_not_call`          | Boolean   | Both      | No       | Inverted mapping |

### Custom Fields

| WeGive Field    | Blackbaud Field      | Data Type | Direction | Required | Notes                 |
| --------------- | -------------------- | --------- | --------- | -------- | --------------------- |
| `custom_fields` | Attribute Categories | Object    | Both      | No       | Configurable mappings |
| `tags`          | Constituent Codes    | Array     | Both      | No       | Category assignments  |
| `notes`         | Notes                | Array     | Both      | No       | Free-form text notes  |

## Organization Constituent Mapping

### Basic Information

| WeGive Field | Blackbaud Field        | Data Type | Direction | Required | Notes                         |
| ------------ | ---------------------- | --------- | --------- | -------- | ----------------------------- |
| `id`         | Correlation ID storage | String    | Both      | No       | Stored in custom field        |
| `name`       | `name`                 | String    | Both      | Yes      | Organization name             |
| `type`       | `organization_type`    | String    | Both      | No       | Corporation, Foundation, etc. |
| `tax_id`     | `organization_tax_id`  | String    | Both      | No       | EIN or tax identifier         |
| `website`    | `website`              | URL       | Both      | No       | Organization website          |

### Contact Information

Organization contacts use the same email, phone, and address mapping as individuals, with primary contacts designated.

### Industry Information

| WeGive Field | Blackbaud Field | Data Type | Direction | Required | Notes                                  |
| ------------ | --------------- | --------- | --------- | -------- | -------------------------------------- |
| `industry`   | `industry`      | String    | Both      | No       | Business industry                      |
| `sic_code`   | `sic_code`      | String    | Both      | No       | Standard Industrial Classification     |
| `naics_code` | `naics_code`    | String    | Both      | No       | North American Industry Classification |

## Household Constituent Mapping

### WeGive Integration Note

WeGive primarily uses individual donor records. Household information from Blackbaud is preserved but not actively managed in WeGive.

### Household Information (Read-Only from Blackbaud)

| Blackbaud Field     | Purpose                   | Data Type      | Notes                          |
| ------------------- | ------------------------- | -------------- | ------------------------------ |
| `household_id`      | Household identifier      | String         | Links individuals to household |
| `household_name`    | Household name            | String         | Combined family name           |
| `household_address` | Primary household address | Address Object | Shared address                 |
| `household_members` | Family members            | Array          | Individual constituent IDs     |

## Data Transformation Rules

### Name Handling

**Individual Names**

* **Empty First Name**: Default to "FNU" (First Name Unknown)
* **Empty Last Name**: Default to "LNU" (Last Name Unknown)
* **Name Formatting**: Preserve capitalization and spacing
* **Special Characters**: Handle apostrophes, hyphens, and accents

**Organization Names**

* **Required Field**: Organization name must not be empty
* **Legal Suffixes**: Preserve Inc., LLC, Corp., etc.
* **DBA Names**: Store "doing business as" names in alternate name field

### Contact Information Validation

**Email Validation**

* Must be valid email format
* Maximum 255 characters
* Duplicate email checking across constituents
* Case-insensitive matching

**Phone Formatting**

* Flexible input format acceptance
* Standardized storage format
* International number support
* Extension handling

**Address Standardization**

* USPS address validation (where applicable)
* International address support
* PO Box detection and handling
* Geocoding for mapping applications

### Data Quality Controls

**Duplicate Detection**

* Email address matching (primary method)
* Name + address combination matching
* Phone number matching as secondary
* Manual merge queue for potential duplicates

**Required Field Handling**

* Default values for missing required fields
* Data validation before sync
* Error reporting for invalid data
* Skip records with critical missing data

## Sync Behavior

### Create Operations

**New WeGive Donor → Blackbaud Constituent**

1. Validate required fields
2. Check for existing constituent (email match)
3. Create new constituent record
4. Store correlation ID
5. Create associated contact records (address, phone, email)
6. Apply communication preferences

**New Blackbaud Constituent → WeGive Donor**

1. Determine constituent type (individual/organization)
2. Extract contact information
3. Create WeGive donor record
4. Store correlation ID
5. Apply communication preferences

### Update Operations

**Bidirectional Updates**

* Last-modified timestamp comparison
* Field-level change detection
* Selective field updates
* Conflict resolution logging

**Field Priority Rules**

* Contact information: Most recent update wins
* Communication preferences: Preserve opt-out status
* Custom fields: Configurable precedence rules
* Names: Manual review for significant changes

### Delete Operations

**Soft Delete Handling**

* WeGive: Mark donor as inactive
* Blackbaud: Mark constituent as inactive
* Preserve historical transaction data
* Maintain audit trail

## API Examples

### Create Individual Constituent

**WeGive to Blackbaud Request**

```json theme={null}
POST /constituent/v1/constituents
{
  "type": "Individual",
  "first": "John",
  "last": "Smith", 
  "email": {
    "address": "john.smith@example.com",
    "type": "Email",
    "primary": true
  },
  "phone": {
    "number": "555-123-4567",
    "type": "Home",
    "primary": true
  },
  "address": {
    "address_lines": "123 Main Street",
    "city": "Anytown",
    "state": "CA",
    "postal_code": "12345",
    "country": "United States",
    "type": "Home",
    "primary": true
  }
}
```

### Update Constituent

**Blackbaud to WeGive Sync**

```json theme={null}
PUT /donors/{donor_id}
{
  "first_name": "John",
  "last_name": "Smith",
  "email_1": "john.smith@example.com",
  "mobile_phone": "555-123-4567",
  "mailing_address": {
    "line_1": "123 Main Street",
    "city": "Anytown",
    "state": "CA",
    "postal_code": "12345",
    "country": "United States"
  },
  "blackbaud_id": "12345678-1234-1234-1234-123456789abc"
}
```

## Error Handling

### Common Validation Errors

**Missing Required Fields**

* Error: First name or last name missing
* Resolution: Use default values (FNU/LNU)
* Action: Log warning and continue

**Invalid Email Format**

* Error: Email address format invalid
* Resolution: Skip email field
* Action: Log error and continue without email

**Duplicate Constituent**

* Error: Email address already exists
* Resolution: Update existing record instead
* Action: Link to existing constituent

### Retry Logic

**Temporary Failures**

* Network timeouts: Retry with exponential backoff
* Rate limiting: Respect retry-after headers
* Server errors: Retry up to 3 times

**Permanent Failures**

* Validation errors: Log and skip record
* Authorization errors: Alert administrators
* Data conflicts: Queue for manual review

## Monitoring and Reporting

### Sync Metrics

**Success Rates**

* Constituent creation success rate
* Update operation success rate
* Data validation pass rate
* Duplicate detection accuracy

**Performance Metrics**

* Average sync time per record
* API response time monitoring
* Batch processing efficiency
* Error resolution time

### Data Quality Reports

**Regular Audits**

* Orphaned correlation IDs
* Incomplete contact information
* Communication preference mismatches
* Custom field mapping accuracy

**Exception Reports**

* Failed sync operations
* Data validation failures
* Duplicate detection results
* Manual review queue status

## Best Practices

### Data Management

1. **Clean Source Data**: Ensure quality before sync
2. **Regular Audits**: Monitor data consistency
3. **Backup Strategy**: Maintain data backups
4. **Documentation**: Keep field mapping records current

### Performance Optimization

1. **Batch Processing**: Use appropriate batch sizes
2. **Rate Limiting**: Respect API limits
3. **Caching**: Cache frequently accessed data
4. **Monitoring**: Track performance metrics

### Security Considerations

1. **Data Encryption**: Encrypt sensitive data in transit and at rest
2. **Access Control**: Limit sync permissions
3. **Audit Logging**: Maintain complete audit trails
4. **Compliance**: Follow data protection regulations

## Troubleshooting Guide

### Common Issues

**Sync Failures**

* Check network connectivity
* Verify API credentials
* Review rate limiting status
* Validate data format

**Data Mismatches**

* Compare field mappings
* Check transformation rules
* Review conflict resolution
* Validate correlation IDs

**Performance Issues**

* Monitor batch sizes
* Check API response times
* Review error rates
* Optimize sync timing

### Support Resources

* **WeGive Support**: [support@wegive.com](mailto:support@wegive.com)
* **Integration Documentation**: [Data Mapping Overview](/blackbaud/data-mapping/overview)
* **Blackbaud Documentation**: [Sky API Constituent Documentation](https://developer.blackbaud.com/skyapi/docs/services/56b76470069a0509c8f1c5b3)