DonorAtlas for Virtuous — User Manual
Last Updated: September 2026
Everything a team member does with the Virtuous integration day to day, page by page. For setup from scratch see the Quick Start Guide; for how it works underneath see the Technical Documentation.
1. Where Things Live
The integration lives on the Integrations page of DonorAtlas (Dashboard → Integrations). The Virtuous card there is the front door: it shows whether you are connected and links to Configure, Bulk sync, Users & connections and Auto-resync. In Virtuous itself there is nothing to open: DonorAtlas data appears in the custom fields, Custom Collections and (optionally) contact rows your admin mapped, usually on a DonorAtlas tab on the Contact record.
Who sees what:
| You are | You see |
|---|---|
| Any team member | The Virtuous card with your own connection and the Bulk sync and Auto-resync pages; the Sync button on donor profiles |
| Admin or Configure Only | All of the above, plus Set up, Configure and Users & connections |
2. Connecting Yourself
Your team connects to Virtuous once, with an API key an admin enters. After that, each member connects themselves with one click and no Virtuous sign-in.
- On the Integrations page, the Virtuous card says “You haven't connected your Virtuous account yet. Your team's API key is already set up, so connecting takes one click.” Click Connect your account.
- The card then reads “You're connected since Sep 18, 2026”.
3. Syncing One Donor from DonorAtlas
Open any donor's profile. The Virtuous button sits with the other actions.
- Sync (not yet synced): click it to open a picker, already searching Virtuous for the donor's name. Search by name, or paste a Contact's id or its Virtuous link. Pick the Contact this donor already is and click Link selected: DonorAtlas links it and writes the donor's data. Contacts already synced to another donor are greyed out. Or click Match automatically, and DonorAtlas checks Virtuous itself, by email or phone alongside the name: a confident match is linked and written, and no match creates a new Contact. A Contact that shares only the name is linked if the name is uncommon and no other Contact has it; otherwise DonorAtlas creates a new Contact and the job names the look-alike, so you can merge the two if they're the same person. An address cannot confirm a match here, because Virtuous does not return addresses in this check. To link a particular Contact instead, choose it in the picker.
- Syncing…: DonorAtlas is working. A second click does nothing until it finishes.
- View: the Contact is synced. Click to open it in Virtuous in a new tab.
- The small arrow beside View opens two more actions for this one Contact:Re-sync rewrites every mapped field from the latest research (needs the Sync permission), and Unsync… removes what DonorAtlas wrote and drops the link, after a confirmation (needs the Unsync permission). A photo DonorAtlas added stays, because Virtuous can't remove one (). Both run as jobs; the button reads Re-syncing… or Unsyncing… until they finish.
- Greyed out with “Your team hasn't allowed you to sync through Virtuous”: ask a team admin for the Sync permission ().
Errors show in a small red box under the button.
4. Sending a Whole DonorAtlas List
On Donor Lists, open a list's menu and choose Send to Virtuous. Each donor is checked against Virtuous first, so donors already there are linked rather than duplicated. The list runs as one job with a sub-job per donor; follow it in the jobs panel. You need the Bulk and Sync permissions.
5. Bulk Sync: Tags and Organization Groups
Integrations → Virtuous → Bulk sync (any team member; what you can run there depends on your Bulk, Sync and Unsync permissions). The table lists every Tag and Organization Group in your Virtuous organization with Members, Synced and Last synced columns. Each row's actions are in its menu, the three dots at the end of the row.
- Sync matches and writes every member that is not synced yet. One import credit is spent per newly matched Contact.
- Re-sync rewrites every synced member with the latest DonorAtlas data. Free.
- Unsync… removes what DonorAtlas wrote from every synced member, except any photo it added (team Admins with Bulk and Unsync only). A confirmation names the Tag or group. Free.
- Count now counts that Tag or group now; the Refresh button at the top re-reads the whole list. DonorAtlas counts the first 20 rows automatically and leaves larger tables to you.
- A running row turns blue and reads “Syncing 12 of 340…”. Progress also appears in the jobs panel.
Things you may see:
- “Every record in this Tag is already synced.” The Sync button is disabled because there is nothing new to do.
- “Your team is out of imports…” Buy more import credits, then try again.
- “That operation is already running for this list.” A run is in flight; wait for it to finish.
- “Bulk syncing is turned off for your account.” Ask a team admin for the Bulk and Sync permissions.
6. Configure: What DonorAtlas Writes
Integrations → Virtuous → Configure (Admin or Configure Only). This is where your team decides what lands where.
Single values
One row per DonorAtlas field (net worth range, giving capacity, gift figures, age, sex, religion, spouse, profile link, last synced date, political figures). Each dropdown offers the custom fields in your organization whose type can hold that value, or Not written. A field mapped to something Virtuous no longer has is flagged in amber and written nowhere until you re-map it. Each of your fields holds one DonorAtlas value, so a field another row already uses is shown with its name and can't be picked again.
Repeating data
Employment, Education, Board Affiliations, Private Foundations, Public Donations and Social Media & Bio Websites are written as rows in a Custom Collection, one row per entry. Pick a collection, then choose which column takes each part (for Employment: Employer, Job title, Start date, End date, DonorAtlas page, Company website, Source). Three of those are links and easy to confuse: DonorAtlas page is the company's page in DonorAtlas, Company website is its own site, and Source is where DonorAtlas found the job. A part left on Not written is simply skipped.
Verified contact information
One checkbox covering Mailing Address, Verified Personal Email and Verified Mobile Phone. When on, DonorAtlas adds its own contact method and address rows to the Contact and removes exactly those rows on unsync; your team's own rows are never touched. This is the one place DonorAtlas writes to records your team also edits by hand, which is why it is off by default.
Political data
If your team has turned political data off for Virtuous, the political rows are not offered here and any earlier mapping is kept dormant. An admin changes that under Political Data on the profile page.
Click Save configuration. “Saved. DonorAtlas will write these fields from now on.” confirms it. Changing the mapping does not rewrite already-synced Contacts by itself; run a Re-sync (or wait for the nightly refresh) to apply it.
Values your team typed are safe. DonorAtlas fills a mapped field when it is empty and keeps updating values it wrote itself. If someone changes a value in Virtuous, DonorAtlas leaves it alone from then on and the job says which fields it left. If your mapped fields are for DonorAtlas only, tick Let DonorAtlas overwrite values already in these fields under “What else a sync does”.
The donor's spouse. Tick Link the donor's spouse to bring the spouse along: if DonorAtlas has a profile for them, they're found or created in Virtuous as a contact of their own, synced in full, and linked to the donor as their spouse, with the relationship noted “Added by DonorAtlas”. The spouse is added the first time a donor is synced, in a bulk sync as well as one at a time (a bulk sync adds spouses once it has matched every record, so a spouse who is in the same Tag or group is linked, not added twice), and doesn't use an import, but is a new contact in Virtuous and appears in your jobs under their own name. Re-syncs, including the nightly one, only link a spouse already in Virtuous. Other relatives aren't added. A spouse Virtuous already keeps in the donor's household is left there rather than linked. Unsyncing a donor removes the link DonorAtlas made and never one your team added.
The donor's photo. Tick Add the donor's photo to give the person in Virtuous the photo from their DonorAtlas profile. Virtuous keeps its own copy, so the photo doesn't expire. It follows the same rule as your mapped fields: a person who already has a photo your team added keeps it, unless you've turned on overwriting. A photo DonorAtlas added is replaced only when the DonorAtlas photo changes. Virtuous has no way to remove a photo once it's added, so unsyncing leaves it in place and the job says so; remove it in Virtuous if you don't want it.
7. Replacing the API Key
If Virtuous stops accepting the key (it was deactivated, or its permission group changed), everyone connected to Virtuous sees a pop-up: “Your team's Virtuous API key is no longer accepted, so syncing and sending donors to Virtuous will fail until it is updated.” Admins and Configure Only users get an Update API key button that lands on the Configure page with the key box focused.
Paste the new key and click Save key. Only the key changes: your field mapping stays exactly as it is and every member keeps their connection. The new key must belong to the same Virtuous organization.
8. Users & Connections and Permissions
Integrations → Users & connections (Admin or Configure Only) lists everyone connected to Virtuous and what each may do:
| Permission | Allows |
|---|---|
| Sync | Sync and re-sync individual records, send donors from DonorAtlas, match Contacts by hand |
| Unsync | Remove DonorAtlas data from individual records |
| Bulk | Run Tag- and group-level operations (with Sync for bulk sync and re-sync, with Unsync for bulk unsync) |
Every connected member can see synced profiles whatever their permissions; a member with none of the three is view-only. Members have full access until you restrict them. Remove connection disconnects a member and clears their permissions; if they reconnect they are view-only until you grant more.
The Inviting someone to connect card holds paste-ready instructions, with a Copy button, to send a new team member.
9. Auto-resync
Integrations → Virtuous → Auto-resync. Every night DonorAtlas finds synced Contacts whose data is due for a refresh and re-syncs them the same way a manual Re-sync does: DonorAtlas data on the Contact is replaced with the newest research, and your own Virtuous fields are never touched. The page shows the cadence (default every 7 days) and the next scheduled run; Edit settings changes the cadence. A team with a bulk run in progress is skipped that night.
10. Disconnecting
The Uninstall card on Configure (Admin or Configure Only) removes DonorAtlas data from every Contact the team has synced, then disconnects Virtuous and deletes the team's key and every member's connection. It runs as a job; a team with many synced Contacts can leave it running and follow it in the jobs panel. The Contacts themselves and your custom fields and collections stay in Virtuous. Reconnecting later means entering a key and mapping the fields again.
11. Credits
An import credit is spent once per Contact, when it is first matched in a bulk sync. Sending a donor from DonorAtlas, re-syncing, unsyncing and the nightly refresh spend nothing. A Contact that could not be matched is remembered, so a later bulk sync does not pay for it again.
12. Frequently Asked Questions
Where do I find my Virtuous API key?
A Virtuous administrator creates it at Settings → All Settings → Connectivity → API Keys. Choose the Admin permission group, or a custom group with Contact Read and Write.
Why is a field missing from the dropdown?
Only fields whose type can hold the value are offered. Figures need a Decimal field, the profile link a Link field, dates a Date field, text a Text or Paragraph field. Field types cannot be changed after creation in Virtuous; create a new field.
Why does a bulk sync take so long?
Virtuous gives each organization an hourly request budget shared by all its integrations. DonorAtlas paces itself to it and waits out any throttling rather than dropping records.
Does DonorAtlas change gifts, addresses or names?
No. It writes only to the custom fields and collections you mapped and, if you opted in, to contact rows it created itself.
Can two Individuals in one household be synced separately?
Not in this version. DonorAtlas matches on the Contact's primary Individual and writes to the Contact.