Technical Administration Guide

1. Product Overview

DonorAtlas for EveryAction (Bonterra; the NGP VAN platform, “EA8”) writes DonorAtlas prospect research into EveryAction contact records and keeps it current. A DonorAtlas user chooses a contact, a saved list, or a DonorAtlas list; DonorAtlas identifies each person in its own database and writes the research your team has chosen into custom contact fields, a DonorAtlas note, and, if you opt in, the contact's own employment and contact-information fields, with a link back to the full DonorAtlas profile. From then on, every nightly sweep refreshes what was written.

EveryAction has no add-in or panel framework for third parties, so there is no embedded DonorAtlas tile. The integration is the written data plus the profile link, and everything in EveryAction that reads custom fields (searches, lists, exports, reports) can use it.

What the Integration Never Touches

Contributions, pledges, activist codes, survey responses, canvass or contact history, scores, events, or the name and addresses of a contact you already have (a contact DonorAtlas creates for a donor you send is given the donor's name and mailing address). Emails and phones are added only when your team opts in, and social profiles only when it turns them on; EveryAction offers no way to remove either afterwards, which the Configure page says before you turn them on.

2. Prerequisites & Roles

On the EveryAction side you need an administrator of the committee, to create custom fields, generate an API key, and share saved lists. On the DonorAtlas side, connecting and configuring takes the Admin or Configure Only team role; any member can then connect their own account and sync within the permissions your admin grants (Section 8).

Before connecting, the committee administrator sets up:

• A Custom Contact Field group (Administrative Menu → Custom Contact Fields → Add New Custom Field Group, group type Contacts) named for DonorAtlas, with one field per DonorAtlas value you want written, of a type that fits: Number or Money for figures, Text for names and the profile URL, Date for dates. DonorAtlas offers only these four types for mapping, so a Boolean or Selection field never appears in its dropdowns. EveryAction has no URL field type; the profile URL goes in a Text field and is also the first line of the DonorAtlas note.
• An API key for DonorAtlas: API Integrations → Request an API Key, naming DonorAtlas as the integration; an administrator approves it and the requester generates it. The key is shown once. Keys are issued per committee and per database; DonorAtlas uses the My Campaign database, so the key you paste ends in |1.
• Saved lists you want to bulk sync, shared with the user the API key belongs to. EveryAction scopes lists and folders per user; a list the API user cannot see does not appear in DonorAtlas.

3. Installation & Connection

There is nothing to install in EveryAction; the click-by-click version of the steps below is the Quick Start Guide. In DonorAtlas:

1. An Admin or Configure Only user opens Integrations → EveryAction → Set up and pastes the key. DonorAtlas validates it (GET /apiKeyProfiles), trying the US endpoint and then the international one; it records the first endpoint that accepts the key, the committee id and name, and links your DonorAtlas team to that committee. One committee links to one DonorAtlas team and vice versa; a customer with several committees connects each to its own team.
2. The same user opens Configure and maps DonorAtlas fields to the custom fields DonorAtlas discovered (Section 5).
3. Each other member clicks Connect once on the Integrations hub or on Users & connections; no EveryAction sign-in is involved.

4. Authentication Architecture

EveryAction authenticates every request with HTTP Basic credentials: DonorAtlas's application name and the committee's API key. The key is held once per DonorAtlas team, in a secret of its own in AWS Secrets Manager (encrypted at rest with AWS KMS), and shown to members only by its last characters. Keys can carry an expiry set by the approving administrator; when EveryAction rejects the key, 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 Configure. The replacement must belong to the same committee; the mapping and every member's connection survive.

DonorAtlas never holds an EveryAction username or password, and the integration makes no calls from a browser. EveryAction assigns each vendor a security tier; DonorAtlas operates at the tier that permits writing custom fields and notes and reading contacts and saved-list exports, and does not use the higher-tier change-tracking exports or score loading.

5. Configuration

The Configure page lists every DonorAtlas field the integration can write (Section 7) with, beside each, the custom contact fields whose type can hold it. Repeating fields (employment history, education, board seats, foundations, public donations) have no structured home in EveryAction; when the note switch is on they are written as lines of the DonorAtlas note.

Switches under the mapping: the note switch (on by default) maintains one DonorAtlas note per contact; Let DonorAtlas overwrite values already in these fields (off by default) lets a sync write over a value your staff changed; Fill in employer, occupation and job title (off by default) writes the person's current employer, occupation and title into EveryAction's own fields under the same rule as the mapped fields, so it fills an empty one, keeps refreshing one DonorAtlas filled, and leaves alone one your staff changed unless the overwrite switch is on, which applies to these fields too; Add social profiles to the person (off by default) puts the person's LinkedIn, Facebook, X (Twitter), Instagram and YouTube profiles into EveryAction's external ID slots for those networks, one per network, under the same rule; Write verified contact information (off by default) appends DonorAtlas's verified email and mobile phone to the contact's emails and phones on every sync, with the caveat that EveryAction cannot remove them later (it does not add a mailing address to an existing contact); an advanced switch stamps the DonorAtlas person id as an external identifier on the contact, which works only once your committee has an external ID type named DonorAtlas. DonorAtlas reads the committee's external ID types (the values of the bulk-import ApplyExternalID mapping) to show whether it does, and won't turn the switch on until it does.

The DonorAtlas ID stamp and its external ID type

With Stamp the DonorAtlas ID on the person on, every sync adds the donor's DonorAtlas ID to the EveryAction contact as an external ID, so your team can look a contact up by it. Nothing in DonorAtlas reads the stamp back.

EveryAction accepts an external ID only under a type your committee already has, and refuses the whole write when sent one it doesn't. So the stamp needs an external ID type named exactly DonorAtlas in your committee first. DonorAtlas checks for it and keeps the switch off until it exists.

How to get the DonorAtlas external ID type

Committee administrators can't create external ID types in EveryAction. Bonterra's support team creates an external ID type and shares it with your committee, so you ask them for it:

1. Open a support request. In EveryAction, scroll to the bottom of the left-hand menu, click Need a Little Help?, then Request Support. (You can also type “Submit a Support Request” into Search for a page.) A request made this way goes to your organization's account administrator first, who passes it on to Bonterra. You can instead email EA-Help@bonterratech.com or call (202) 370-8050, Monday to Friday, 8 am to 6 pm Eastern.
2. Ask for the type. Something like: “Please create a contact external ID type named DonorAtlas and share it with our committee, [your committee's name]. It holds alphanumeric IDs (letters, digits and hyphens), and it doesn't need to be unique or used for matching.” The name has to be exactly DonorAtlas, because that is the type DonorAtlas writes under.
3. Reload the Configure page in DonorAtlas once Bonterra confirms. It reads your committee's external ID types afresh, shows that the committee has the type, and lets you turn on Stamp the DonorAtlas ID on the person.

• If the type is deleted later, syncs don't fail: DonorAtlas writes the contact without the stamp and says so on the job.
• EveryAction can't remove an external ID once it is added, so an unsync leaves the stamp in place.

Verified contact information, and why an unsync leaves it

With Write verified contact information onto EveryAction records on, each sync adds DonorAtlas's verified email and mobile phone to the contact's own emails and phones. EveryAction adds them alongside what the contact already has; nothing your team entered is replaced. A mailing address is written only when DonorAtlas creates a new contact, whether or not this setting is on, and never added to an existing one.

Saving validates against a fresh discovery, marks any field whose custom field no longer exists, and counts the integration as configured only while at least one field has somewhere to land.

6. Data Model

An EveryAction contact is a person record keyed by VanID within the committee's My Campaign database. Emails, phones and addresses are arrays on the person, each with a preferred flag; custom field values, codes and notes attach to the person.

DonorAtlas keeps one linkage row per synced contact: the VanID, the matched DonorAtlas person, the match probability, when it was last written and by whom, and the id of the DonorAtlas note. Custom fields are rewritten in place on every sync; the note is updated in place.

7. Data Dictionary

Values come from the same DonorAtlas profile the app shows. Political fields obey your team's political-data setting for EveryAction; when it is off for the CRM they are written as empty on the next sync.

Scalar Fields (Custom Contact Fields)

The DonorAtlas Note

One note per contact, created on first sync and rewritten on every later one: the profile link on the first line, then whichever repeating fields you ticked on Configure (Education, Employment, Board Affiliations, Private Foundations, Public Donations, Social Media & Bio Websites) as readable lines, and the sync date. Notes are created visible to all users. On unsync the note's text is replaced with a line saying DonorAtlas data was removed, because EveryAction has no way to delete a note.

Contact Record Fields (Opt-in)

Employer, occupation and job title (filled when empty, refreshed when still DonorAtlas's, and written over a value your staff changed only when the overwrite switch is on); social profiles as external IDs, under the same rule; verified personal email and mobile phone appended to emails and phones. The mailing address is written only when DonorAtlas creates a new contact for a donor sent from DonorAtlas, whether or not contact information is opted in, and is never added to an existing contact.

8. Sync Operations

A sync reads the contact, then sends one POST /people/{vanId} carrying every mapped custom field and any opted-in record fields, then the note. Sending a new donor uses findOrCreate, which either matches an existing contact (EveryAction's own match rules: name plus email, phone, or address) or creates one.

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 EveryAction; 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: DonorAtlas first looks for an existing contact by name plus email, phone or address; a confident match is linked and written; no match creates the contact and 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 saved list: DonorAtlas starts an export job for the list in EveryAction, waits for EveryAction to report it complete (EveryAction calls a DonorAtlas endpoint when the file is ready; DonorAtlas also polls as a fallback), reads the file, skips members already synced, and matches and writes each new member. Progress is on the Jobs panel and the list's row on Bulk sync.
• Resync: rewrites every mapped field and the note for the list's synced members. The same operation is available for one contact from the donor's profile in DonorAtlas.
• Unsync: clears each mapped custom field that is empty or still holds what DonorAtlas wrote (any of them, with overwrite on), empties the note, and removes the linkage, for one list or, on disconnect, for the whole team. Emails, phones, addresses, external IDs (social profiles and the DonorAtlas stamp) and filled employment fields are left in place. One contact can be unsynced from the donor's profile in DonorAtlas.
• 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 list 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, addresses, emails, phones, employer and occupation. A confident match is linked; no match is recorded 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

• EveryAction rate-limits per API key by vendor tier; on the tier DonorAtlas starts at, the contact-matching endpoints allow 2 requests per second and everything else 5. DonorAtlas paces to those figures and, on a 429, waits the interval EveryAction names. A saved list of a few thousand contacts syncs over hours, not minutes.
• Custom fields and saved lists are created and shared in EveryAction, never by DonorAtlas. A field's type is fixed at creation.
• Text fields have a per-field character limit set at creation; longer values are truncated.
• Emails, phones and external IDs (social profiles, the DonorAtlas stamp) that DonorAtlas adds cannot be removed by API; the Configure page says so beside the contact-information and social-profile switches.
• Saved-list membership is read through an export, which EveryAction produces asynchronously; a very large list is truncated by EveryAction at its export size limit.

11. Credits

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

12. Security & Privacy

The committee's API key is stored in a secret of its own in AWS Secrets Manager (encrypted at rest with AWS KMS) and shown only by its last characters. All traffic is server to server between DonorAtlas and EveryAction's API; nothing runs inside the EveryAction interface. The export-completion callback EveryAction makes to DonorAtlas carries a single-use secret minted per export and is ignored otherwise. DonorAtlas reads a contact's identity fields to match it and stores the linkage described in Section 6; it does not copy contributions or other records. Data written into EveryAction becomes the customer's data there under your EveryAction terms.

13. Troubleshooting

14. Uninstallation

Disconnect from the Configure page. DonorAtlas unsyncs every synced contact (clearing mapped fields and emptying the DonorAtlas note, and leaving what an unsync leaves, as Section 8 describes), removes each member's connection, and deletes the key from Secrets Manager at once, with no recovery window. Custom fields stay defined in EveryAction. Revoke the key in EveryAction afterwards if it will not be reused.

15. Glossary