Skip to main content

Salesforce via API-Only integration user

Updated
Note: The naming of certain items may vary slightly based on whether you're using the newer Spring '24 "Minimum Access - API Only Integrations" profile or the legacy "API Only System Integrations" profile. But the concepts should be similar otherwise.

To set up your API-only user, you need to do the following:

  • Create the user
  • Assign the "Salesforce Integration" user license
  • Assign the appropriate API-only profile (either Minimum Access - API Only Integrations or API Only System Integrations)
  • When assigning permission sets/permission set groups, make sure that the Salesforce API Integration permission set license is associated. (Note that this is not the same as the similarly-named Salesforce Integration permission set license type, which will block access to default objects like Opportunity!)

This is documented in the Salesforce Help Center, but the language of the current article makes it very confusing and doesn't give any step-by-step instructions or troubleshooting tips. If you aren't sure about your permission sets, you can either test connecting in Avid with the new user, or provide a credential and we can check object access from our side. 

After you have set up your API-only user in Salesforce:

 To use an API-only Salesforce user, you'll want to first provision it and grant access on the objects listed below, and then complete the process by logging in with that username and password when prompted through the oAuth process in Avid. Note that you can also use field-level permissions if needed, but the object metadata needs to be accessible (see note on "sObject Describe" below).
 
For the non-default objects, you can ignore them if they aren't utilized in your instance. Note that we'll automatically detect which objects are actively used, but would prefer still having them included if they were used at any point historically. I've also added notes on how we use the data from each object:
  • Standard Objects
    • Opportunity (used for donation transaction reporting)
    • OpportunityLineItem (used for split-designation gifts)
      • Prerequisites: The integration user must have Read access to OpportunityLineItem, Opportunity, and Product2 (Products). If your org does not use Products, this object will not exist and should be excluded from the sync.
    • OpportunityStage (used to map any custom stage names)
    • Account (used for grouping households as well as non-individual donor types)
    • Contact (used for individual-level reporting, contactability cohort reporting, and mail segmentation)
    • Campaign (used for campaign-level reporting, mail segmentation)
    • CampaignMember (used for segmentation and mail-related needs)
    • CampaignMemberStatus (used to check the status within a campaign)
    • User (provides friendly name/username values for caseload owners and similar)
    • RecordType (used to list subtypes for other object types)
  • Conditional Objects (if used)
    • Individual (used in some householding models or when "Data Protection and Privacy" mode is enabled to store consent information)
    • Lead (used by some organizations to store original lead acquisition data, as well as by integrations like Pardot)
    • ContactPointAddress (used for contactability reporting and mail when using individual or person accounts)
    • ContactPointEmail (used for contactability reporting and segmentation when using individual or person accounts)
    • ContactPointPhone (used for contactability reporting and segmentation when using individual or person accounts)
    • ContactPointTypeConsent (used to store related consent values)
  • NPSP-related Objects (if enabled)
    • npsp__Account_Soft_Credit__c (used for account-level soft credits, especially common with DAFs)
    • npsp__Address__c (used for contactability cohort reporting as well as mail segmentation for household-level addresses)
    • npsp__Allocation__c (used with General Accounting Units to handle split-designation gifts)
    • npsp__GeneralAccountingUnits__c (used to list/filter designation and other giving types)
    • npsp__Level__c (for organizations using the NPSP levels in their program)
    • npsp__Opportunity_Stage_To_State_Mapping__mdt (used to correctly categorize and custom stages)
    • npsp__Partial_Soft_Credit__c (used to properly attribute partial soft credits)
    • npsp__RecurringDonationChangeLog__c (used to enrich recurring donor retention/upgrade/downgrade reporting)
    • npsp__RecurringDonationStatusMapping__mdt (handles custom recurring statuses)
    • npe01__OppPayment__c (used to enrich channel and source reporting)
    • npe03__Recurring_Donation__c (used to enrich recurring gift reporting)
    • npe4__Relationship__c (handle related records)
    • npe5__Affiliation__c (affiliation data, if used)
    • npo02__Household__c (used to handle householding, including for mail selects)
  • Organization-specific
    • FOR EXAMPLE -- Caseload_Owner__c (used to ensure midlevel/major donors are correctly categorized)
  • Other
    • sObject Describe (while not an object, we use the Describe endpoint to check permissions, detect which NPSP features are used, and also provide friendly names for fields. Generally, this is enabled along with the object permissions, but in some cases may be overridden)

Note: If any selected stream's underlying object is inaccessible to the integration user, the Describe call will return a 404 NOT_FOUND error and the stream will fail. This most commonly occurs when switching to a new integration user that uses a "Minimum Access" profile, which starts with zero object permissions by default.

Grant the integration user access to all Opportunities

If your Salesforce org has Opportunity org-wide default set to Private, the integration user only sees opportunities it owns. Because the integration user owns no records, Opportunities will appear empty or incomplete in Avid even when the connection succeeds.

  1. Add the integration user to a new Public Group (for example, Avid Integration Access).

  2. Go to Setup > Sharing Settings > Opportunity Sharing Rules and create a rule that shares all opportunities with that public group as Read Only.

    Salesforce emails you when the sharing recalculation completes.

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

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.

Common Sync Errors

Error: NOT_FOUND — "The requested resource does not exist" on OpportunityLineItem/describe
 
This error typically appears when the integration user attempts to discover object metadata via the Describe stream. It indicates the user lacks access to the OpportunityLineItem object (also called Opportunity Products), or the object does not exist in your org.
Cause Resolution
Missing Permission Set assignment Ensure the integration user's Permission Set grants Read access to OpportunityLineItem, Opportunity, and Product2.
Products not enabled in the org If your org does not use Salesforce Products (common in some NPSP configurations), OpportunityLineItem does not exist as a queryable object. Deselect the OpportunityLineItem stream in your Airbyte connection and re-sync.
Wrong Permission Set License Verify the user has the Salesforce API Integration permission set license, not the Salesforce Integration license. The latter blocks access to standard objects.
Important: The Describe stream iterates through every object in your schema and calls the Salesforce describe endpoint for each one. If any single object returns a 404, the entire Describe stream will fail. This means one missing object permission can cause an otherwise healthy sync to error out.

Frequently Asked Questions

  • Can we limit which Salesforce records Avid has access to?

    Yes. You can 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, excluding 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 doesn’t support them on certain core objects like Contact, Account, and Opportunity.

  • Can we control which fields Avid can read?

    Yes. While we recommend granting access to all fields (since it doesn’t materially impact sync performance), you can restrict access to specific fields for compliance or privacy reasons. This can be done using Field-Level Security (FLS) by creating a custom Permission Set and setting those fields to an access level of “None (Hidden)”. This ensures Avid cannot read those fields during synchronization. Many organizations use this approach successfully when certain fields contain legacy or sensitive data.

  • 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. As a result, ongoing API usage is relatively minimal. While actual usage depends on how active your Salesforce instance is, most organizations see between 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 to ensure it doesn’t exceed your available quota. To date, we haven’t encountered quota issues even with very large orgs.

  • 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 Salesforce’s Help Center. However, if you’re unsure, our team can verify object access from Avid’s side once your API-only user is created.

Related articles