Technical Administration Guide

1. Product Overview

DonorAtlas for Virtuous writes DonorAtlas prospect research into Virtuous CRM+ Contact records and keeps it current. A DonorAtlas user chooses a Contact, a Tag, an Organization Group, or a DonorAtlas list; DonorAtlas identifies each person in its own database, and writes the research your team has chosen into custom fields and Custom Collections on the Contact, together with a link back to the full DonorAtlas profile. From then on, every nightly sweep refreshes what was written.

Virtuous has no add-in or panel framework for third parties, so there is no embedded DonorAtlas tile inside Virtuous. The integration is the written data plus the profile link. Everything in Virtuous that can read a custom field (queries, exports, automation workflows, the Contact page) can read DonorAtlas data.

What the Integration Never Touches

Gifts, pledges, recurring gifts, designations, campaigns, communications, segments, tasks, or a Contact's name, addresses, emails and phones unless your team explicitly opts in to writing verified contact information (Section 6). It never archives or merges a Contact.

2. Prerequisites & Roles

On the Virtuous side you need an administrator, because only administrators can create API keys and custom fields. On the DonorAtlas side, connecting and configuring the integration takes the Admin or Configure Only team role; any team member can then connect their own account and sync records within the permissions your admin grants (Section 8).

Before connecting, an administrator creates in Virtuous:

• A Custom Field Group on Contact for the DonorAtlas fields (Settings → Data Customization → Custom Fields and Collections). Turning on “show as a tab on the Contact record” gives your team a DonorAtlas tab on every Contact.
• One custom field per DonorAtlas value you want written, of a type that fits the value: Decimal for figures, Text (140 characters) or Paragraph for names and short text, Date for dates, Link for the profile URL.
• A Custom Collection on Contact for each kind of repeating data you want (employment history, education, board seats, private foundations, public donations), with one column per part of a row you want kept.
• An API key: Settings → All Settings → Connectivity → API Keys → New API Key, permission group Admin or a custom group with Contact Read and Write (and Delete, if you will opt into writing contact information, since removing what DonorAtlas added on unsync deletes a contact method or address).

3. Installation & Connection

There is nothing to install in Virtuous. Connection is a three-step handshake in DonorAtlas; the click-by-click version is the Quick Start Guide.

1. An Admin or Configure Only user opens Integrations → Virtuous → Set up and pastes the API key. DonorAtlas validates it against Virtuous (GET /api/Organization/Current), records the organization id and name, and links your DonorAtlas team to that Virtuous organization. One Virtuous organization links to one DonorAtlas team and vice versa; moving a link is a support action.
2. The same user opens Configure, sees the custom fields and collections DonorAtlas discovered in your organization, and maps each DonorAtlas field to one of them (Section 5).
3. Each other team member clicks Connect once, on the Integrations hub or on Users & connections. No Virtuous sign-in is involved; the click records that this person uses the integration, which is what per-user permissions and the “synced by” attribution hang on.

4. Authentication Architecture

One credential is involved: the organization's Virtuous API key, held once per DonorAtlas team in a secret of its own in AWS Secrets Manager (encrypted at rest with AWS KMS), and sent as a bearer token on every call. Virtuous keys are static and do not expire on a schedule; an administrator can deactivate one at any time.

• The key is scoped by the permission group your administrator chose. DonorAtlas cannot read what a group allows, so a key that can read but not write connects cleanly and fails on its first write; the failure names the permission.
• DonorAtlas never holds a Virtuous username, password, or session, and the integration makes no calls from a browser.
• If Virtuous rejects the key (deactivated, or the group changed), the next sync marks every member's connection as needing attention, the app shows a pop-up, and an Admin or Configure Only user replaces the key on the Configure page. The mapping and every member's connection survive a key replacement; the replacement key must belong to the same Virtuous organization.

5. Configuration

Configuration lives in DonorAtlas and is per team. The Configure page shows every DonorAtlas field the integration can write (Section 7) and, beside each, the custom fields of your organization whose type can hold it. Repeating fields show your Custom Collections instead, and, once a collection is chosen, one column picker per part of the row.

Four switches sit under the mapping, all off by default. Let DonorAtlas overwrite values already in these fields lets a sync write over a value your staff changed, in a mapped field or in the photo. Link the donor's spouse finds or creates the donor's spouse as a Contact of their own, syncs them in full, and links the two as spouses; a bulk sync holds each spouse back until it has matched every record in the run, then links those it found and sends the rest. Add the donor's photo uploads the DonorAtlas photo as the person's photo in Virtuous. Write verified contact information lets a sync add DonorAtlas's verified email and mobile phone as contact methods on the primary Individual and the mailing address as an address on the Contact; these are rows DonorAtlas creates, records, and removes again on unsync, and rows your staff added are never touched.

Saving validates the mapping against a fresh discovery: a field whose custom field or collection no longer exists in Virtuous is marked invalid with the reason, and the integration counts as configured only while at least one field has somewhere to land. Re-open the Configure page after changing custom fields in Virtuous.

6. Data Model

A Virtuous Contact is a household or organization; the people in it are Individuals, one of them primary. Gifts, notes, tags, addresses, custom fields and Custom Collections belong to the Contact; emails, phones, birth date and deceased belong to the Individual.

DonorAtlas treats the Contact as the synced record. Matching identity comes from the primary Individual (name, nickname, birth date) together with the Contact's primary address and the Individual's contact methods. Research is written to Contact-level custom fields and collections, so it is visible on the household. A second adult in a household is not synced separately in this version.

DonorAtlas keeps one linkage row per synced Contact: the Contact id, the matched DonorAtlas person, the match probability, when it was last written and by whom, and the ids of every row DonorAtlas created on the Contact (collection instances, contact methods, an address, the reference). That last set is what lets a resync replace exactly its own rows and an unsync remove exactly them.

With the photo setting on, a sync uploads the donor's DonorAtlas photo as the primary Individual's avatar (POST /api/ContactIndividual/{id}/Avatar). The linkage row records which DonorAtlas photo was sent and the address of the copy Virtuous stored, so a later sync replaces the avatar only while it is still DonorAtlas's and the photo has changed, and leaves an avatar your team uploaded alone unless overwriting is on. Virtuous offers no way to remove an avatar, so an unsync leaves it and says so on the job.

7. Data Dictionary

Every value comes from the same DonorAtlas profile the app shows. Political figures obey your team's political-data setting for Virtuous: when that setting is off for the CRM, political fields are written as empty on the next sync, which clears what an earlier sync wrote.

Scalar Fields (One Value, Written to a Custom Field)

Repeating Fields (Rows, Written to a Custom Collection)

Contact Information (Opt-in, Written to the Contact's Own Rows)

Verified Personal Email and Verified Mobile Phone become contact methods on the primary Individual; Mailing Address becomes an address on the Contact. Rows DonorAtlas adds are recorded and removed on unsync; rows your staff added are never touched.

8. Sync Operations

Every write to a Contact is the same shape: read the Contact, then one PUT that carries every mapped custom field, plus one call per collection row and one per contact-information row. A sync that fails partway is retried whole; the ledger of created rows keeps a retry from duplicating them.

DonorAtlas does not write over a value your team put in a mapped field. Each sync records what it wrote. On the next one, a field is written when it is empty or still holds what DonorAtlas last wrote, and is left alone when someone changed it in Virtuous; the job then names the fields it left. A team whose mapped fields are DonorAtlas's alone can turn on “Let DonorAtlas overwrite values already in these fields” on the Configure page. An unsync clears only the values that are still DonorAtlas's.

• Send a donor from DonorAtlas: from a DonorAtlas profile, Send to Virtuous. DonorAtlas looks for an existing Contact by email and name; a confident match is linked and written, no match creates a Contact with the person's name, address and (if opted in) contact information and then writes. A Contact sharing only the name is linked when the name is uncommon and no other Contact has it, and otherwise a new Contact is created and the job names the look-alike. Nothing is left undecided.
• Send a list: a DonorAtlas list is pushed the same way, one job per list with a sub-job per person.
• Bulk sync a Virtuous source: pick a Tag or an Organization Group on Bulk sync. Members already synced are skipped; each new member is read, matched, and written. Progress is on the Jobs panel and on the source's row.
• Resync: rewrites every mapped field for the source's synced members from the current DonorAtlas profile, replacing DonorAtlas's own collection rows. The same operation is available for one Contact from the donor's profile in DonorAtlas.
• Unsync: clears every mapped field and deletes every row DonorAtlas created, for one Contact from the donor's profile, for one source, or, on disconnect, for the whole team.
• Nightly automatic resync: every synced Contact older than the team's resync interval (default seven days) is resynced overnight; a team with a bulk run in progress is skipped that night.

Permissions: sync, unsync and bulk are granted per member on Users & connections; unsyncing a whole source additionally requires the Admin role.

9. Matching

Matching is DonorAtlas's own identity resolution over the fields read from the Contact: name, nickname, birth date, address, emails and phones. A record with a confident match is linked; a record with no match is recorded as such so a later bulk run does not spend a credit on it again. A shared surname never confirms a match on its own.

10. Limits & Considerations

• Virtuous enforces an hourly request budget per organization (the seeded sandbox and current help centre say 5,000 per hour) shared by every integration the organization runs. DonorAtlas paces itself to that budget and, when Virtuous answers 429, waits until the window resets. A large bulk sync of an organization with other busy integrations takes longer, not fewer records.
• A Text custom field holds 140 characters; longer values are truncated. Use Paragraph for long text.
• Virtuous does not expose the members of a Segment or a saved Query, so bulk sync is by Tag or Organization Group.
• Virtuous keeps Contact and Individual custom fields in separate namespaces; DonorAtlas writes Contact-level fields.
• A Contact whose primary Individual has no first and last name cannot be matched.

11. Credits

A DonorAtlas import credit is spent once per Contact when it is first matched, in a bulk sync of a source. Sending a donor from DonorAtlas, resyncing, unsyncing, and the nightly sweep spend nothing.

12. Security & Privacy

DonorAtlas stores the organization's API key in a secret of its own in AWS Secrets Manager (encrypted at rest with AWS KMS) and shows only its last characters to team members. Reads and writes happen server to server between DonorAtlas and Virtuous; nothing runs inside the Virtuous user interface. DonorAtlas reads a Contact's identity fields to match it and stores the linkage described in Section 6; it does not copy gifts or other Virtuous records. Data written into Virtuous becomes the customer's data in Virtuous under your Virtuous terms.

Donor photos are held in private DonorAtlas storage and never shared as a public link. When the photo setting is on, DonorAtlas reads the image itself and uploads it to Virtuous, which keeps its own copy; no link to DonorAtlas storage is written into Virtuous.

13. Troubleshooting

14. Uninstallation

Disconnect from the Configure page. DonorAtlas unsyncs every synced Contact (clearing mapped fields and deleting the rows it created), removes each member's connection, and deletes the key from Secrets Manager at once, with no recovery window. The custom fields and collections your administrator created stay in Virtuous, empty. Deactivate the API key in Virtuous afterwards if it will not be reused.

15. Glossary