Create a dedicated, read-only API user in Salesforce so Avid can sync donation data without a named staff login. Avid reads your data one way and syncs new and changed records daily.
Use this article when
- You are connecting Salesforce to Avid for the first time.
- You want to switch from a named-user OAuth connection to a dedicated integration user.
- Your sync fails, or fields are missing, after you change Salesforce credentials or permissions.
Applies to and prerequisites
| Where | Salesforce Setup, then Avid Settings > Connections |
|---|---|
| Role | Salesforce System Administrator or equivalent |
| License | One available Salesforce Integration user license |
| Time | 20–30 minutes |
The integration user needs each of these permissions. Missing any one of them can stop the sync.
| Salesforce setting | Required permission | What it enables in Avid | Where to verify |
|---|---|---|---|
| Permission set license | Salesforce API Integration | Access to standard objects such as Opportunity
|
User detail page, Permission Set License Assignments |
| Object permissions | Read on every object Avid reads | Records sync for each object | Permission set, Object Settings |
| Field permissions | View All Fields, or Read Access on each field | Field values, such as gift amounts, sync | Permission set, Object Settings, Field Permissions |
| Record access | View All Records, or a sharing rule | Records on private objects sync | Sharing Settings |
Prefer a staff login instead? See Connect Salesforce via OAuth. We recommend the integration user for production. It doesn't depend on one staff member or use a seat license.
Set up the integration user
Step 1: Create the integration user
- In Salesforce, go to Setup and search for Users.
- Click New User. Use a clear name, for example
Avid Integration. -
Set User License to Salesforce Integration.
Don't select the standard Salesforce license.
-
Set Profile to Minimum Access - API Only Integrations.
Older orgs may show Salesforce API Only System Integrations instead. Either profile works.
-
Save the user.
The new user appears on the Users list with an Active status.
Step 2: Assign the permission set license
- On the user detail page, go to Permission Set License Assignments and click Edit Assignments.
-
Enable Salesforce API Integration, then click Save.
Don't use the similar Salesforce Integration permission set license. It blocks standard objects like
Opportunity.
Step 3: Grant object and field access
- In Setup, search for Permission Sets and click New.
- Enter a label, for example
Avid Integration Access, and save. - Click Object Settings, select an object from the list below, and click Edit.
- Under Object Permissions, select Read.
-
Grant field access. Select View All Fields under Object Permissions.
Don't see View All Fields? Select Read Access for every field under Field Permissions instead.
Object Read alone is not enough. With a Minimum Access profile, field Read Access starts unchecked. Salesforce then hides those fields from Avid, and processing fails.
-
Click Save. Repeat for each object Avid reads.
Each object shows Read and either View All Fields or Read Access on its fields.
- Click Manage Assignments and assign the permission set to the integration user.
Objects Avid reads
Grant Read and field access on every object you use. Include objects you used in the past.
- Standard:
Opportunity,OpportunityLineItem,OpportunityContactRole,OpportunityStage,Account,Contact,Campaign,CampaignMember,CampaignMemberStatus,User,RecordType. - Products:
Product2,Pricebook2, andPricebookEntry. Grant Read even if you don't use Products. - If used:
Individual,Lead,ContactPointAddress,ContactPointEmail,ContactPointPhone,ContactPointTypeConsent. - NPSP:
npe01__OppPayment__c,npe03__Recurring_Donation__c,npe4__Relationship__c,npe5__Affiliation__c,npo02__Household__c,npsp__Account_Soft_Credit__c,npsp__Address__c,npsp__Allocation__c,npsp__General_Accounting_Unit__c,npsp__Level__c,npsp__Partial_Soft_Credit__c,npsp__RecurringDonationChangeLog__c,npsp__Opportunity_Stage_To_State_Mapping__mdt,npsp__RecurringDonationStatusMapping__mdt. - Custom objects you use for reporting, for example
Caseload_Owner__c. Tell LockStep Support how they relate to other objects.
Avid uses the Salesforce Describe API to read each object's fields and labels. Describe returns only fields the integration user can read. Fields without Read Access are left out, so Avid can't sync them.
The Describe check runs on every object, not just the ones that hold data. If one object returns 404 NOT_FOUND, the whole check fails and the sync stops.
Step 4: Grant record-level access
If an object's organization-wide default is Private, the integration user sees none of its records. Choose one option.
-
Option A, the simplest: in
Avid Integration Access, open each private object, such asOpportunity. Select View All Records under Object Permissions.View All Records ignores sharing rules. You can't use it to exclude records, such as contacts who are minors.
- Option B, a sharing rule: use this to exclude some records.
- Create a Public Group, for example Avid Integration Access, and add the integration user.
- In Sharing Settings, under Opportunity Sharing Rules, share opportunities with the group as Read Only.
- Save the rule. Salesforce emails you when the sharing recalculation completes.
- Repeat for any other private object, such as
AccountorContact.
LockStep insight: Missing Opportunities after the first sync almost always mean this step was skipped. See Fix: Opportunities are missing after connecting Salesforce to Avid.
Step 5: Connect in Avid
- In Avid, go to Settings > Connections > Add System and start the Salesforce connection flow.
- Enter the integration user's username and password, then complete the OAuth authorization.
- Save the connection and run a test sync.
Test and verify
Avid first runs a backfill of your full history. Most nonprofits see it finish within a few hours to a day. After that, Avid syncs new and changed records each day. Avid's data team then works with you to confirm field mappings.
Troubleshoot sync errors
A new integration user is usually missing access to an object or its fields. Work through these checks in order.
| Check | What to do |
|---|---|
| Permission set license | Confirm the user has Salesforce API Integration, not Salesforce Integration. |
| Object Read access | Grant Read on every object in the list, including Product2, Pricebook2, and PricebookEntry. |
| Fields missing, or the sync fails after a passing connection test | The user can read the objects but not their fields. Grant field access as in Step 3. Then contact LockStep Support for a full refresh. |
| Products disabled in your org | If Products or Price Books don't appear in your permission sets, contact LockStep Support. We can skip those objects. |
| Other private objects | Give the new user record access, as in Step 4. |
Changed permissions on an existing connection? Contact LockStep Support for a full refresh. Without it, past records stay incomplete.
If you tested the API directly and saw a NOT_FOUND error
Admins testing through Workbench or the REST API may see this response for an object the user can't access:
The requested resource does not exist
The same permission gap causes the sync to fail. Work through the checks above.
Still failing after these checks? Contact LockStep Support. Include the integration user's username and the date and time of the change or failed sync. Also say which permissions you changed, and whether Products are enabled.
Frequently Asked Questions
Can we control which fields Avid can read?
Yes. With a Minimum Access profile, fields start hidden. First grant Read Access on all fields of the object. Then uncheck Read Access on the sensitive fields.
Don't use View All Fields on that object. It grants every field, including fields added later.
Keep core fields readable. Hiding them breaks processing, even when the connection test passes. These include:
-
AccountIdonContactandOpportunity -
AmountandCloseDateonOpportunity -
npe01__Payment_Date__candnpe01__Payment_Amount__connpe01__OppPayment__c -
npsp__Opportunity__candnpsp__Amount__connpsp__Allocation__c
Can we limit which Salesforce records Avid has access to?
Yes, with Salesforce's own permission model. Set the Organization-Wide Default (OWD) to Private. Then grant access back to specific subsets with Sharing Rules.
For example, exclude minors with a condition such as Is_Minor__c = FALSE. Use Option B in Step 4, because View All Records overrides sharing rules.
Custom objects can also use Restriction Rules. This is a Salesforce limit, not Avid: they don't work on Contact, Account, or Opportunity.
What if we don't use a listed object?
Still grant Read on it. Avid's metadata check needs access to every listed object, even empty ones. If the object doesn't exist in your org, contact LockStep Support.
How much of our Salesforce API limit does Avid use?
After the backfill, Avid syncs only records changed since the last sync, based on SystemModstamp. Most organizations see 5,000–10,000 API calls per day. Avid respects all Salesforce backoff and retry headers.
How is our Salesforce data protected?
You own your data. The connection is read-only by default, and data is encrypted in transit and at rest. If you stop using Avid, your data is securely deleted. See trust.avidai.com for SOC 2 details.
Who should configure these permissions?
Your Salesforce administrator or implementation partner. See the Salesforce Help Center for details. Unsure? Once your integration user exists, our team can verify object and field access from Avid's side.