Salesforce Integration

Connect Salesforce (SFDC) to Rox to sync your CRM objects, power Rox features, and optionally write activities and updates back to Salesforce.

Overview

The Rox Salesforce integration connects to your Salesforce org to read key CRM objects and fields, and—optionally—to write selected activities and field updates back into Salesforce.

• Read (sync): Rox periodically pulls objects such as Account, Contact, Opportunity, and Products into Rox to power account research, insights, and revenue (opportunity) management.

• Write (writeback): When enabled, Rox writes back a set of fields and activities that you control.

Rox uses a pull model: data is synced on a schedule into a managed warehouse. You control which objects are synced and which fields appear in the Rox UI. For a full breakdown of vendors, regions, and data handling, see How the integration works.

The simplest setup: connect with a dedicated Salesforce user that has a full Salesforce license and the System Administrator profile. This single choice gives Rox the read and write access it needs, enables Activities writeback natively, and lets you skip the per-object permission configuration entirely. The rest of this guide is structured around that recommended path, with clearly marked optional steps for organizations that prefer to restrict access.

Before you begin

You will need the following:

• A Salesforce administrator who can:

  • Create and edit Users

  • Create, update, and view Permission Sets

  • Create, update, and view Licenses

• A Rox Organization Admin. The person connecting the integration must be an Organization Admin in Rox. Contact the Rox team to have a user added as an Organization Admin.

• A Salesforce user to connect with. We recommend a dedicated integration user (see Step 1).

Step 1: Create the Rox integration user

We recommend creating a dedicated Salesforce user for Rox. A dedicated user makes it easy to uniquely identify the records Rox reads and writes, and keeps Rox's activity cleanly auditable in Salesforce.

Most important: assign this user a full Salesforce license and the System Administrator profile.

This is the configuration Rox recommends because Activities writeback (Tasks, Events, and email logging) is not supported on the API-only Salesforce Integration license, even with the correct permission sets. A System Administrator profile also means Rox automatically has access to every object and field, so you can skip the permission-set configuration in Restricting Rox's access.

If you've already created a user you'd like to reuse, you can skip ahead—just confirm its license, profile, and API access match the steps below.

Go to Setup → Administration → Users → Users and click New User.

Fill in the new user form:

• User License → Salesforce / Salesforce Integration (recommended)

• Profile → System Administrator (recommended)

• Email

• Username (and set a password)

Once created, the user detail page will look similar to the example below. (Your User License and Profile may differ if you choose to restrict access.)

Finally, make sure API Enabled is selected for the user.

Want to restrict what Rox can access? If your organization prefers a least-privilege setup instead of a System Administrator profile, complete the steps in Restricting Rox's access before connecting, then return here. Note that the API-only Salesforce Integration license does not support Activities writeback—see that section for details.

Step 2: Connect Salesforce to Rox

This is a guided flow: you'll authorize Rox to access Salesforce, then authorize the data ingestion service (Fivetran) to sync your data.

Sign in to Salesforce as the integration user you created in Step 1 (not your personal admin account, unless that is the account you intend to connect). Rox will use whichever Salesforce account is authorized during this flow.

1

Open Rox integration settings

Sign in to run.rox.com as an Organization Admin and click the gear icon in the bottom-left to open Settings → Integrations.

2

Start the Salesforce connection

Find the Salesforce card under Integrations and click Connect.

3

Connect your Salesforce data

In the Connect your Salesforce Data dialog, click Connect SFDC. You'll be redirected to the Salesforce login.

4

Log in to Salesforce

If your integration user is already saved, select it. Otherwise choose Log In with a Different Username and sign in as the integration user.

Connecting a Sandbox? Choose Log In with a Different Username, then:

1. Click Use Custom Domain.

2. Enter your custom domain and click Continue.

After logging in, you'll be redirected back to Rox.

5

Connect Fivetran

Once Rox finishes its initial checks, a Connect Fivetran button appears on the Salesforce card. Click it to authorize data ingestion.

6

Configure the Fivetran connector

On the first screen, click Continue.

Click Authorize to allow Fivetran to connect to your Salesforce instance.

Fivetran reuses your most recent Salesforce login, so you usually won't need to sign in again. If prompted, use the same credentials (and custom domain, if applicable) you used to log in to Rox.

Click Save and Test. Fivetran runs a series of connection tests.

7

Configure Field Mappings

After both connected apps have been installed, click Continue to set up basic field mappings between Salesforce and Rox. These are the basic fields that Rox can cleanly map out-of-the-box. You create custom custom field mappings after finishing setup in Settings.

8

(Optional) Set up Writeback

If you want Rox to write updates to core entities in Rox back to Salesforce, install the SFDC writeback package and follow the onboarding guide in Step 3 (below)

9

(Optional) Test Sync

Optionally, test the Salesforce sync mapping and press Submit once you are ready to finalize the connection. You are done!

Step 3: Enable writeback (optional)

Writeback lets Rox push selected updates and activities back into Salesforce. Rox only writes the fields and activities you configure as an Organization Admin.

Install the Rox managed package

Rox uses a small managed package to set up the custom object required for bi-directional sync. Install it from:

https://login.salesforce.com/packaging/installPackage.apexp?p0=04tUr000000Sg17IAC

The package creates a custom object RoxAI__ID_Mapping__c (label ID Mapping, in the RoxAI namespace) and a Rox Integration User Access permission set with full access to that object. Rox uses this object to resolve entities across Rox and Salesforce for the bi-directional sync.

Make sure to select Install For All Users in Rox to prevent any future access-related issues

Create the activity tracking field

To write Activities (such as logged emails) back to Salesforce, Rox needs a tracking field so it knows which activities have already been written.

Go to the Activity object in Object Manager and create a Text field, 100-character limit, named RoxActivityId.

Create this field on the parent Activity object, not on Task directly. Although Rox writes to the Task object, the field must live on Activity so it automatically flows down to Task.

If your integration user has the System Administrator profile (full Salesforce license), writeback setup is complete. The user already has the object, field, and activity permissions Rox needs—you can stop here.

The remaining steps in this section are only required if your integration user does not use a System Administrator profile (for example, an org that has restricted access via permission sets). Continue below if that applies to you.

Grant writeback permissions (restricted setups only)

If you are not using a System Administrator profile, complete the following so Rox can write back successfully.

1

Assign the Rox Integration User Access permission set

Assign the Rox Integration User Access permission set (installed by the package) to the user connected to Rox. This grants full access to the RoxAI__ID_Mapping__c object used for bi-directional sync.

2

Verify object and field write permissions

Ensure the connected user has write access to every object (Account, Opportunity, etc.) and field you want Rox to write back to.

Navigate to the custom permission set you created for read access (this must be separate from the package's permission set) to add the write permissions.

Open Object Settings and grant Edit access, field by field, to every field Rox should write back to.

3

Assign both permission sets to the user

On the User page, assign both the Rox Integration User Access permission set and your custom permission set to the connected user.

Verify the user's Salesforce license

Activities writeback (Tasks, Events, etc.) is not available on the API-only Salesforce Integration license—even if you grant Edit access in a permission set. The connected user must hold a full Salesforce license for Activities writeback to work. If you need to change the license, see the note below.

Changing a user's license removes their permission sets. When you change a user from Salesforce Integration to Salesforce, all existing permission set assignments are removed, and simply re-assigning them won't restore the permissions correctly—because permission sets are bound to both the user and their license.

Instead, clone the original permission set and assign the cloned version to the user under the new Salesforce license. See Restricting Rox's access for how permission sets are assigned; the only difference is that you assign the cloned set to the user with the new license.

Enable activity permissions

1

Enable Access Activities

In the permission set assigned to the integration user, go to System Permissions and enable Access Activities.

2

Enable task editing

In the same permission set, open Object Settings and search for Tasks.

Enable Create, edit, and delete tasks.

3

Grant field access on the Task object

Open the Task object settings in the permission set.

Give Edit access to the fields you want Rox to write—especially the RoxActivityId field you created earlier, which Rox uses to map IDs.

When you're done, confirm with the Rox CRM Mappings page after about half an hour (let the re-sync happen), that the integration user's credentials have the write permissions needed for all the objects and fields you expect.

Connected before 2025-05-31? If your Salesforce integration was connected before this date, you must re-authenticate so Rox receives a new token that includes write permissions. See Troubleshooting & re-authentication.

Lead creation & resolution

Rox can automatically create new leads in Salesforce or match contacts to existing leads, keeping your CRM up to date without manual effort.

How it works

When processing a contact, Rox queries Salesforce directly for an existing lead by email address:

• Match found: Rox associates the activity with the existing lead.

• No match found: Rox creates a new lead in Salesforce.

How to enable

Go to Settings → CRM → Activities to configure lead creation and resolution.

Lead creation and resolution is currently supported for email writeback only.

Restricting Rox's access (optional)

You can skip this section if you connected with a System Administrator profile. That profile already grants Rox read access to every object and field.

We recommend granting Rox access to all objects and fields for the smoothest experience. The steps below are for organizations that need to limit Rox to a specific set of objects and fields. If you restrict access, use this section to grant the complete access Rox requires.

If granted access doesn't show up in the Rox UI: after you grant access to an object or field, it should appear in the Rox CRM UI. If it doesn't, please reach out to the Rox team so we can help reconcile the permissions.

1

Assign the Permission Set License

On the integration user's detail page, scroll to Permission Set License Assignments.

Click Edit Assignments, select Salesforce API Integration, and save.

2

Create a permission set

Go to Setup → Administration → Users → Permission Sets.

Click New, fill in the details, and leave License set to None. Click Save.

From the permission set list, open the set you just created (use pagination if needed).

You'll see the permission set's configuration sections.

3

Grant object & field permissions

Click Object Settings. Use the Find Settings search bar to locate each object and grant the required permissions.

Grant access to the following objects (recommended to allow all fields). At minimum, the fields listed are required:

Account

ID · Name · Website · Industry · Annual Revenue · Number of Employees · Billing Country · Billing State · Billing City · Billing Street · Billing Postal Code · SYSTEM_MODSTAMP

Contact

ID · Name · Email · Account ID · Phone · Title · SYSTEM_MODSTAMP

Opportunity

ID · Name · Amount · Stage Name · Close Date · Next Step · Account ID · SYSTEM_MODSTAMP

Also grant access to these objects:

• OpportunityLineItem

• Product (Product2)

• Lead

• Task

• Event

• Any other custom objects you need Rox to sync

For each object, apply the permissions shown below:

Verify your access. Log in to Salesforce Workbench as the user you're connecting to Rox. Confirm the objects are visible, and use SOQL to verify the fields are queryable.

4

Assign system permissions

In the permission set, open System Permissions and enable:

• View Setup and Configuration

• Download AppExchange Packages (required to install the Rox package for writeback)

5

Assign the permission set to the user

Go to Setup → Administration → Users → Users, open the integration user, and click Edit Assignments under Permission Set Assignments.

Select the permission set you created and click Save.

The integration user is now ready. Return to Step 2: Connect Salesforce to Rox.

Troubleshooting & re-authentication

If your Salesforce connection shows an error, requires action, or needs refreshed credentials (for example, an expired refresh token or revoked access), re-authenticate as follows.

1

Open the Salesforce integration settings

Open Settings → Integrations and find the Salesforce integration.

2

Open the integration settings menu

Regardless of the integration's state (Error, Action Required, or Ready), click the settings icon next to the Salesforce integration to open its settings.

3

Re-authenticate Salesforce

Under the Authentication tab, click Re-authenticate and complete the Salesforce connection flow. This updates Rox with the latest credentials for your Salesforce user and resolves expired-token and revoked-access errors.

4

Confirm the updated state

After successful authentication, you're redirected back to the Salesforce settings page and the integration enters the Action Required state. (If it doesn't update immediately, refresh the page—it can take a few seconds.)

5

Re-authenticate Fivetran

Click Action Required. In the dialog, you'll see that Salesforce is already connected to Rox—you just need to re-authenticate with Fivetran using the same updated credentials. Click Map Key Values.

6

Save and test the connection

Click Re-authorize connection, then Save and Test. You'll be redirected back to Rox, and the Salesforce connection should now show Connected. Refresh the page if the status doesn't update right away.

Common issues

OAUTH_APPROVAL_ERROR_GENERIC

If you see an error with the code OAUTH_APPROVAL_ERROR_GENERIC:

This usually means Rox's app is being blocked in your list of OAuth Connected Apps. Go to Connected Apps OAuth Usage and check whether the RoxAI app is installed (alongside Fivetran). If it isn't, approve or install it and retry the connection.

How the integration works

The Rox Salesforce integration uses a pull model: once connected, Salesforce data is periodically synced into managed warehouse tables. You can customize which objects are synced and which fields appear in the Rox UI. Writeback pushes only the fields you configure as an Organization Admin.

Components & hosting

Component	Vendor	Region
Warehouse	Snowflake	United States
Ingestion	Fivetran	United States
Rox application (frontend)	Vercel	United States
Rox application (backend)	AWS	United States

Data handling & privacy

Category	Description
Data accessed	The objects and fields the Salesforce integration user is permitted to sync. Fields can be selectively removed.
Data written	The fields the integration user has access to and that an Organization Admin has configured for writeback in Rox.
Purpose	Powering Rox features such as account research, insights, and revenue (opportunity) management.
PII minimization	Only the required fields the integration user has permission to access are used.
Retention	Synced data is retained only for operational and feature purposes, and is deleted upon user or tenant disconnection.
Deletion	On disconnection or a data-removal request, all synced data can be purged per Rox's data lifecycle policies.