Neon Account Mapping

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

WeGive Field	Neon Field	Data Type	Direction	Required	Transformation
`id`	Correlation ID	UUID/String	-	No	Stored for tracking
`first_name`	`primaryContact.firstName`	String	Bidirectional	Yes	Direct mapping
`last_name`	`primaryContact.lastName`	String	Bidirectional	Yes	Direct mapping
`name`	Computed	String	Export	No	`firstName + " " + lastName`
`type`	Account type	String	Export	Yes	Set to “individual”

Contact Information

WeGive Field	Neon Field	Data Type	Direction	Required	Transformation
`email_1`	`primaryContact.email1`	Email	Bidirectional	Yes	Email validation
`email_2`	`primaryContact.email2`	Email	Bidirectional	No	Email validation
`email_3`	`primaryContact.email3`	Email	Bidirectional	No	Email validation
`mobile_phone`	`primaryContact.addresses[0].phone3`	Phone	Bidirectional	No	Phone formatting
`home_phone`	`primaryContact.addresses[0].phone1`	Phone	Bidirectional	No	Phone formatting
`office_phone`	`primaryContact.addresses[0].phone2`	Phone	Bidirectional	No	Phone formatting
`fax`	`primaryContact.addresses[0].fax`	Phone	Bidirectional	No	Phone formatting

Communication Preferences

WeGive Field	Neon Field	Data Type	Direction	Required	Transformation
`email_notifications`	`consent.email`	Boolean	Bidirectional	No	Boolean mapping
`sms_notifications`	`consent.sms`	Boolean	Bidirectional	No	Boolean mapping

Integration Fields

WeGive Field	Neon Field	Data Type	Direction	Required	Transformation
`neon_account_id`	`accountId`	Integer	Correlation	No	Direct mapping
`neon_id`	`primaryContact.contactId`	Integer	Correlation	No	Contact reference

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": "john.smith@example.com",
      "email2": null,
      "email3": null,
      "addresses": [...]
    }
  }
}

Company Account Mapping

WeGive Company Donor to Neon Company Account

Core Identity Fields

WeGive Field	Neon Field	Data Type	Direction	Required	Transformation
`id`	Correlation ID	UUID/String	-	No	Stored for tracking
`name`	`name`	String	Bidirectional	Yes	Direct mapping
`type`	Account type	String	Export	Yes	Set to “company”

Contact Information

WeGive Field	Neon Field	Data Type	Direction	Required	Transformation
`email_1`	`primaryContact.email1`	Email	Bidirectional	No	Email validation
`phone`	`primaryContact.addresses[0].phone1`	Phone	Bidirectional	No	Phone formatting
`fax`	`primaryContact.addresses[0].fax`	Phone	Bidirectional	No	Phone formatting

Integration Fields

WeGive Field	Neon Field	Data Type	Direction	Required	Transformation
`neon_account_id`	`accountId`	Integer	Correlation	No	Direct mapping

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": "contact@acme.com",
      "addresses": [...]
    }
  }
}

Address Integration

Primary Address Mapping

Address information is integrated within the account structure:

WeGive Address Field	Neon Address Field	Data Type	Direction	Required
`address_1`	`addresses[0].addressLine1`	String	Bidirectional	No
`address_2`	`addresses[0].addressLine2`	String	Bidirectional	No
`city`	`addresses[0].city`	String	Bidirectional	No
`state`	`addresses[0].stateProvince.code`	String	Bidirectional	No
`zip`	`addresses[0].zipCode`	String	Bidirectional	No
`country`	`addresses[0].country.code`	String	Bidirectional	No

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

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

Account Updates

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

Import from Neon CRM

Account Search: Uses search API with filters for recent changes
User Matching: Attempts to match existing WeGive users by email
Account Creation: Creates new donors for unmatched Neon accounts
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

Integration Path	WeGive Path	Purpose
`consent.email`	`email_notifications`	Email communication preference
`consent.sms`	`sms_notifications`	SMS communication preference
`primaryContact.email1`	`email_1`	Primary email address
`primaryContact.email2`	`email_2`	Secondary email address
`primaryContact.email3`	`email_3`	Tertiary email address
`primaryContact.firstName`	`first_name`	Individual first name
`primaryContact.lastName`	`last_name`	Individual last name

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": "jane.doe@example.com",
      "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": "newemail@company.com"
    }
  }
}

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.