> ## Documentation Index
> Fetch the complete documentation index at: https://docs.benefitflow.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Salesforce Integration: Security & Permissions

> What BenefitFlow reads, stores and writes in Salesforce, the permissions it needs, network details for allowlisting, and how it uses your API allowance.

For Salesforce admins and security reviewers. Setup steps live in [Setup Instructions](https://docs.benefitflow.com/knowledge-base/salesforce-integration-setup-instructions.md).

## At a glance

| | |
| - | - |
| **Connection** | OAuth 2.0, two ways. **Automatic:** a Salesforce admin authorizes BenefitFlow's Connected App in one click. **Manual:** your team creates its own Connected App and enters its key and secret in BenefitFlow. Both request the same scopes |
| **APIs used** | REST for records. SOAP for a read-only duplicate check. Metadata and Tooling APIs for read-only setup checks |
| **Package to install** | None |
| **Custom fields required** | None |
| **Deletes** | Never. BenefitFlow doesn't delete records in Salesforce |

## Object access

| Object | Read | Create / update | Why |
| - | - | - | - |
| **Account** | Yes | Yes | Match existing companies, add new ones, keep fields current |
| **Contact** | Yes | Yes | Match existing people, add new ones, keep fields current |
| **Lead** | Yes | Yes | Check for an existing lead before creating a contact. Push leads when Lead is your target object |
| **User** | Yes | No | Look up active users so records can be assigned an owner |
| **Opportunity** | Yes | No | Weekly read of standard fields |
| **Duplicate, matching and validation rules** | Yes | No | So BenefitFlow doesn't push records that break your rules |

BenefitFlow also reads each object's field list so your admin can map fields in Integration Settings.

When BenefitFlow writes a record, it can set the record owner, the parent account for contacts, and the parent account for child accounts.

## What BenefitFlow stores

To match records, BenefitFlow keeps a copy of your accounts, contacts, active users and up to 100,000 opportunities. The copy includes every field the integration user can see. That's the main reason to connect as a dedicated integration user with only the access below.

Connection tokens are stored in our database, which is encrypted at rest.

A small number of BenefitFlow administrators can view synced records to support your account.

## System permissions

The connecting user needs:

1. **API Enabled** (system permission)
2. Read and create/edit on the objects in the table above
3. OAuth scopes on your app. BenefitFlow requests **api** (read and write records) and **refresh\_token** (stay connected without logging in again). If you create your own app, the manual setup steps also select the identity URL scope

BenefitFlow also reads your duplicate and validation rules so it can check records before pushing them. No extra permission is required for this. If your org blocks it, syncing and pushes still work. BenefitFlow just can't check records against your rules first, so Salesforce rejects any record that breaks one and it shows in the Activity Log.

### Hiding sensitive fields

You can hide fields from the integration with field-level security. BenefitFlow skips hidden fields when it reads.

Keep these visible:

1. **Website, Email, Billing City and Billing State.** BenefitFlow matches on them. Hiding them causes errors or duplicate records.
2. **Every field BenefitFlow writes to.** That includes default fields like Title and Mailing State, not only fields your admin mapped. If one is hidden or read-only, the write fails for that record.
3. **Standard Opportunity fields.** BenefitFlow reads a fixed set, so hiding one stops the weekly Opportunity read.

## Recommended: a dedicated integration user

Connect as a dedicated integration user, not a person's own login. The connection then keeps working when someone leaves, and you control exactly what it can see and change.

1. Create a user for BenefitFlow.
2. Give it a permission set with API Enabled and the object access above. Nothing more.
3. Hide any fields you don't want shared, keeping the ones listed above.
4. Log out of Salesforce, log back in as the integration user, then connect from BenefitFlow.

A Salesforce admin can revoke BenefitFlow's access at any time from your org, and access stops immediately. You can also disconnect in BenefitFlow and deactivate the integration user.

## Network and allowlisting

All calls to your Salesforce org come from BenefitFlow's servers, not from users' browsers. The only browser step is the one-time login during setup.

| | |
| - | - |
| **Outbound IP address** | `34.228.132.49`. One static address, not a range, and it doesn't rotate |
| **OAuth callback URL** | `https://prod-api.benefit-flow.com/crm-integration/callback` |

If your org restricts API access by IP, adding this address is all you need.

## API usage

What BenefitFlow calls, and when:

1. **First sync.** Reads your accounts and contacts in pages of 2,000 and stores a copy so it can tell you which records you already have.
2. **After that.** Up to 4 times a day, reads only accounts and contacts changed in the last 5 days. It skips the read when nothing has changed.
3. **Daily.** Refreshes active users, record counts, field lists and your duplicate and validation rules.
4. **Weekly.** Reads up to 100,000 opportunities, standard fields only.
5. **When your team pushes records.** Looks up only the records being pushed, then creates or updates them, up to 200 records per API call.
6. **Scheduled enrichment.** If your admin sets up enrichment, BenefitFlow checks every 3 hours and updates the fields you mapped.

**If you hit your API limit.** Records in a push that Salesforce rejects are marked failed in the Activity Log so you can push them again. Scheduled enrichment updates try once more about 20 minutes later.

BenefitFlow doesn't read your org's remaining daily API allowance, so it won't slow down on its own as you get close to the limit.

## How records are matched

By default, BenefitFlow matches on values your org already has, so you don't need a BenefitFlow ID field:

1. **Accounts** match on website domain. Child accounts also match on billing city and state.
2. **Contacts and leads** match on email.

By default, a Salesforce account without a website can't be matched, so BenefitFlow may create a duplicate of it. Check how many of your accounts are missing a website before your first push.

BenefitFlow can change the matching fields for your org. Ask your Customer Success Manager.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.