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)

{
  "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)

{
  "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)

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

Validate required fields
Check for existing constituent (email match)
Create new constituent record
Store correlation ID
Create associated contact records (address, phone, email)
Apply communication preferences

New Blackbaud Constituent → WeGive Donor

Determine constituent type (individual/organization)
Extract contact information
Create WeGive donor record
Store correlation ID
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

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

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

Clean Source Data: Ensure quality before sync
Regular Audits: Monitor data consistency
Backup Strategy: Maintain data backups
Documentation: Keep field mapping records current

Performance Optimization

Batch Processing: Use appropriate batch sizes
Rate Limiting: Respect API limits
Caching: Cache frequently accessed data
Monitoring: Track performance metrics

Security Considerations

Data Encryption: Encrypt sensitive data in transit and at rest
Access Control: Limit sync permissions
Audit Logging: Maintain complete audit trails
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
Integration Documentation: Data Mapping Overview
Blackbaud Documentation: Sky API Constituent Documentation

​Constituent Data Mapping

​Object Overview

​WeGive Donor Object

​Blackbaud Constituent Object

​Individual Constituent Mapping

​Basic Information

​Professional Information

​Contact Information

​Email Addresses

​Phone Numbers

​Addresses

​Communication Preferences

​Custom Fields

​Organization Constituent Mapping

​Basic Information

​Contact Information

​Industry Information

​Household Constituent Mapping

​WeGive Integration Note

​Household Information (Read-Only from Blackbaud)

​Data Transformation Rules

​Name Handling

​Contact Information Validation

​Data Quality Controls

​Sync Behavior

​Create Operations

​Update Operations

​Delete Operations

​API Examples

​Create Individual Constituent

​Update Constituent

​Error Handling

​Common Validation Errors

​Retry Logic

​Monitoring and Reporting

​Sync Metrics

​Data Quality Reports

​Best Practices

​Data Management

​Performance Optimization

​Security Considerations

​Troubleshooting Guide

​Common Issues

​Support Resources

Constituent Data Mapping

Object Overview

WeGive Donor Object

Blackbaud Constituent Object

Individual Constituent Mapping

Basic Information

Professional Information

Contact Information

Email Addresses

Phone Numbers

Addresses

Communication Preferences

Custom Fields

Organization Constituent Mapping

Basic Information

Contact Information

Industry Information

Household Constituent Mapping

WeGive Integration Note

Household Information (Read-Only from Blackbaud)

Data Transformation Rules

Name Handling

Contact Information Validation

Data Quality Controls

Sync Behavior

Create Operations

Update Operations

Delete Operations

API Examples

Create Individual Constituent

Update Constituent

Error Handling

Common Validation Errors

Retry Logic

Monitoring and Reporting

Sync Metrics

Data Quality Reports

Best Practices

Data Management

Performance Optimization

Security Considerations

Troubleshooting Guide

Common Issues

Support Resources