​

Address Object Mapping

​

Object Overview

​

Neon Address Object

​

WeGive Address Object

​

Core Address Mapping

​

WeGive Address to Neon Address

​

Location Information

​

Address Classification

​

Contact Information

​

Phone Type Mapping

​

Integration Fields

​

Address Types and Context

​

Address Type Handling

​

Mailing Address

• Primary Use: Main contact address for donor
• Neon Integration: Mapped as primary address in Neon CRM
• Phone Integration: All phone numbers included with mailing address
• Default Behavior: Created automatically with donor accounts

​

Billing Address

• Primary Use: Billing address for payment processing
• Neon Integration: Secondary address when different from mailing
• Conditional Creation: Only created if different from mailing address
• Payment Association: Associated with payment method information

​

Primary Address Designation

• Single Primary: Only one address can be marked as primary
• Automatic Selection: First address automatically marked as primary
• Sync Behavior: Primary designation synchronized between platforms
• Display Priority: Primary address used for main contact display

​

Complete Address Structure

​

Full Neon Address Object

{
  "id": "addr123",
  "accountId": "67890",
  "addressLine1": "123 Main Street",
  "addressLine2": "Suite 100",
  "city": "Chicago",
  "stateProvince": {
    "code": "IL",
    "name": "Illinois",
    "status": "ACTIVE"
  },
  "zipCode": "60601",
  "country": {
    "id": "1",
    "name": "United States",
    "status": "ACTIVE"
  },
  "isPrimaryAddress": true,
  "phone1": "+1 (555) 123-4567",
  "phone1Type": "Home",
  "phone2": "+1 (555) 234-5678",
  "phone2Type": "Work", 
  "phone3": "+1 (555) 345-6789",
  "phone3Type": "Mobile",
  "fax": "+1 (555) 456-7890",
  "faxType": "Home"
}

​

WeGive Address Structure

{
  "id": "addr456",
  "addressable_type": "donor",
  "addressable_id": "donor123",
  "type": "mailing",
  "address_1": "123 Main Street",
  "address_2": "Suite 100",
  "city": "Chicago",
  "state": "IL",
  "zip": "60601",
  "country": "US",
  "primary": true,
  "neon_id": "addr123"
}

​

Geographic Data Handling

​

State/Province Mapping

​

State Object Structure

{
  "stateProvince": {
    "code": "IL",
    "name": "Illinois", 
    "status": "ACTIVE"
  }
}

​

Common State Mappings

​

Country Code Mapping

​

Country Object Structure

{
  "country": {
    "id": "1",
    "name": "United States",
    "status": "ACTIVE"
  }
}

​

Common Country Mappings

​

Phone Number Processing

​

Phone Number Formatting

• Input Flexibility: Accepts various phone number formats
• Normalization: Phone numbers normalized to standard format
• Validation: Basic phone number validation applied
• International Support: Support for international phone numbers

​

Phone Number Examples

// Input variations accepted
const phoneInputs = [
  "555-123-4567",
  "(555) 123-4567", 
  "+1 555 123 4567",
  "5551234567"
];

// Normalized output
const normalizedPhone = "+1 (555) 123-4567";

​

Phone Type Assignment

• Automatic Detection: Phone type detected based on WeGive field
• Default Types: Standard types assigned (Home, Work, Mobile)
• Type Consistency: Types maintained across synchronization
• Multiple Numbers: Support for multiple phone numbers per address

​

Data Transformations

​

Address Validation

• Required Fields: Address line 1 and city are required
• Format Validation: State and zip code format validation
• Country Validation: Country code validation against Neon standards
• Completeness Check: Ensures address has minimum required information

​

Phone Number Transformation

// Phone number normalization
function normalizePhoneNumber(phone) {
  if (!phone) return null;
  
  // Remove non-digit characters except +
  const cleaned = phone.replace(/[^\d+]/g, '');
  
  // Format for US numbers
  if (cleaned.length === 10) {
    return `+1 (${cleaned.slice(0,3)}) ${cleaned.slice(3,6)}-${cleaned.slice(6)}`;
  }
  
  return cleaned; // Return as-is for international
}

​

Geographic Code Conversion

// State code validation and conversion
function validateStateCode(stateCode) {
  const validStates = ['AL', 'AK', 'AZ', 'AR', 'CA', /* ... */];
  return validStates.includes(stateCode.toUpperCase());
}

// Country code to Neon ID mapping
function getCountryId(countryCode) {
  const countryMap = {
    'US': '1',
    'CA': '2', 
    'UK': '3'
  };
  return countryMap[countryCode] || '1'; // Default to US
}

​

Synchronization Behavior

​

Address Creation

1. Donor Association: Address linked to donor account
2. Primary Designation: First address marked as primary
3. Phone Integration: Phone numbers included with address
4. Validation: Address validated before creation

​

Address Updates

1. Existing Check: Uses neon_id to identify existing addresses
2. Primary Management: Ensures only one primary address
3. Phone Updates: Updates phone numbers with address changes
4. Validation: Revalidates address data on updates

​

Import from Neon CRM

1. Account Association: Links addresses to imported donor accounts
2. Address Creation: Creates WeGive addresses for Neon addresses
3. Phone Import: Imports phone numbers with addresses
4. Type Assignment: Assigns appropriate address types

​

Address Integration with Accounts

​

Account-Address Relationship

​

Within Individual Account

{
  "individualAccount": {
    "primaryContact": {
      "addresses": [
        {
          "isPrimaryAddress": true,
          "addressLine1": "123 Main Street",
          "city": "Chicago",
          "stateProvince": {"code": "IL"},
          "zipCode": "60601",
          "phone1": "+1 (555) 123-4567",
          "phone1Type": "Home"
        }
      ]
    }
  }
}

​

Separate Address Management

• Independent Updates: Address updates independent of account changes
• Bulk Operations: Batch address updates for efficiency
• Relationship Maintenance: Address-account relationships maintained
• Validation: Address validation independent of account validation

​

Error Handling

​

Validation Errors

• Missing Required Fields: Clear errors for missing address line 1 or city
• Invalid State/Country: Validation errors for invalid geographic codes
• Phone Format Errors: Phone number format validation errors
• Duplicate Addresses: Prevention of duplicate address creation

​

Resolution Strategies

• Data Correction: Tools for correcting invalid address data
• Geocoding Support: Address validation and geocoding services
• Manual Review: Administrative interface for address conflicts
• Bulk Correction: Tools for bulk address data correction

​

Performance Considerations

​

Address Processing

• Batch Operations: Efficient processing of multiple addresses
• Validation Optimization: Optimized address validation routines
• Phone Processing: Efficient phone number normalization
• Geographic Lookup: Optimized state/country code lookups

​

Memory Management

• Large Datasets: Efficient processing of large address datasets
• Phone Storage: Optimized storage of phone number data
• Geographic Data: Efficient storage of geographic reference data
• Correlation Tracking: Optimized address correlation management

​

API Examples

​

Creating Address

POST /v2/addresses
{
  "accountId": "67890",
  "addressLine1": "456 Oak Avenue",
  "addressLine2": "Apartment 2B",
  "city": "Springfield",
  "stateProvince": {"code": "IL"},
  "zipCode": "62701",
  "isPrimaryAddress": false,
  "phone1": "+1 (555) 987-6543",
  "phone1Type": "Home"
}

​

Updating Address

PUT /v2/addresses/addr123
{
  "addressLine2": "Suite 200",
  "phone2": "+1 (555) 111-2222",
  "phone2Type": "Work"
}

​

Getting Account Addresses

GET /v2/accounts/67890/addresses

[
  {
    "id": "addr123",
    "accountId": "67890",
    "addressLine1": "123 Main Street",
    "city": "Chicago",
    "isPrimaryAddress": true,
    "phone1": "+1 (555) 123-4567"
  }
]

​

Best Practices

​

Address Management

• Data Quality: Maintain clean, standardized address data
• Validation: Validate addresses before synchronization
• Phone Numbers: Include complete phone number information
• Geographic Accuracy: Use correct state and country codes

​

Integration Management

• Regular Validation: Regularly validate address data quality
• Phone Updates: Keep phone numbers current and accurate
• Primary Management: Ensure proper primary address designation
• Batch Operations: Use batch operations for large address updates

​

Data Quality

• Standardization: Use consistent address formatting
• Completeness: Ensure addresses have required information
• Accuracy: Verify address accuracy with donors
• Regular Cleanup: Remove or archive outdated addresses

​

Address Analytics

​

Available Metrics

• Geographic Distribution: Analyze donor distribution by location
• Phone Coverage: Track phone number completeness
• Address Quality: Monitor address validation rates
• Update Frequency: Track address update patterns

​

Reporting Features

• Geographic Reports: Location-based donor analysis
• Contact Completeness: Phone and address completeness reports
• Data Quality Metrics: Address validation and quality reports
• Change Tracking: Address change history and patterns