Skip to main content

Virtuous CRM

Updated

Sync contacts, gifts, campaigns, and other donor data from Virtuous CRM to Avid for analysis, segmentation, and marketing automation.

Use this article when

  • You want to connect your Virtuous CRM instance to Avid for the first time.
  • You need to create or regenerate an API key in Virtuous.
  • You are updating an existing Virtuous connection with a new API key.
  • You need to configure the minimum permissions required for Avid integration.

Before you begin

Requirement Details
Avid permission Connections > Edit
Virtuous role Admin access to Settings and API key management
What Avid reads Contacts, gifts, campaigns, communications, segments, projects, and recurring gifts (read-only)
Time estimate 10–15 minutes

Virtuous recently updated API key authentication to require both a name and a permission group assignment. This article covers the new process.

Step 1: Create a custom permission group (recommended)

Avid only reads data from Virtuous — it never writes, deletes, or modifies records. Create a custom permission group that allows read access but blocks all write operations. This is more secure than using the default Admin group.

Name your permission group something descriptive like Avid Integration so your team knows its purpose.

Access the permission group settings

  1. Log in to Virtuous.
  2. In the left-side navigation, click the Settings link at the bottom left.
  3. Click on All Settings.
  4. In the mid-page navigation, click on CONNECTIVITY.

  5. Click on Permission Groups.

Create the Avid Integration permission group

  1. In the top right corner, click CREATE A PERMISSION GROUP.
  2. Enter the name: Avid Integration.

  3. Under Permission Settings, click through the following features and enable the corresponding permissions.

    Feature Permissions
    Contact
    • Audit Logs
    • View Private
    • View Wealth
    Gift
    • Read
    • View Statistics
    • View Private
    Campaign
    • Read
    Project
    • Read
    Recurring Gifts
    • Read
    • View Private

    Enable View access on all features noted above to ensure complete data sync. Virtuous may silently omit data for features without View permission rather than showing an error. Do not enable Write, Delete, Bulk Edit, or Import on any feature — Avid never modifies your Virtuous data.

    If you'd rather skip creating a custom group, you can use the default Admin permission group when creating the API key. Admin grants full access, including write permissions Avid doesn't need, but it will work.

  4. Click Save.

    You'll see a confirmation message and the permission group appears in the list.

Step 2: Create an API key in Virtuous

  1. In Virtuous, go to Settings > All Settings (same as above).
  2. In the mid-page navigation, click CONNECTIVITY.

  3. Click API Keys.

    You see a list of existing API keys (if any).

Generate a new API key

  1. In the top right corner, click CREATE AN API KEY.

  2. A form appears with two required fields:

    • Name — Enter a descriptive name for this key. For example: Avid Integration.
    • Permission Group — Select the permission group from the dropdown. Choose Avid Integration (if you created it in Step 1) or Admin if you prefer to use an existing group.

    Do not select a permission group that lacks read access to contacts, gifts, campaigns, and other core data types. If you select the wrong group, the API key will fail to connect.

  3. Click Save.

    Virtuous creates the API key and displays a success message. The key now appears in the API Keys list.

Copy the API key value

  1. In the API Keys list, find the key you just created (it matches the name you entered).
  2. Click the Edit icon (pencil) next to the key name.
  3. A details panel opens. You see a copy button next to the API key value.

  4. Click the copy button to copy the full API key to your clipboard.

    The API key is only displayed once during creation and when you edit the key. Store it securely. If you lose the key value, you must regenerate a new one.

Step 3: Connect Virtuous to Avid

  1. In Avid, go to Connections.
  2. Click Add Connection.

  3. Search for and select Virtuous CRM.

    The connection form opens.

Enter your API key

  1. In the API Key field, paste the key you copied from Virtuous.

  2. Click Save.

    Avid validates the API key by calling the Virtuous organization endpoint. This may take a few seconds.

Verify the connection

  1. If the connection is successful, the form closes and you return to the Connections page.
  2. You see the new Virtuous CRM connection in your list with a Connected status.
  3. Click on the connection to see the organization name and sync status.

What you'll see

After a successful connection, your Avid account begins syncing data from Virtuous CRM within a few minutes.

Data synced from Virtuous

  • Contacts — All donor and constituent records
  • Gifts — Donation and transaction records
  • Campaigns — Campaign tracking and attribution
  • Communications — Email, call, and interaction logs
  • Segments — Predefined audience segments from Virtuous
  • Projects — Grant projects and initiatives
  • Recurring Gifts — Scheduled recurring donation records

Using your synced data in Avid

Your Virtuous data is now available as DataSets in Avid. You can:

  • Create segments and audiences based on your Virtuous data.
  • Build custom reports and dashboards.
  • Push audiences to email marketing and other platforms via Pathways.
  • View your donor data in the Insights module.

Data syncs from Virtuous to Avid continuously. Avid never writes or modifies records in your Virtuous instance — the sync is read-only in one direction.

Troubleshooting

Connection fails with "API Key was not able to successfully connect"

This error means Avid could not reach your Virtuous instance or validate the API key. Check the following:

  1. Verify the API key is correct. Copy it directly from Virtuous without any extra spaces or characters.
  2. Confirm the API key has not expired. In Virtuous, check the API Keys list to confirm your key is still active.
  3. Ensure the permission group assigned to the API key has View access to Contact, Gift, Campaign, and Email features. If the permission group lacks these permissions, the connection will fail.
  4. Check your Virtuous account status. If your Virtuous subscription is inactive or in trial, the API may be disabled.
  5. Try creating a new API key with the Admin permission group (temporarily) to rule out permission group issues.
Data is not syncing after connection

If the connection shows as Connected but data is not appearing:

  1. Wait a few minutes. The initial sync can take 5–10 minutes depending on your data volume.
  2. Check the sync status in Avid. Go to Connections and click on your Virtuous connection. Look for any sync errors or warnings.
  3. Verify your Virtuous data exists. Log in to Virtuous and confirm you have contacts, gifts, campaigns, and other records.
  4. Contact Avid support if syncs are failing. Provide the connection name and organization ID so we can investigate.
I used the Admin permission group but prefer to lock it down later

You can change the permission group assigned to your API key without regenerating it:

  1. Log in to Virtuous and go to Settings > All Settings > CONNECTIVITY > API Keys.
  2. Click the Edit icon next to your Avid API key.
  3. Click the Permission Group dropdown and select Avid Integration (or your custom group).
  4. Click Save.
  5. The API key now uses the new permission group. No changes are needed in Avid.

Changing the permission group does not invalidate the API key. Avid's connection continues to work as long as the new permission group includes read access to the required data types.

I need to regenerate the API key

If your API key is compromised or lost, you can create a new one:

  1. In Virtuous, go to Settings > All Settings > CONNECTIVITY > API Keys.
  2. Click the Edit icon next to the key you want to replace.
  3. Click Delete to remove the old key.
  4. Create a new API key following the steps in Step 2: Create an API key in Virtuous.
  5. In Avid, go to Connections, find your Virtuous connection, and update it with the new API key.

Next steps

Once your Virtuous connection is live, combine your donor data with other sources (email service providers, wealth data, etc.) to create more targeted segments. Use Data Blends to normalize and enrich your audience data.

Related articles