​

Account Object Mapping

This document details the comprehensive mapping between Neon CRM account objects (Individual and Company accounts) and WeGive donor records, including field mappings, data transformations, and synchronization behavior.

​

Account Types Overview

​

Individual Account

Represents personal donors with detailed contact information and communication preferences.

​

Company Account

Represents organizational donors including businesses, foundations, and other institutional supporters.

​

Individual Account Mapping

​

WeGive Individual Donor to Neon Individual Account

​

Core Identity Fields

​

Contact Information

​

Communication Preferences

​

Integration Fields

​

Neon Individual Account Structure

​

Account Level Properties

{
  "individualAccount": {
    "accountId": "12345",
    "consent": {
      "dataSharing": "GIVEN",
      "email": "GIVEN",
      "mail": "GIVEN", 
      "phone": "GIVEN",
      "sms": "GIVEN"
    },
    "login": {
      "username": "WeGiveUser",
      "password": "WeGiveTest1234"
    },
    "noSolicitation": false,
    "origin": {
      "originDetail": "WeGive"
    },
    "primaryContact": {
      "contactId": "67890",
      "firstName": "John",
      "lastName": "Smith",
      "email1": "[email protected]",
      "email2": null,
      "email3": null,
      "addresses": [...]
    }
  }
}

​

Company Account Mapping

​

WeGive Company Donor to Neon Company Account

​

Core Identity Fields

​

Contact Information

​

Integration Fields

​

Neon Company Account Structure

​

Account Level Properties

{
  "companyAccount": {
    "name": "Acme Corporation",
    "accountId": "12346",
    "consent": {
      "dataSharing": "GIVEN",
      "email": "GIVEN",
      "mail": "GIVEN",
      "phone": "GIVEN",
      "sms": "NOT_GIVEN"
    },
    "origin": {
      "originDetail": "WeGive"
    },
    "primaryContact": {
      "contactId": "67891",
      "email1": "[email protected]",
      "addresses": [...]
    }
  }
}

​

Address Integration

​

Primary Address Mapping

Address information is integrated within the account structure:

​

Address Structure in Account

{
  "addresses": [
    {
      "isPrimaryAddress": true,
      "addressLine1": "123 Main Street",
      "addressLine2": "Suite 100",
      "city": "Chicago",
      "stateProvince": {
        "code": "IL"
      },
      "zipCode": "60601",
      "phone1": "+1 (555) 123-4567",
      "phone1Type": "Home",
      "phone2": "+1 (555) 234-5678", 
      "phone2Type": "Work",
      "phone3": "+1 (555) 345-6789",
      "phone3Type": "Mobile"
    }
  ]
}

​

Data Transformations

​

Name Processing

• Individual Names: First and last names mapped separately
• Display Name: Computed as firstName + " " + lastName
• Username Generation: Generated from name with non-letter characters removed
• Company Names: Direct mapping to account name field

​

Email Validation

• Format Validation: Email format validated before sync
• Multiple Emails: Support for up to 3 email addresses
• Primary Email: First email address treated as primary contact method

​

Phone Number Formatting

• Flexible Input: Accepts various phone number formats
• Normalization: Phone numbers normalized during sync
• Type Assignment: Phone numbers assigned appropriate types (Home, Work, Mobile)

​

Boolean Mapping

Communication preferences mapped as follows:

• WeGive true: Neon “GIVEN”
• WeGive false: Neon “NOT_GIVEN”
• WeGive null: Neon “UNKNOWN”

​

Synchronization Behavior

​

Account Creation

1. Duplicate Check: Email-based duplicate detection
2. Account Type: Determined by WeGive donor type
3. Primary Contact: Automatically created with account
4. Default Values: System defaults applied for missing optional fields

​

Account Updates

1. Correlation Matching: Uses neon_account_id for exact matching
2. Field Precedence: Last modified wins for conflicting updates
3. Required Fields: Ensures all required fields remain populated
4. Address Handling: Primary address updated or created as needed

​

Import from Neon CRM

1. Account Search: Uses search API with filters for recent changes
2. User Matching: Attempts to match existing WeGive users by email
3. Account Creation: Creates new donors for unmatched Neon accounts
4. Login Association: Links WeGive users to donor records

​

Custom Field Mapping

​

Default Mappings

The integration includes several pre-configured custom field mappings:

​

Account Level Custom Fields

​

Adding Custom Mappings

Organizations can add custom field mappings using the mapping rule system:

{
  "integration": "ACCOUNT",
  "integration_path": "customField.value",
  "wegive_path": "custom_field_name",
  "crm": "NEON",
  "level": "bidirectional"
}

​

Error Handling

​

Validation Errors

• Missing Required Fields: Clear error messages for missing required data
• Invalid Email Format: Email validation with specific error details
• Duplicate Detection: Warnings for potential duplicate accounts
• Data Type Mismatches: Type conversion errors with correction guidance

​

Resolution Strategies

• Manual Review: Administrative interface for resolving account conflicts
• Data Correction: Tools for correcting invalid data before sync
• Duplicate Merging: Guidance for handling duplicate account scenarios
• Field Validation: Pre-sync validation to prevent common errors

​

Performance Considerations

​

Batch Processing

• Account Search: Paginated search for efficient large-scale imports
• Batch Updates: Multiple account updates processed efficiently
• Rate Limiting: Respectful API usage with built-in throttling
• Incremental Sync: Only changed accounts synchronized after initial import

​

Memory Management

• Large Datasets: Efficient processing of large account datasets
• Address Handling: Optimized address processing and validation
• Custom Fields: Efficient handling of organizations with many custom fields

​

API Examples

​

Creating Individual Account

POST /v2/accounts
{
  "individualAccount": {
    "consent": {
      "email": "GIVEN",
      "sms": "NOT_GIVEN"
    },
    "origin": {
      "originDetail": "WeGive"
    },
    "primaryContact": {
      "firstName": "Jane",
      "lastName": "Doe", 
      "email1": "[email protected]",
      "addresses": [
        {
          "isPrimaryAddress": true,
          "addressLine1": "456 Oak Avenue",
          "city": "Springfield",
          "stateProvince": {"code": "IL"},
          "zipCode": "62701"
        }
      ]
    }
  }
}

​

Updating Company Account

PUT /v2/accounts/12346
{
  "companyAccount": {
    "name": "Updated Company Name",
    "primaryContact": {
      "email1": "[email protected]"
    }
  }
}

​

Searching Accounts

POST /v2/accounts/search
{
  "searchFields": [
    {
      "field": "Account Last Modified Date",
      "operator": "GREATER_THAN",
      "value": "2023-01-01"
    },
    {
      "field": "Email 1",
      "operator": "NOT_BLANK"
    }
  ],
  "outputFields": [
    "Account ID",
    "First Name", 
    "Last Name",
    "Email 1",
    "Contact Type"
  ],
  "pagination": {
    "currentPage": 0,
    "pageSize": 200
  }
}

​

Best Practices

​

Data Quality

• Clean Email Data: Ensure valid, unique email addresses
• Complete Names: Provide complete first and last names for individuals
• Consistent Formatting: Use consistent data formats across the platform
• Address Validation: Validate addresses before synchronization

​

Integration Management

• Regular Monitoring: Monitor account sync performance and errors
• Duplicate Prevention: Implement processes to prevent duplicate account creation
• Data Backup: Backup account data before major synchronization operations
• Testing: Test account mappings thoroughly in staging environment

This comprehensive account mapping ensures accurate synchronization of donor information between WeGive and Neon CRM while maintaining data integrity and supporting organizational customization needs.