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

# Neon Account Mapping

> Detailed mapping between Neon CRM account objects and WeGive donor records

# 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

```json theme={null}
{
  "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

```json theme={null}
{
  "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

```json theme={null}
{
  "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

| 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:

```json theme={null}
{
  "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

```http theme={null}
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

```http theme={null}
PUT /v2/accounts/12346
{
  "companyAccount": {
    "name": "Updated Company Name",
    "primaryContact": {
      "email1": "newemail@company.com"
    }
  }
}
```

### Searching Accounts

```http theme={null}
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.