Skip to main content

Salesforce via API-Only Connection

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)
    • 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)

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