> ## 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 CRM Data Mapping Overview

> Comprehensive mapping between Neon CRM objects and WeGive donor platform data structures

# Data Mapping Overview

This document provides a comprehensive overview of how the WeGive donor platform maps to Neon CRM objects, including their relationships with WeGive API endpoints and synchronization behavior.

## Object Mapping Categories

The Neon CRM integration maps objects across two main categories:

1. **Neon CRM Objects**
   * Account management (Individual and Company accounts)
   * Contact information and communication preferences
   * Donation and payment processing
   * Campaign and fundraising tracking
   * Address and location management
   * Recurring donation scheduling

2. **WeGive Platform Objects**
   * Donor management system
   * Transaction processing
   * Campaign and fundraising tools
   * Recurring donation management
   * Address and contact information

## Core Object Mappings

### Account/Donor Management

| Neon Object        | Type         | WeGive Object         | API Endpoint      | Sync Direction |
| ------------------ | ------------ | --------------------- | ----------------- | -------------- |
| Individual Account | Individual   | Donor (Individual)    | `/donors/{donor}` | Bidirectional  |
| Company Account    | Organization | Donor (Company)       | `/donors/{donor}` | Bidirectional  |
| Primary Contact    | Contact Info | Donor Contact Details | `/donors/{donor}` | Bidirectional  |

### Transaction Management

| Neon Object | Type           | WeGive Object       | API Endpoint                  | Sync Direction |
| ----------- | -------------- | ------------------- | ----------------------------- | -------------- |
| Donation    | Gift           | Transaction         | `/transactions/{transaction}` | Bidirectional  |
| Payment     | Payment Method | Transaction Payment | `/transactions/{transaction}` | Bidirectional  |

### Campaign Management

| Neon Object | Type                 | WeGive Object | API Endpoint            | Sync Direction |
| ----------- | -------------------- | ------------- | ----------------------- | -------------- |
| Campaign    | Fundraising Campaign | Campaign      | `/campaigns/{campaign}` | Bidirectional  |

### Recurring Donation Management

| Neon Object        | Type           | WeGive Object      | API Endpoint                | Sync Direction |
| ------------------ | -------------- | ------------------ | --------------------------- | -------------- |
| Recurring Donation | Recurring Plan | Scheduled Donation | `/scheduled-donations/{id}` | Bidirectional  |

### Address Management

| Neon Object | Type            | WeGive Object | API Endpoint                | Sync Direction |
| ----------- | --------------- | ------------- | --------------------------- | -------------- |
| Address     | Contact Address | Donor Address | `/donors/{donor}/addresses` | Bidirectional  |

## Neon CRM Object Details

### Individual Account Object

The Individual Account object represents personal donors:

#### Primary Contact Fields

* **Personal Information**: First name, middle name, last name, suffix
* **Contact Details**: Multiple email addresses (email1, email2, email3)
* **Communication Preferences**: Email and SMS consent settings
* **Identification**: Unique Neon account ID and contact ID for tracking

#### Account Management

* **Login Credentials**: Username and password for Neon CRM access
* **Account Status**: Active/inactive status and account preferences
* **Origin Tracking**: Source attribution (WeGive platform)
* **No Solicitation**: Communication preference flags

### Company Account Object

The Company Account object represents organizational donors:

#### Organization Information

* **Company Details**: Full legal or business name
* **Contact Information**: Primary business email and phone
* **Account Management**: Primary contact person within organization
* **Business Classification**: Industry and organization type

### Donation Object

The Donation object represents all financial transactions:

#### Financial Details

* **Amount Information**: Donation amount, currency, and fees
* **Timing**: Donation date, received date, and processing dates
* **Attribution**: Campaign association and fund designation
* **Donor Association**: Link to account making the donation

#### Payment Processing

* **Payment Method**: Credit card, ACH, check, cash, or other methods
* **Payment Details**: Payment processor information and transaction IDs
* **Fee Handling**: Processing fees and donor-covered fee amounts
* **Security**: Last four digits and secure payment references

### Campaign Object

The Campaign object represents fundraising initiatives:

#### Campaign Information

* **Basic Details**: Name, description, and campaign status
* **Timeline**: Start date, end date, and campaign duration
* **Goals**: Financial targets and progress tracking
* **Web Integration**: Campaign page URLs and donation form links

#### Campaign Statistics

* **Financial Metrics**: Total donated, donation count, and goal progress
* **Event Metrics**: Registration amounts and attendee counts
* **Performance**: Campaign effectiveness and engagement metrics

### Recurring Donation Object

The Recurring Donation object manages scheduled gifts:

#### Schedule Information

* **Frequency**: Recurring period and interval settings
* **Amount**: Recurring donation amount and currency
* **Timing**: Next payment date and schedule management
* **Duration**: Recurring period type and total duration

#### Account Association

* **Donor Link**: Connection to the donor making recurring gifts
* **Payment Method**: Default payment method for recurring processing
* **Campaign Association**: Optional campaign designation for recurring gifts

### Address Object

The Address object manages contact locations:

#### Address Information

* **Location Details**: Street address, city, state, zip, and country
* **Address Types**: Mailing, billing, and other address classifications
* **Primary Designation**: Primary address flag for main location
* **Contact Integration**: Phone and fax numbers associated with address

## Default Field Mappings

### Account/Donor Mapping

#### Individual Donor to Individual Account

| WeGive Field          | Neon Field                 | Transformation       | Required |
| --------------------- | -------------------------- | -------------------- | -------- |
| `id`                  | Stored as correlation ID   | -                    | No       |
| `first_name`          | `primaryContact.firstName` | Direct mapping       | Yes      |
| `last_name`           | `primaryContact.lastName`  | Direct mapping       | Yes      |
| `email_1`             | `primaryContact.email1`    | Email validation     | Yes      |
| `email_2`             | `primaryContact.email2`    | Email validation     | No       |
| `email_3`             | `primaryContact.email3`    | Email validation     | No       |
| `email_notifications` | `consent.email`            | Boolean conversion   | No       |
| `sms_notifications`   | `consent.sms`              | Boolean conversion   | No       |
| `neon_account_id`     | `accountId`                | Correlation tracking | No       |
| `neon_id`             | `primaryContact.contactId` | Contact reference    | No       |

#### Company Donor to Company Account

| WeGive Field      | Neon Field               | Transformation       | Required |
| ----------------- | ------------------------ | -------------------- | -------- |
| `id`              | Stored as correlation ID | -                    | No       |
| `name`            | `name`                   | Direct mapping       | Yes      |
| `email_1`         | `primaryContact.email1`  | Email validation     | No       |
| `neon_account_id` | `accountId`              | Correlation tracking | No       |

### Transaction/Donation Mapping

#### WeGive Transaction to Neon Donation

| WeGive Field      | Neon Field               | Transformation              | Required |
| ----------------- | ------------------------ | --------------------------- | -------- |
| `id`              | Stored as correlation ID | -                           | No       |
| `amount`          | `amount`                 | Cents to dollars conversion | Yes      |
| `created_at`      | `date`                   | Date formatting             | Yes      |
| `owner` (donor)   | `accountId`              | Account reference           | Yes      |
| `campaign`        | `campaign.id`            | Campaign reference          | No       |
| `anonymous`       | `anonymousType`          | Boolean mapping             | No       |
| `cover_fees`      | `donorCoveredFee`        | Fee calculation             | No       |
| `tribute_name`    | `tribute.name`           | Direct mapping              | No       |
| `neon_id`         | `id`                     | Donation correlation        | No       |
| `neon_payment_id` | `payments[0].id`         | Payment reference           | No       |

#### Payment Method Mapping

| WeGive Source Type | Neon Tender Type    | Neon Code | Description                |
| ------------------ | ------------------- | --------- | -------------------------- |
| `card`             | Credit Card Offline | 2         | Credit/debit card payments |
| `bank`             | Check               | 3         | ACH and bank transfers     |
| `donor`            | Check               | 3         | Donor-funded payments      |
| `cash`             | Cash                | 1         | Cash donations             |
| `check`            | Check               | 3         | Physical check payments    |
| `other`            | Other               | 10        | Other payment methods      |

#### Card Type Mapping

| WeGive Card Type | Neon Card Code | Description      |
| ---------------- | -------------- | ---------------- |
| `visa`           | V              | Visa cards       |
| `mastercard`     | M              | MasterCard       |
| `amex`           | A              | American Express |
| `discover`       | D              | Discover cards   |

### Campaign Mapping

#### WeGive Campaign to Neon Campaign

| WeGive Field                   | Neon Field                           | Transformation       | Required |
| ------------------------------ | ------------------------------------ | -------------------- | -------- |
| `id`                           | Stored as correlation ID             | -                    | No       |
| `name`                         | `name`                               | Direct mapping       | Yes      |
| `goal`                         | `goal`                               | Direct mapping       | No       |
| `start_date`                   | `startDate`                          | Date formatting      | No       |
| `expiration`                   | `endDate`                            | Date formatting      | No       |
| `total_donated`                | `statistics.donationAmount`          | Import only          | No       |
| `number_of_donations`          | `statistics.donationCount`           | Import only          | No       |
| `total_registration_collected` | `statistics.eventRegistrationAmount` | Import only          | No       |
| `number_of_registrations`      | `statistics.eventRegistrationCount`  | Import only          | No       |
| `neon_id`                      | `id`                                 | Campaign correlation | No       |

### Address Mapping

#### WeGive Address to Neon Address

| WeGive Field | Neon Field           | Transformation       | Required |
| ------------ | -------------------- | -------------------- | -------- |
| `address_1`  | `addressLine1`       | Direct mapping       | Yes      |
| `address_2`  | `addressLine2`       | Direct mapping       | No       |
| `city`       | `city`               | Direct mapping       | Yes      |
| `state`      | `stateProvince.code` | State code mapping   | No       |
| `zip`        | `zipCode`            | Direct mapping       | No       |
| `country`    | `country.code`       | Country code mapping | No       |
| `primary`    | `isPrimaryAddress`   | Boolean mapping      | No       |

## Custom Field Mapping System

### JSONPath Integration

The integration supports JSONPath expressions for complex field mapping:

#### Example Mappings

```json theme={null}
{
  "integration_path": "primaryContact.addresses[0].addressLine1",
  "wegive_path": "mailingAddress.address_1",
  "crm": "NEON",
  "integration": "ACCOUNT"
}
```

#### Supported Objects

* **ACCOUNT** (1): Donor/account mappings
* **DONATION** (2): Transaction/donation mappings
* **CAMPAIGN** (3): Campaign mappings
* **RECURRING\_DONATION** (4): Scheduled donation mappings
* **ADDRESS** (5): Address mappings

### Mapping Levels

#### Directional Control

* **Bidirectional**: Used for both import and export operations
* **Import**: Only used when importing data from Neon CRM (`level != 'export'`)
* **Export**: Only used when exporting data to Neon CRM (`level = 'export'`)

#### Custom Field Types

* **Standard Fields**: Built-in fields in both platforms
* **Custom Fields**: Organization-specific fields requiring configuration
* **Literal Values**: Static values assigned during synchronization
* **Computed Fields**: Fields calculated or transformed during sync

## Data Synchronization Rules

### Correlation ID Management

**Primary Correlation:**

* `neon_account_id` field tracks Neon account ID
* `neon_id` field tracks Neon contact ID for individuals
* `neon_payment_id` field tracks Neon payment ID for transactions
* Multiple correlation fields for complete reference tracking

### Matching Logic

1. **Exact ID Match**: Use correlation IDs when available
2. **Email Matching**: For accounts without correlation IDs
3. **Name + Organization**: Fallback for company accounts
4. **Create New**: When no match found

### Sync Direction Rules

#### Push Operations (WeGive → Neon CRM)

* **New Records**: Create new Neon CRM records
* **Existing Records**: Update based on correlation ID
* **Data Precedence**: WeGive data overwrites Neon CRM data
* **Required Fields**: Ensure all Neon CRM required fields are populated

#### Pull Operations (Neon CRM → WeGive)

* **New Records**: Create new WeGive records
* **Existing Records**: Update based on correlation ID
* **Data Precedence**: Neon CRM data overwrites WeGive data
* **Field Mapping**: Transform Neon CRM format to WeGive format

### Conflict Resolution

**Duplicate Prevention:**

* Email address uniqueness for individual accounts
* Organization name uniqueness for company accounts
* Account correlation tracking for accurate matching

**Update Strategy:**

* **Last Modified Wins**: Most recent update takes precedence
* **Field-Level Merging**: Specific field update rules
* **Manual Review**: Flag conflicts for administrative review

## API Endpoint Reference

### WeGive API Endpoints

#### Donor Management

* `GET /donors` - List all donors
* `GET /donors/{donor}` - Get specific donor
* `POST /donors` - Create new donor
* `PUT /donors/{donor}` - Update existing donor

#### Transaction Management

* `GET /transactions` - List all transactions
* `GET /transactions/{transaction}` - Get specific transaction
* `POST /transactions` - Create new transaction

#### Campaign Management

* `GET /campaigns` - List all campaigns
* `GET /campaigns/{campaign}` - Get specific campaign
* `POST /campaigns` - Create new campaign

#### Scheduled Donation Management

* `GET /scheduled-donations` - List all scheduled donations
* `GET /scheduled-donations/{id}` - Get specific scheduled donation

### Neon CRM API Endpoints

#### Account Management

* `GET /accounts` - List all accounts
* `GET /accounts/{id}` - Get specific account
* `POST /accounts` - Create new account
* `PUT /accounts/{id}` - Update existing account
* `POST /accounts/search` - Search accounts with criteria

#### Donation Management

* `GET /donations` - List all donations
* `GET /donations/{id}` - Get specific donation
* `POST /donations` - Create new donation
* `PUT /donations/{id}` - Update existing donation
* `POST /donations/search` - Search donations with criteria

#### Campaign Management

* `GET /campaigns` - List all campaigns
* `GET /campaigns/{id}` - Get specific campaign
* `POST /campaigns` - Create new campaign
* `PUT /campaigns/{id}` - Update existing campaign

#### Recurring Donation Management

* `GET /recurring` - List all recurring donations
* `POST /recurring` - Create new recurring donation
* `PUT /recurring/{id}` - Update recurring donation

#### Address Management

* `GET /addresses` - List all addresses
* `POST /addresses` - Create new address
* `PUT /addresses/{id}` - Update existing address

#### Webhook Management

* `GET /webhooks` - List configured webhooks
* `POST /webhooks` - Create new webhook
* `DELETE /webhooks/{id}` - Remove webhook

## Integration Notes

### Data Validation

**Required Field Validation:**

* Neon CRM requires at least first name OR last name for individuals
* Company accounts require organization name
* Donations require amount, date, and account reference
* Campaigns require name and status

**Format Requirements:**

* Email addresses: Must be valid email format
* Phone numbers: Flexible formatting, normalized during sync
* Dates: ISO 8601 format for API calls
* Amounts: Decimal format with proper currency handling

### Performance Considerations

**Batch Processing:**

* Transaction batching for efficiency
* Account search with pagination
* Rate limiting respectful API usage
* Incremental sync based on last modified dates

**Error Handling:**

* Comprehensive error logging and recovery
* Automatic retry logic for failed operations
* Data validation before sync operations
* Manual intervention tools for complex issues

## Related Documentation

* [Account Mapping](./account)
* [Donation Mapping](./donation)
* [Campaign Mapping](./campaign)
* [Recurring Donation Mapping](./recurring-donation)
* [Address Mapping](./address)

## Future Enhancements

Features under development:

* **Enhanced Custom Fields**: Extended custom field mapping capabilities
* **Advanced Relationships**: Extended donor relationship tracking
* **Event Integration**: Event registration and participation data
* **Communication Preferences**: Enhanced communication management
* **Bulk Operations**: Improved bulk import/export capabilities

This comprehensive data mapping ensures accurate bidirectional synchronization between WeGive and Neon CRM while supporting flexible customization for each organization's unique requirements.