> For the complete documentation index, see [llms.txt](https://docs.rox.com/development/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.rox.com/development/admin-guide/integrations/salesforce/syncing-with-salesforce.md).

# Syncing with Salesforce

The Rox Salesforce integration brings CRM records into Rox so reps can work with their Accounts, Contacts, and Leads, use campaign information in outreach, and log completed sequence activities back to Salesforce. Admins choose which data to sync and configure the fields and activities Rox writes back.

Access to Salesforce data in Rox follows Rox account assignment rules. Salesforce sharing rules and role hierarchies are not mirrored in Rox, so account access should be reviewed as part of setup.

This page explains the integration's behavior. For setup instructions, see [Configuring Salesforce Integration + Writeback](https://docs.rox.com/development/product/organization-level-configurations/configuring-salesforce-integration-+-writeback). After setup, manage the connection under **Settings → Integrations → Salesforce**.

### What you can do

* Bring Salesforce Accounts, Contacts, and Leads into Rox for prospecting and outreach.
* Map standard and custom fields on supported objects.
* Use Campaigns and Campaign Members as context when coordinating sequences with marketing activity.
* Write configured field updates back to Salesforce, including Account updates.
* Log supported sequence activities as Salesforce Tasks and associate them with Contacts or Leads.
* Enable Contact or Lead creation during activity writeback. People List creation is also available where enabled for your organization.

These capabilities depend on the objects, mappings, and writeback settings enabled for your organization. Connecting Salesforce does not enable every writeback option automatically.

### How data moves between Salesforce and Rox

The integration includes periodic synchronization, as well as user-initiated pushes in-product. **Periodic syncs require the installation of a managed package to enable writeback.** Otherwise, the connection will be read-only. User-initiated pushes live within People Lists (Contact or Lead). They are described in more detail below.

Here is a summary:

| Action                         | What it does                                                                                                                                                                                                                                                                                                                                                                                           | Where it is configured                     |
| ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------ |
| **Read Salesforce data**       | Brings selected objects and mapped fields into Rox on a schedule. This applies to: Accounts, Contacts, Leads, Opportunities, Campaigns, CampaignMembers                                                                                                                                                                                                                                                | Organization integration settings          |
| **Write Salesforce data**      | Sends configured Rox field values back to Salesforce. This includes creating new objects with those values if matching objects are not found. Contact and Lead writeback currently only happens when Activities are synced (below).                                                                                                                                                                    | Organization integration settings          |
| **Log activities**             | <p>Creates Salesforce Tasks for enabled sequence activity types (email, call, LinkedIn) with standard metadata and optionally also writes configured fields to the associated Contact or Lead.<br><br>We give an option whether to create a new Contact or Lead if not found. For Contacts, if no associated Account is found, it will not create a new Account, nor will it create a new Contact.</p> | Organization integration settings          |
| **Contact and Lead list push** | Bulk creates new Contacts and Leads or updates existing ones                                                                                                                                                                                                                                                                                                                                           | People product (Contact List or Lead List) |

#### Scheduled sync

Rox pulls Salesforce data into a managed warehouse for use in the application. An Organization Admin configures the objects and fields included in the integration and the updates Rox can send back. This is done in Settings → Integrations → Salesforce. The default sync interval is 30 minutes, and the sync interval for Activities and Contact/Lead engagement status updates is 5 minutes.

#### People List writeback

Where People List writeback is enabled (Contacts or Leads), a user can add a lookup column to a list to find a matching Contact or Lead in Salesforce. Then, the user can add a Create column or an Update column that trigger depending on whether a matching record was found. The Create and Update columns run when the column is added and again as new records enter the list.

Importantly, People List writeback is user-configured, whereas our background syncs are automatic.

#### Managed package

As mentioned above, a managed package must be installed to enable writeback. Installing the package makes these schema additions to the customer's org:

1. One custom object: `RoxAI__ID_Mapping__c`
   1. Fields: `RoxAI__SFDC_ID__c`, `RoxAI__Rox_ID__c`, `RoxAI__Object_Type__c`
2. A `RoxAI__Rox_ID__c` attribution field on Account, Contact, Lead, and Opportunity
3. A `RoxAI__RoxActivityId__c` field on Task

Do not delete or modify these objects/fields.

### Supported Salesforce objects

Account and User are required for the integration. Additional supported objects are selected during onboarding. **Once an object has been synced, it cannot be removed through the synced-object configuration.**

| Object              | Read Scope                                                 | Write Scope                            | **Write Path**           | **Can Create New?**       |
| ------------------- | ---------------------------------------------------------- | -------------------------------------- | ------------------------ | ------------------------- |
| **Account**         | Any mapped field                                           | Any mapped field                       | Sync                     | No                        |
| **Contact**         | Any mapped field                                           | Only certain properties                | Activity writeback, List | Yes                       |
| **Lead**            | Prospect records                                           | Only certain properties                | Activity writeback, List | Yes                       |
| **Opportunity**     | Any mapped field, requires Rox support                     | Any mapped field, requires Rox support | Sync                     | Yes, requires Rox support |
| **Task**            | Only certain properties, only activities originated in Rox | Only certain properties                | Activity writeback       | Yes                       |
| **Campaign**        | Any mapped fields                                          | Not supported                          | N/A                      | N/A                       |
| **Campaign Member** | Any mapped fields                                          | Not supported                          | N/A                      | N/A                       |
| **User**            | Only certain properties                                    | Not supported                          | N/A                      | N/A                       |

Opportunity read/sync is available in Enterprise deployments. Confirm availability for your organization during setup. Opportunity writeback is not generally available, and Rox does not associate sequence Tasks with Opportunities.

Salesforce Events are not read by this integration, and Event writeback is not supported. Calendar and meeting context comes from the Rox calendar integration, not from SFDC.

#### Custom fields and custom objects

Custom fields on supported objects can be mapped between Salesforce and Rox. Mapping instructions can be found here: <https://docs.rox.com/development/product/organization-level-configurations/configuring-salesforce-integration-+-writeback#after-onboarding-manage-crm-mappings>

Standalone custom objects and junction objects are not yet supported out of the box. If your workflow depends on them, review the requirements with your Rox team to determine whether a custom implementation is possible.

### Entity resolution / matching logic

Rox matches records to determine how to connect records in Rox with records in the CRM, as well as when it should attempt to create a new record versus update an existing one. Once a match is established, the records remain linked by Salesforce ID.

Rox matches objects based on the following rules:

| Object              | Match Properties                                                              |
| ------------------- | ----------------------------------------------------------------------------- |
| **Account**         | `domain`                                                                      |
| **Contact**         | `email, account_id`                                                           |
| **Lead**            | `name, company_name, email, phone, website` using waterfall logic             |
| **Opportunity**     | None, new Opportunities are created and linked the first time they are seen   |
| **Task**            | None, new Tasks are created and linked the first time they are seen           |
| **Campaign**        | None, new Campaigns are created and linked the first time they are seen       |
| **Campaign Member** | None, new CampaignMembers are created and linked the first time they are seen |
| **User**            | `email`                                                                       |

#### Accounts and people with more than one possible match

Review your data model with your Rox team if:

* Several Account records share the same domain (`Website`).
* One company is represented by multiple Accounts with different domains.
* The same person appears under several Accounts or email addresses.
* An email address is shared across Contact records associated with different Accounts.
* Your Salesforce organization uses custom duplicate or matching rules.

### How access works

Two settings determine how Salesforce data becomes available in Rox: the integration user's Salesforce permissions and your organization's Rox account assignments.

#### Integration user

The integration authenticates through a dedicated Salesforce integration user using OAuth. Read and write permissions are based on that integration user. Review to make sure that it has the proper permissions across all objects to sync.

#### Account assignment in Rox

An admin configures account assignment using Salesforce Account-to-User fields, such as Account Owner or custom owner fields. A user can have multiple owner fields, combined with OR logic, and one additional account filter. A default rule applies to users without their own owner fields or filter. If neither the user-specific configuration nor the applicable default rule grants access, the user sees no Accounts.

Account assignment governs visibility of Accounts and their associated Contacts and activity in Rox. Review the assignments with representative users before rollout, including users who do not have an explicit assignment configuration.

For example, access granted through a Salesforce sharing rule does not automatically grant the same access in Rox. The Account must also be accessible under the user's Rox assignment configuration.

### Activity writeback

Activity writeback records outreach completed in Rox as Salesforce Tasks. When an enabled sequence activity is completed, Rox creates a Task and writes the configured activity fields to the associated Contact or Lead.

Admins can enable these activity types independently:

* Email
* Phone call
* LinkedIn connection request
* LinkedIn message

The **Mark Rox-created activities** setting writes `Rox` to a selected Task field, making those activities easier to identify in Salesforce reports and filters.

Rox uses two Task fields to associate the activity:

| Task field | What Rox writes                                             |
| ---------- | ----------------------------------------------------------- |
| `WhoId`    | The matched Contact or Lead                                 |
| `WhatId`   | The associated Account for a Contact; left empty for a Lead |

An admin can decide whether, activity writeback does creates a new Contact or Lead record if it cannot be found in SFDC.

If new Contact or Lead creation is disabled and Rox cannot match the person, it creates the Task without a person association: the Task's `WhoId` is empty. If an Account is known, the Task may still be associated with it through `WhatId`.

If new Contact or Lead creation and new Lead is enabled, Rox creates the missing person record and associates the Task with it. The follow fields are written by default:

* For Contacts: `FirstName`, `LastName`, `Email`, `Phone`, `AccountId`
* For Leads: `FirstName`, `LastName`, `Company`, `Email`, `Phone`, `LeadSource`

The following properties are available to be mapped to SFDC custom fields:

* For Contacts and Leads: `Added to Sequence By`, `Currently in Sequence`, `Sequence Name`, `Sequence Status`, `Sequence Step Number`, `Sequence Step Type`
* For Tasks: `Rox Activity Id`, `Call AI Analysis`, `Call Date`, `Call Duration`, `Call Transcript`, `Sequence Name`, `Sequence Step Number`
  * For `Call Transcript`, it is recommended to map this to the standard `Description` field in SFDC to get around character limitations for custom fields in the Task object.

Example Task written back:

```jsx
{
  "Subject": "Phone Call",
  "Description": "Rep: Hi, is this Jane?\nProspect: Speaking...\n[full formatted transcript]",
  "Status": "Completed",
  "ActivityDate": "2026-09-17",
  "CallType": "Outbound",
  "CallDisposition": "Connected - Meeting Booked",
  "Type": "Phone Call",
  "TaskSubtype": "Call",
  "WhoId": "003XXXXXXXXXXXXAAA",
  "WhatId": "001XXXXXXXXXXXXAAA",
  "OwnerId": "005XXXXXXXXXXXXAAA",
  "RoxAI__RoxActivityId__c": "call_9f2c1a7b-...",
  "Rox_Call_Duration__c": 372,
  "Rox_Call_Date__c": "2026-09-17T18:42:05Z",
  "Rox_Call_Sentiment__c": "Positive",
  "Activity_Source__c": "Rox"
}
```

Example Contact written back:

```jsx
{
  "Id": "003XXXXXXXXXXXXAAA",
  "Title": "VP of Engineering",
  "Phone": "+1-415-555-0199",
  "Rox_Sequence_Name__c": "Q3 Enterprise Outbound",
  "Rox_Sequence_Status__c": "Active",
  "Rox_Sequence_Step_Number__c": 3,
  "Rox_Sequence_Step_Type__c": "Call",
  "Rox_Currently_In_Sequence__c": true,
  "Added_To_Sequence_By__c": "005XXXXXXXXXXXXAAA",
  "Rox_Contact_Stage__c": "Meeting Booked"
}
```

#### Engagement Status Writeback

We can write back the following statuses to an engagement field on both Contact and Lead records. The engagement status field should be a picklist. The following engagement status fields can be mapped:

| Name             | Description                                                                                                              |
| ---------------- | ------------------------------------------------------------------------------------------------------------------------ |
| Not Started      | Written when a Contact or Lead is added to a Sequence                                                                    |
| Active           | Written when the first task is completed for the Contact or Lead                                                         |
| Completed        | Written when all steps are completed for the Contact or Lead, and there is no response                                   |
| Email replied    | Written when the Contact or Lead responds to an email                                                                    |
| LinkedIn replied | Written when the Contact or Lead responds to a LinkedIn message                                                          |
| Call answered    | Written when the Contact or Lead answers a call                                                                          |
| Meeting booked   | Written when a meeting is booked, as detected through a synced calendar or an email response indicating a booked meeting |

Note that if new Contact or Lead creation and new Lead is enabled, a new Contact or Lead will be created automatically if it doesn’t already exist. This usually happens when Contacts or Leads are added to the Sequence. This is the same setting that is used by general Activity writeback above.

### Limitations and setup considerations

* **Opportunities:** Read/write is available via enterprise deployments via special configuration. Please contact your Rox team to enable. Sequence Tasks are not associated with Opportunities via WhatId.
* **OpportunityContactRole, OpportunityStage:** Please contact your Rox team if you need support.
* **Events:** Salesforce Event read and writeback are not supported. Calendar events are synced through the Rox calendar integration.
* **Account creation:** Rox does not automatically create accounts by default. Please contact your Rox team if you would like to enable this.
* **Entity resolution:** Review your matching rules with the Rox team to avoid creating duplicate Contacts.
* **Custom objects:** Review custom objects, junction objects, and ambiguous Account or person matches with your Rox team.

#### Formula fields

Changes in a calculated value may not update the record modification timestamp used by sync, so formula-field changes may not appear reliably in Rox. The documented workaround is to copy the result into a stored Salesforce field and map that field into Rox. Configure the automation to update the stored value whenever the relevant inputs change. Confirm coverage for formulas that depend on related records or time.

### Data storage and handling

Rox uses Fivetran to ingest Salesforce data into a managed Snowflake warehouse. The integration reads data within the integration user's permissions and the configured object and field mappings.

Include your data residency, retention, and deletion requirements in the setup review. Confirm the applicable policies with your Rox team before connecting Salesforce, particularly if your organization has requirements for previously synced data after a mapping is removed or the integration is disconnected.