Skip to main content

Salesforce via API-Only integration user

Updated

Create a dedicated, read-only API user in Salesforce so Avid can sync donation data securely without relying on a named staff login.

Use this article when...

  • You are connecting Salesforce to Avid for the first time.
  • You want to switch from an OAuth (named-user) connection to a dedicated integration user.
  • You see sync errors related to missing object permissions after changing Salesforce credentials.

Applies to / prerequisites

Item Details
Product area Connections > CRM Systems > Salesforce
Role Salesforce System Administrator or equivalent
Time to complete 20–30 minutes

Why use an API-Only integration user

Avid supports two OAuth patterns for Salesforce.

  • A real staff user authorizes the connection. This uses that person's seat license and inherits their permissions.
  • A dedicated Salesforce Integration user authorizes the connection. This uses a free integration license and only the permissions you grant on a single permission set.

Either pattern works. We recommend the API-Only user for production because it does not depend on any one staff member, does not consume a seat license, and lets you scope access precisely.

LockStep insight: If your data team plans to enforce Field-Level Security for donor records or custom fields, build that policy on the integration user's permission set first. It is easier to widen access later than to claw it back from a seat user with broad profile access.

If you prefer the seat-based approach, see Connect Salesforce via OAuth instead.

Steps

Step 1: Create the integration user

  1. In Salesforce, go to Setup and search for Users.
  2. Click New User.
  3. Fill in the required fields. Use a clearly identifiable name, for example Avid Integration.

  4. Set the User License to Salesforce Integration.

    Important: Do not select Salesforce (the standard user license). Select Salesforce Integration, which is the dedicated API-only license.

  5. Set the Profile to one of the following API-only profiles:

    • Minimum Access - API Only Integrations (Spring '24 and newer)
    • API Only System Integrations (legacy)

    Note: Item names may vary slightly between the newer Spring '24 profile and the legacy profile. The concepts are the same.

  6. Save the user.

    You see the new user on the Users list with an Active status.

Step 2: Assign the correct permission set license

  1. On the user detail page, scroll to Permission Set License Assignments.
  2. Click Edit Assignments.

  3. Move Salesforce API Integration to the Enabled Permission Set Licenses column.

    Critical: This is not the same as the similarly-named Salesforce Integration permission set license. The Salesforce Integration license blocks access to default objects like Opportunity. Always select Salesforce API Integration.

  4. Click Save.

Step 3: Grant object access through a permission set

  1. In Setup, search for Permission Sets and click New.
  2. Enter a label, for example Avid Integration Access, and save.

  3. Under Object Settings, enable Read (and Edit only if your workflow requires it) for every object Avid needs.

    See the full object list below for details.

  4. Click Manage Assignments and assign the permission set to your integration user.

Step 4: Grant record-level access to Opportunities

  1. In Setup, search for Sharing Settings.

  2. If the Opportunity organization-wide default is set to Private, the integration user will not see any opportunities because it owns no records.

    LockStep insight: If Opportunities are missing in Avid after the first sync, this is almost always the cause. See Fix: Opportunities are missing after connecting Salesforce to Avid.

  3. Create a new Public Group, for example Avid Integration Access.
  4. Add the integration user to the group.
  5. Under Opportunity Sharing Rules, create a rule that shares all opportunities with Avid Integration Access as Read Only.
  6. Save the rule. Salesforce emails you when the sharing recalculation completes.

Note: The same pattern applies to any other private object you want Avid to read. Account and Contact are typically not private, but if yours are, add sharing rules for those objects too.

Step 5: Connect in Avid

  1. In Avid, go to Settings > Connections > Add System and start the Salesforce connection flow.
  2. When prompted, enter the integration user's username and password.
  3. Complete the OAuth authorization.
  4. Save the connection and run a test sync.

What happens after you connect

Once Salesforce is linked, Avid runs an initial backfill so every donor's history is complete and trends are visible end to end. After the backfill completes, Avid syncs only new and modified records each day to keep the data fresh and aligned with Salesforce.

Backfill duration depends on the size of your org. Most nonprofits see the first sync complete within a few hours to a day.

Once data is flowing, Avid's data team will work with your team to confirm field mappings. The goal is to make sure you have the flexibility to view, filter, and act on the data the way that makes sense for your organization.

Required object access

Grant the integration user Read access to every object you use. You can skip objects your organization does not use, but we recommend including them if they were used historically.

Standard Objects
  • Opportunity: Donation transaction reporting.

  • OpportunityLineItem: Split-designation gifts.

    Prerequisites: The integration user needs Read access to OpportunityLineItem, Opportunity, Product2 (Products), Pricebook2, and PricebookEntry. Even if you do not use Products, granting Read on these objects keeps the metadata check from failing during sync. If Products are disabled at the org level and these objects do not appear in your permission sets, contact LockStep Support so we can align the sync connection to your schema.

  • OpportunityStage: Custom stage name mapping.
  • Account: Grouping households and non-individual donor types.
  • Contact: Individual-level reporting, contactability cohorts, and mail segmentation.
  • Campaign: Campaign-level reporting and mail segmentation.
  • CampaignMember: Segmentation and mail-related needs.
  • CampaignMemberStatus: Status checks within campaigns.
  • User: Friendly name and username values for caseload owners.
  • RecordType: Subtypes for other object types.
Conditional Objects (if used)
  • Individual: Householding models or Data Protection and Privacy consent storage.
  • Lead: Original lead acquisition data and integrations like Pardot.
  • ContactPointAddress: Contactability reporting and mail for individual or person accounts.
  • ContactPointEmail: Contactability reporting and segmentation.
  • ContactPointPhone: Contactability reporting and segmentation.
  • ContactPointTypeConsent: Related consent values.
NPSP-related Objects (if enabled)
  • npsp__Account_Soft_Credit__c: Account-level soft credits, especially DAFs.
  • npsp__Address__c: Contactability cohorts and household-level mail segmentation.
  • npsp__Allocation__c: Split-designation gifts with General Accounting Units.
  • npsp__General_Accounting_Unit__c: Designation and giving-type filtering.
  • npsp__Level__c: Organizations using NPSP Levels.
  • npsp__Opportunity_Stage_To_State_Mapping__mdt: Custom stage categorization.
  • npsp__Partial_Soft_Credit__c: Partial soft-credit attribution.
  • npsp__RecurringDonationChangeLog__c: Recurring donor retention, upgrade, and downgrade reporting.
  • npsp__RecurringDonationStatusMapping__mdt: Custom recurring statuses.
  • npe01__OppPayment__c: Channel and source reporting enrichment.
  • npe03__Recurring_Donation__c: Recurring gift reporting.
  • npe4__Relationship__c: Related records.
  • npe5__Affiliation__c: Affiliation data.
  • npo02__Household__c: Householding and mail selects.
Organization-specific Objects
  • Any custom object your organization uses for segmentation or reporting. For example, Caseload_Owner__c ensures midlevel and major donors are correctly categorized. Grant the integration user Read access to those objects and let Avid Support know how they relate to other objects so we can map them in.
Object Describe (endpoint)

While not an object, Avid uses the Describe endpoint to check permissions, detect which NPSP features are used, and provide friendly field names. This is generally enabled along with object permissions.

Important: The Describe check runs against every object in your schema, not just the ones currently syncing. If any single object returns a 404 NOT_FOUND, the entire metadata check fails and the sync stops. This most commonly happens when switching to a new integration user on a Minimum Access profile, which starts with zero object permissions. Granting Read on the objects listed above, including Product2, Pricebook2, and PricebookEntry, keeps the metadata check healthy even if your org does not store data in those objects.

Security and data ownership

You own your Salesforce data. Avid only does what you authorize, which is visualizing, analyzing, and integrating it the way you have asked.

  • All data is encrypted in transit and at rest.
  • Salesforce connections are read-only by default.
  • No identifiable data leaves Avid except through integrations you explicitly turn on.
  • If you stop using Avid, your data is securely deleted.
  • For organizations with HIPAA, BAA, or similar requirements, our team can sign supplemental documents.

You can review live compliance posture, including SOC 2 attestation and policy controls, at trust.avidai.com.

Troubleshoot sync errors

Salesforce sync fails after switching credentials

If your Salesforce sync starts failing soon after you move from one user to a new integration user, the new user is usually missing access to one or more objects that Avid checks during sync. Work through the checks below in order.

Check What to do
Permission Set License Confirm the integration user has the Salesforce API Integration permission set license, not the similarly-named Salesforce Integration permission set license. The latter blocks access to standard objects like Opportunity.
Object Read access Grant Read on OpportunityLineItem, Opportunity, Product2, Pricebook2, and PricebookEntry through the permission set assigned to the integration user. This keeps the metadata check healthy even if your org stores no data in Products or Price Books.
Products fully disabled in your org If Products, Price Books, or Price Book Entries do not appear in your permission sets at all, contact LockStep Support. We can align the sync connection so the metadata check skips objects that do not exist in your schema.
Other private objects If you switched the connection and other objects (for example, Account or Contact) are set to Private, add the new integration user to the same sharing rules you used before.

Why one object can stop the whole sync: Avid runs a metadata check across every object in your schema on each sync. If the integration user cannot access even one object, the check fails and the sync stops, even when every other object is healthy. Granting Read on the objects above, or asking LockStep Support to align the connection, clears the check.

If you tested the API directly and saw a NOT_FOUND error

Salesforce admins who test the integration user directly through Workbench or the REST API may see this response when describing an object the user cannot access:

The requested resource does not exist

The same permission gap causes the sync to fail. Work through the checks above to resolve it.

Get help

If the sync still fails after verifying the permission set license and object access, contact LockStep Support with:

  • The Salesforce username of your integration user.
  • The date and time you switched credentials or ran the failing sync.
  • Whether Products, Price Books, and Price Book Entries are enabled in your org.

Frequently Asked Questions

Can we limit which Salesforce records Avid has access to?

Yes. Control this entirely within Salesforce using its built-in permission model. We recommend creating a dedicated read-only, API-only user for Avid and limiting its permissions accordingly.

The most common setup is to make all records private by default using an Organization-Wide Default (OWD) and then grant access back to specific subsets through Sharing Rules. For example, exclude contacts marked as minors by setting a condition such as Is_Minor__c = FALSE.

For custom objects, Restriction Rules can also be used, though Salesforce currently does not support them on core objects like Contact, Account, and Opportunity.

Can we control which fields Avid can read?

Yes. While we recommend granting access to all fields (it does not materially impact sync performance), you can restrict access using Field-Level Security (FLS).

Create a custom Permission Set and set sensitive fields to an access level of None (Hidden). This ensures Avid cannot read those fields during synchronization. Many organizations use this approach when certain fields contain legacy or sensitive data.

What happens if we do not use a listed object?

You can skip object data your organization does not use, but the integration user still needs Read access to those objects so Avid's metadata check can complete. Without Read access, one inaccessible object can fail the check and block the sync, even when no records exist.

If an object does not exist in your org at all (for example, Products is fully disabled), contact LockStep Support. We can adjust the sync connection so the check skips that object.

How much of our Salesforce API limit does Avid use?

After the initial backfill (which reads all historical data), Avid only syncs new or updated records based on SystemModstamp. Ongoing API usage is minimal.

While actual usage depends on how active your Salesforce instance is, most organizations see 5,000–10,000 API calls per day across all objects. Salesforce does not provide a way to set per-user API limits, but Avid respects all backoff and retry headers.

Who should configure these permissions?

Your Salesforce Administrator or implementation partner will typically be familiar with setting up API users, Permission Sets, and Sharing Rules. These controls are well-documented in the Salesforce Help Center.

However, if you are unsure, our team can verify object access from Avid's side once your API-only user is created.

Next steps / related workflows

Notes and limits

Note on naming variations

The naming of certain items may vary slightly based on whether you are using the newer Spring '24 Minimum Access - API Only Integrations profile or the legacy API Only System Integrations profile. The concepts are the same.

Permission Set License confusion

The Salesforce API Integration permission set license is documented in the Salesforce Help Center, but the language can be confusing and does not give step-by-step instructions. If you are not sure about your permission sets, test connecting in Avid with the new user, or contact us and we can check object access from our side.

Related articles