Virtuous Field Mapping Reference
Last updated: April 1, 2026
This article documents how data fields map between WeGive and Virtuous. All field mappings are set automatically when the integration is enabled. They are not customizable.
Use this as a reference when reviewing your data or troubleshooting sync issues to understand which WeGive field corresponds to which Virtuous field.
Contact / Donor Fields
WeGive Field | Virtuous Field | Notes |
Name | name | |
First Name | contactIndividuals.firstName | Maps to the contact individual record |
Last Name | contactIndividuals.lastName | Maps to the contact individual record |
Type (individual/company) | contactType | "company" maps to "Organization", all others map to "Household" |
Created At | createDateTimeUtc |
Email Fields
WeGive Field | Virtuous Field | Notes |
email_1 | Primary Email contact method | Set as isPrimary in Virtuous |
email_2 | Secondary Email contact method | Set as non-primary in Virtuous |
Emails sync as contact methods in Virtuous with the type "Email". Both are set to opted-in by default.
Phone Fields
WeGive Field | Virtuous Field | Notes |
Mobile Phone | Primary Phone contact method | Set as isPrimary in Virtuous |
Other Phone | Secondary Phone contact method | Set as non-primary in Virtuous |
Phones sync as contact methods in Virtuous with the type "Phone". Both are set to opted-in by default.
Address Fields
WeGive syncs both mailing and billing addresses to Virtuous. Mailing addresses are set as primary in Virtuous.
WeGive Field | Virtuous Field | Notes |
address_1 | address1 | |
address_2 | address2 | |
City | city | |
State | state | |
Zip | postal | |
Country | country |
Mailing addresses sync with the label "mailing" and are set as primary. Billing addresses sync with the label "billing" and are set as non-primary.
Transaction / Gift Fields
WeGive Field | Virtuous Field | Notes |
Amount | amount | |
Donor | contactId | Matched by Virtuous contact ID |
Designations | giftDesignations.projectId | Maps to the Virtuous project |
Campaign | segmentId | Maps to the Virtuous segment |
Transaction ID | wg_id (custom field) | Required custom field for tracking synced gifts |
The wg_id custom field in Virtuous stores the WeGive transaction ID. This is how WeGive identifies which gifts have already been synced and prevents duplicates. See Prerequisites & Before You Begin for how to create this field.
Fund Allocations (Organizations with Multi-Designation Enabled)
For organizations that have multi-designation enabled, WeGive supports splitting a single gift across multiple designations via the allocation table. Each allocation row maps to a separate gift designation entry in Virtuous.
WeGive | Virtuous |
Designation (Fund) | Project ( |
Allocation Amount |
|
When a gift with multiple allocations syncs to Virtuous, WeGive sends a designations array on the gift record, one entry per allocation row. Each entry references the Virtuous Project that corresponds to the WeGive Designation and the amount designated.
Requirements: Each Designation must have a corresponding Virtuous Project ID configured. If a Designation is missing a Virtuous ID, WeGive will automatically push it to Virtuous before syncing the allocation.
Sync behavior: WeGive is the source of truth for allocations. When a gift is updated, WeGive replaces the entire designations array in Virtuous rather than merging changes. Likewise, when Virtuous designations are pulled back into WeGive, any WeGive allocations not present in the Virtuous record will be removed to keep both systems in sync.
Recurring Donation Fields
WeGive Field | Virtuous Field | Notes |
Amount | amount | |
Frequency | frequency | Only supported frequencies will sync |
Next Donation Date | nextExpectedPaymentDate | |
Designation | giftDesignations.projectId | |
Campaign | segmentId |
Supported frequencies: Monthly, Biweekly, Quarterly, Yearly, Daily, First and 15th. Weekly and Semi-annually are not supported and will not sync.
Designation / Project Fields
WeGive Field | Virtuous Field | Notes |
Designation Name | onlineDisplayName | |
Created At | createDateTimeUtc |
Campaign / Segment Fields
WeGive Field | Virtuous Field | Notes |
Campaign Name | segment name |
Company / Organization Contacts
Virtuous requires every organization contact to have at least one contact individual (a person associated with the company). When a company donor syncs from WeGive to Virtuous, the integration creates a contact individual using the available contact person details.
If the company donor in WeGive does not have contact person details, Virtuous will create a placeholder individual with "FNU" (First Name Unknown) and "LNU" (Last Name Unknown). To avoid this, make sure your company donors in WeGive have a contact person's first and last name before the integration syncs them.
The primary contact individual's email and phone become the organization's primary contact methods in Virtuous.
API Version Differences
The field mappings are the same across both API versions. The only difference is how contacts are identified between the two systems.
Version | WeGive ID Field | Virtuous ID Field |
v1 | virtuous_id | contact id |
v2 | virtuous_contact_id + virtuous_contact_individual_id | contact id + contact individual id |
V2 provides more precise matching by tracking both the contact and the individual within that contact. This is especially useful for organizations that manage multiple people within a single household or company record.