# Salesforce Integration

## 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](#how-the-integration-works).

{% hint style="success" %}
**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.
{% endhint %}

## 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)).

## 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.

{% hint style="info" %}
**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](#restricting-roxs-access-optional).

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.
{% endhint %}

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

<figure><img src="/files/lZ7p83REpFmPWXDbtJKs" alt=""><figcaption></figcaption></figure>

Fill in the new user form:

* **User License** → **Salesforce** *(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.

<figure><img src="/files/Mh2TBU7WMOsmnREnBHuS" alt=""><figcaption></figcaption></figure>

{% hint style="info" %}
**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](#restricting-roxs-access-optional) **before** connecting, then return here. Note that the API-only Salesforce Integration license does not support Activities writeback—see that section for details.
{% endhint %}

## 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.

{% hint style="warning" %}
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.
{% endhint %}

{% stepper %}
{% step %}

## Open Rox integration settings

Sign in to [run.rox.com](https://run.rox.com/) as an Organization Admin and click the **gear icon** in the bottom-left to open **Settings → Integrations**.

<figure><img src="/files/yFm2SMQR9HEkMRrGSziY" alt=""><figcaption></figcaption></figure>
{% endstep %}

{% step %}

## Start the Salesforce connection

Find the **Salesforce** card under Integrations and click **Connect**.

<figure><img src="/files/y7eEyPLD6EMyYFvS6bma" alt=""><figcaption></figcaption></figure>
{% endstep %}

{% step %}

## Connect your Salesforce data

In the **Connect your Salesforce Data** dialog, click **Connect SFDC**. You'll be redirected to the Salesforce login.
{% endstep %}

{% step %}

## 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.

{% hint style="info" %}
**Connecting a Sandbox?** Choose **Log In with a Different Username**, then:

1. Click **Use Custom Domain**.
2. Enter your custom domain and click **Continue**.
   {% endhint %}

After logging in, you'll be redirected back to Rox.
{% endstep %}

{% step %}

## Connect Fivetran

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

<figure><img src="/files/2Vdxa2KpfrL3R4Oq1GfO" alt=""><figcaption></figcaption></figure>

<figure><img src="/files/jkSc7khW9YsQ45p5FZ8j" alt=""><figcaption></figcaption></figure>
{% endstep %}

{% step %}

## 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.

<figure><img src="/files/TZDw9S5mc6q9sUaJFWKE" alt=""><figcaption></figcaption></figure>

{% endstep %}

{% step %}

## Confirm the connection

When the tests pass, you're routed back to Rox and the **Salesforce** card shows a **Connected** status. You're all set.
{% endstep %}
{% endstepper %}

## 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.

{% hint style="info" %}
Make sure to select `Install For All Users` in Rox to prevent any future access-related issues
{% endhint %}

<figure><img src="/files/WQ2Nuk3YCmELWV67t9HT" alt=""><figcaption></figcaption></figure>

<figure><img src="/files/6LqAXjzjK1lVRszVJ7B4" alt=""><figcaption></figcaption></figure>

### 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`**.

{% hint style="warning" %}
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**.
{% endhint %}

<figure><img src="/files/MharI80enxbYhcuziAjL" alt=""><figcaption></figcaption></figure>

{% hint style="success" %}
**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.
{% endhint %}

### Grant writeback permissions (restricted setups only)

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

{% stepper %}
{% step %}

## 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.

<figure><img src="/files/ZPTEBGDtmoz8P0HNPN6p" alt=""><figcaption></figcaption></figure>
{% endstep %}

{% step %}

## 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.
{% endstep %}

{% step %}

## 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.

<figure><img src="/files/6EPXn2OMPxbeONfHfRUh" alt=""><figcaption></figcaption></figure>

{% endstep %}
{% endstepper %}

#### 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.

{% hint style="danger" %}
**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](#restricting-roxs-access-optional) for how permission sets are assigned; the only difference is that you assign the cloned set to the user with the new license.
{% endhint %}

#### Enable activity permissions

{% stepper %}
{% step %}

## Enable Access Activities

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

<figure><img src="/files/gwZR7N7Y51TqbfP6Mn4b" alt=""><figcaption></figcaption></figure>

<figure><img src="/files/xN0eMBoDfwJUFGRgaPxv" alt=""><figcaption></figcaption></figure>

<figure><img src="/files/qPJ3aoCQj0Ae9FAf7rOD" alt=""><figcaption></figcaption></figure>
{% endstep %}

{% step %}

## Enable task editing

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

Enable **Create, edit, and delete tasks**.

<figure><img src="/files/ny4GU8TXoDkYCZky8YSd" alt=""><figcaption></figcaption></figure>
{% endstep %}

{% step %}

## 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.

<figure><img src="/files/X257p3gnwlZMTDyabT9O" alt=""><figcaption></figcaption></figure>

<figure><img src="/files/UHW0FRldxXY6FcK7lfbV" alt=""><figcaption></figcaption></figure>
{% endstep %}
{% endstepper %}

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.

{% hint style="warning" %}
**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](#troubleshooting-and-re-authentication).
{% endhint %}

## 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.

{% hint style="info" %}
Lead creation and resolution is currently supported for **email writeback** only.
{% endhint %}

## Restricting Rox's access (optional)

{% hint style="success" %}
**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.
{% endhint %}

{% hint style="warning" %}
**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.
{% endhint %}

{% stepper %}
{% step %}

## 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.

<figure><img src="/files/IcePUcziyeLFeo362X5K" alt=""><figcaption></figcaption></figure>
{% endstep %}

{% step %}

## 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.
{% endstep %}

{% step %}

## 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:

<details>

<summary>Account</summary>

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

</details>

<details>

<summary>Contact</summary>

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

</details>

<details>

<summary>Opportunity</summary>

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

</details>

**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:

{% hint style="info" %}
**Verify your access.** Log in to [Salesforce Workbench](https://workbench.developerforce.com/login.php) as the user you're connecting to Rox. Confirm the objects are visible, and use SOQL to verify the fields are queryable.
{% endhint %}
{% endstep %}

{% step %}

## 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)
  {% endstep %}

{% step %}

## 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](#step-2-connect-salesforce-to-rox).
{% endstep %}
{% endstepper %}

## 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.

{% stepper %}
{% step %}

## Open the Salesforce integration settings

Open **Settings → Integrations** and find the **Salesforce** integration.
{% endstep %}

{% step %}

## 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.
{% endstep %}

{% step %}

## 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.
{% endstep %}

{% step %}

## 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.)
{% endstep %}

{% step %}

## 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**.
{% endstep %}

{% step %}

## 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.
{% endstep %}
{% endstepper %}

## Common issues

### OAUTH\_APPROVAL\_ERROR\_GENERIC

If you see an error with the code **`OAUTH_APPROVAL_ERROR_GENERIC`**:

<figure><img src="/files/xjhkNYvdli6q7tBxhxXc" alt=""><figcaption></figcaption></figure>

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.

<figure><img src="/files/P2IWUrZMOrBh1VUIYgyN" alt=""><figcaption></figcaption></figure>

## 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.         |


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.rox.com/development/engineering/docs/rox-enterprise-integrations/salesforce-integration.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.