> ## 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 Address Mapping

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

# Address Object Mapping

This document details the comprehensive mapping between Neon CRM address objects and WeGive donor address records, including contact information, location data, and synchronization behavior.

## Object Overview

### Neon Address Object

Represents contact addresses in Neon CRM including mailing addresses, phone numbers, and contact preferences.

### WeGive Address Object

Represents donor addresses in WeGive including mailing and billing addresses with associated contact information.

## Core Address Mapping

### WeGive Address to Neon Address

#### Location Information

| WeGive Field | Neon Field           | Data Type | Direction     | Required | Transformation       |
| ------------ | -------------------- | --------- | ------------- | -------- | -------------------- |
| `address_1`  | `addressLine1`       | String    | Bidirectional | Yes      | Direct mapping       |
| `address_2`  | `addressLine2`       | String    | Bidirectional | No       | Direct mapping       |
| `city`       | `city`               | String    | Bidirectional | Yes      | Direct mapping       |
| `state`      | `stateProvince.code` | String    | Bidirectional | No       | State code mapping   |
| `zip`        | `zipCode`            | String    | Bidirectional | No       | Direct mapping       |
| `country`    | `country.code`       | String    | Bidirectional | No       | Country code mapping |

#### Address Classification

| WeGive Field | Neon Field         | Data Type | Direction     | Required | Transformation              |
| ------------ | ------------------ | --------- | ------------- | -------- | --------------------------- |
| `type`       | Address context    | String    | Export        | No       | Mailing/Billing designation |
| `primary`    | `isPrimaryAddress` | Boolean   | Bidirectional | No       | Primary designation         |

#### Contact Information

| WeGive Field         | Neon Field | Data Type | Direction     | Required | Transformation |
| -------------------- | ---------- | --------- | ------------- | -------- | -------------- |
| `donor.mobile_phone` | `phone3`   | Phone     | Bidirectional | No       | Mobile phone   |
| `donor.home_phone`   | `phone1`   | Phone     | Bidirectional | No       | Home phone     |
| `donor.office_phone` | `phone2`   | Phone     | Bidirectional | No       | Work phone     |
| `donor.fax`          | `fax`      | Phone     | Bidirectional | No       | Fax number     |

#### Phone Type Mapping

| WeGive Phone Type | Neon Phone Type | Neon Field   | Description       |
| ----------------- | --------------- | ------------ | ----------------- |
| `mobile_phone`    | Mobile          | `phone3Type` | Mobile/cell phone |
| `home_phone`      | Home            | `phone1Type` | Home phone        |
| `office_phone`    | Work            | `phone2Type` | Work/office phone |
| `fax`             | Home            | `faxType`    | Fax number        |

#### Integration Fields

| WeGive Field     | Neon Field  | Data Type | Direction   | Required | Transformation    |
| ---------------- | ----------- | --------- | ----------- | -------- | ----------------- |
| `neon_id`        | `id`        | Integer   | Correlation | No       | Address reference |
| `addressable_id` | `accountId` | Integer   | Export      | Yes      | Donor reference   |

## Address Types and Context

### Address Type Handling

WeGive supports multiple address types that are integrated with Neon CRM:

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

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

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

Neon CRM uses structured state/province objects:

#### State Object Structure

```json theme={null}
{
  "stateProvince": {
    "code": "IL",
    "name": "Illinois", 
    "status": "ACTIVE"
  }
}
```

#### Common State Mappings

| WeGive Code | Neon Code | Full Name  |
| ----------- | --------- | ---------- |
| `IL`        | `IL`      | Illinois   |
| `CA`        | `CA`      | California |
| `NY`        | `NY`      | New York   |
| `TX`        | `TX`      | Texas      |

### Country Code Mapping

Neon CRM uses structured country objects:

#### Country Object Structure

```json theme={null}
{
  "country": {
    "id": "1",
    "name": "United States",
    "status": "ACTIVE"
  }
}
```

#### Common Country Mappings

| WeGive Code | Neon ID | Full Name      |
| ----------- | ------- | -------------- |
| `US`        | `1`     | United States  |
| `CA`        | `2`     | Canada         |
| `UK`        | `3`     | United Kingdom |

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

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

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

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

Addresses are integrated within the account structure in Neon CRM:

#### Within Individual Account

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

Addresses can also be managed separately:

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

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

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

### Getting Account Addresses

```http theme={null}
GET /v2/accounts/67890/addresses
```

Response:

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

This comprehensive address mapping ensures accurate contact information synchronization between WeGive and Neon CRM while maintaining data quality and geographic accuracy.