> ## Documentation Index
> Fetch the complete documentation index at: https://docs.wegive.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Neon CRM Setup Requirements

> Prerequisites and requirements for setting up the WeGive Neon CRM integration

# Setup Requirements

Before configuring the WeGive Neon CRM integration, gather the following.

## Neon CRM Requirements

### Account Prerequisites

* **Active Neon CRM Account** with API access enabled
* **Organization ID and API Key**: WeGive authenticates with HTTP Basic auth using your Neon **Organization ID** as the username and your **API Key** as the password (`base64(organization_id:api_key)`) — both are required, not just an API key alone
* **Administrative access** in Neon CRM to generate the API key

### Technical Requirements

* **API Version**: Neon CRM API v2 (`https://api.neoncrm.com/v2/` production, `https://trial.neoncrm.com/v2/` staging/trial — WeGive selects automatically based on its own environment, not something you configure)
* **Webhook support** — only required if you intend to enable two-way sync (see below); one-way sync doesn't need it

<Note>
  There is no "advanced API access tier" distinction relevant to this integration — the integration calls a fixed, small set of Neon v2 endpoints (`/accounts`, `/accounts/search`, `/donations`, `/donations/search`, `/campaigns`, `/recurring`, `/addresses`, `/webhooks`). Standard API access covering these is sufficient.
</Note>

## WeGive Platform Requirements

* **Active WeGive organization account** with integration features enabled
* **Organization administrator** permissions to configure the integration and its API credentials via Settings > Integrations

## Authentication Setup

### Neon CRM API Credentials

1. Log into your Neon CRM account
2. Generate an API key with account, donation, campaign, and (if you plan to enable two-way sync) webhook management permissions
3. Note your **Organization ID** as well as the API key — both are needed

### WeGive Configuration

Enter the Organization ID and API key into the WeGive integration settings. There is no separate "WeGive integration token" step for this integration beyond the Neon credentials themselves.

## Two-Way Sync and Webhooks

<Warning>
  Webhooks are only set up automatically when **both** `enabled` and `two_way_sync` are true, and only for **donor create/update** and **donation create/update** — there are no webhooks for recurring donations, campaigns, or addresses. If you only need WeGive → Neon push (or Neon → WeGive daily pull), you don't need webhook permissions on the API key at all.
</Warning>

Webhooks are created/removed automatically by WeGive when the integration is enabled/disabled with two-way sync on — there's no manual webhook configuration step for the admin to perform.

## Data Preparation

### Donor Data Quality

* **Email addresses**: required on pull — a Neon account row with a missing/blank email is silently skipped during import. There's no equivalent hard requirement on push.
* **Name fields**: individual donors need first/last name; company donors use the account's company name

### Campaign Structure

* Existing Neon campaigns pull into WeGive as name + `neon_id` only — statistics (goal, totals) are read from Neon on subsequent pulls, not computed by WeGive
* WeGive campaigns pushed to Neon carry name, start/end dates, goal, and status (active/inactive based on WeGive's own soft-delete state) — nothing more elaborate

### Payment Methods

<Warning>
  Only 3 WeGive payment source types map to Neon: `card` → Credit Card Offline, `bank`/`donor` → Check. Anything else defaults to Check as well. There's no distinct mapping for cash, stock/securities, in-kind, or other Neon tender types this integration doesn't send. Plan Neon-side reporting expectations accordingly — see [Integration Nuances](/external/onboarding/neon/integration-nuances) for detail.
</Warning>

## Custom Field Mapping Preparation

<Warning>
  Custom field mapping for this integration is real (via `NeonMappingRule` records with JSONPath-based `wegive_path`/`integration_path`), but it currently has a known limitation: mapping rules marked "literal" (meant to send a fixed value rather than look one up) don't work as literals yet — every mapping is resolved as a JSONPath lookup regardless of the flag. This is a known issue, in review as of this writing. Plan custom field mappings around live WeGive field paths, not fixed literal values, until that ships.
</Warning>

There is no bidirectional custom-field-array sync (`accountCustomFields`/`donationCustomFields` in Neon's own API shape) implemented — only the flat field mappings described in [Data Mapping](/external/onboarding/neon/data-mapping/overview).

## Environment Configuration

Use a WeGive staging environment and a Neon trial account to test configuration changes before enabling on a production organization — there's no WeGive-side sandbox/dry-run mode for this integration; any push while `enabled` is a real push against whichever Neon environment your credentials point to.

## Pre-Integration Checklist

* [ ] Neon Organization ID and API key obtained
* [ ] API key permissions cover account/donation/campaign, plus webhooks if enabling two-way sync
* [ ] Donor emails in Neon are populated (required for pull)
* [ ] Understand the payment-method mapping limitation above
* [ ] Understand the literal-mapping-rule limitation above (known issue, in review)

## Common Setup Issues

### Authentication Problems

* **Invalid credentials**: verify both the Organization ID and API key are correct — a wrong Organization ID alone will fail Basic auth even with a valid key
* **Permission errors**: if you enabled two-way sync and webhooks aren't appearing in Neon, check the API key has webhook management permission

### Data Quality Issues

* **Missing donor emails**: a Neon account without an email is silently skipped on pull, not flagged as an error
* **Payment method mismatch**: don't be surprised that non-card/bank payment methods show as Check in Neon — see the warning above

## Support Resources

* [Neon CRM API Documentation](https://developer.neoncrm.com/)
* [Integration Configuration Guide](/external/onboarding/neon/configuration-options)
* [Data Mapping Reference](/external/onboarding/neon/data-mapping/overview)
* [Integration Nuances](/external/onboarding/neon/integration-nuances)
* WeGive Support: [support@wegive.com](mailto:support@wegive.com)

## Next Steps

1. Proceed to [Configuration Options](/external/onboarding/neon/configuration-options)
2. Review [Data Mapping Documentation](/external/onboarding/neon/data-mapping/overview)
3. Understand [Integration Nuances](/external/onboarding/neon/integration-nuances)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.