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

# Constituent Mapping

> Field-level mapping between WeGive donors and Blackbaud Raiser's Edge NXT constituents

# Constituent Data Mapping

This page details the field-level mapping between WeGive donor/company records and Blackbaud Raiser's Edge NXT constituent records.

## Object Overview

### WeGive Donor Object

* **Purpose**: Represents individual donors and organizations in the WeGive platform
* **Types**: `individual` and `company`
* **Unique Identifier**: WeGive donor ID, correlated to Blackbaud via the `raisers_edge_id` column

### Blackbaud Constituent Object

* **Purpose**: Represents individuals and organizations in Raiser's Edge NXT
* **API Endpoint**: `constituent/v1/constituents`
* **Unique Identifier**: Blackbaud constituent ID

<Note>
  Household constituents aren't part of this integration — see [Configuration Options](/external/onboarding/blackbaud/configuration-options).
</Note>

## Individual Constituent Mapping

| WeGive Field | Blackbaud Field | Direction | Notes |
| - | - | - | - |
| `raisers_edge_id` | Constituent ID | Both | The correlation key — constituents are matched exclusively by this ID, no name/email/phone fallback |
| `first_name` | `first` | Both | Defaults to "FNU" on push if empty |
| `last_name` | `last` | Both | Defaults to "LNU" on push if empty |
| `middle_name` | `middle` | Both | |
| `gender` | `gender` | Both | |
| `birthdate` | `birthdate` (day/month/year object) | Both | |

### Email

WeGive donors have three email fields (`email_1`, `email_2`, `email_3`) and a `preferred_email` selector (`personal`/`work`/`alternate`). On push, exactly one email is sent — the one matching `preferred_email` (defaulting to `email_1`/"Email Primary" if unset). On pull, only one email comes back from Blackbaud and is written to `email_1`, with `preferred_email` set based on the returned email's type (`work` if the type contains "Business", otherwise `personal`).

### Phone

Similarly, WeGive has `mobile_phone`, `home_phone`, and `office_phone`. On push, one phone is sent, prioritized mobile → home → office. On pull, one phone comes back and is routed to the matching field based on its Blackbaud type (Cell/Mobile → `mobile_phone`, Business/Work → `office_phone`, otherwise → `home_phone`).

<Warning>
  Only US/Canada-format phone numbers (10 digits, or 11 digits starting with 1) are pushed to Blackbaud — an international-format number is skipped with a logged warning, not sent.
</Warning>

### Address

WeGive's mailing address is pushed as a single Blackbaud address object (type `Home` for individuals, `Business` for companies). State values in the form `"SK - Saskatchewan"` are parsed down to just the code (`SK`) before sending.

## Organization (Company) Constituent Mapping

| WeGive Field | Blackbaud Field | Direction | Notes |
| - | - | - | - |
| `raisers_edge_id` | Constituent ID | Both | Same ID-only matching as individuals |
| `name` | `name` | Both | Required — defaults to "Unknown Organization" if empty on push; truncated to 60 characters (Raiser's Edge's limit) |

Companies use the same single email/phone/address handling described above, with company-specific defaults (`office_phone` → "Phone Business", address type `Business`).

<Note>
  Fields like organization type, tax ID, website, industry, and SIC/NAICS codes aren't part of this mapping — there's no corresponding code path for them.
</Note>

## What Isn't Mapped

The following aren't synced by this integration in either direction — there's no corresponding field mapping or transformation logic for them:

* **Custom fields, tags, or notes** — no Attribute Category / Constituent Code / Notes handling exists
* **Communication preferences** (email/SMS/mail opt-in) — no `do_not_email`/`do_not_call`/`do_not_mail` sync
* **Household relationships** — see [Configuration Options](/external/onboarding/blackbaud/configuration-options)
* **Job title, employer, or occupation**
* **Suffix, title (Mr./Mrs./Dr.), or nickname**

## Duplicate Handling

Because matching is strictly by `raisers_edge_id`, a constituent created directly in Blackbaud (outside this integration) has no way to be recognized as the same person on a later WeGive push — it will be created as a new constituent rather than matched or merged. A Redis-backed lock prevents the integration itself from creating duplicate constituents when two pushes for the same new donor race each other.

## Create vs. Update Payloads

* **Create** (no `raisers_edge_id` yet): sends the full compiled payload — name, email, phone, address, birthdate, gender.
* **Update** (`raisers_edge_id` already set): sends only email and phone, via `PATCH` — name, address, birthdate, and gender aren't re-sent on update.

## Error Handling

A failed constituent push raises an exception, which is logged to the integration's sync log and surfaces as a failed sync entry — there's no separate manual-review queue or automated conflict-resolution step beyond that.

## Getting Help

* **WeGive Support**: [support@wegive.com](mailto:support@wegive.com)
* **Blackbaud Sky API Constituent Docs**: [Sky API Constituent Documentation](https://developer.blackbaud.com/skyapi/docs/services/56b76470069a0509c8f1c5b3)


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