> For the complete documentation index, see [llms.txt](https://integrations.drivetrain.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://integrations.drivetrain.ai/integration-guide/readme/crm/integrating-with-salesforce.md).

# Integrating with Salesforce

Connect Salesforce to Drivetrain quickly—no provisioning or support required.

You connect Salesforce yourself by signing in from Drivetrain, then choose which objects and reports to sync.

## Before you start

* **In Drivetrain:** an admin role (or a role with the **Connect a data source** action).
* **Salesforce edition with API access:** Enterprise, Performance, Unlimited or Developer. Professional edition needs Salesforce's API add-on.
* **A Salesforce user to connect with.** Drivetrain syncs only what this user can see, so check its profile or permission set:

| Permission                                                                                                                           | Why Drivetrain needs it                                        |
| ------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------- |
| **API Enabled**                                                                                                                      | Every sync uses the Salesforce API                             |
| **View Setup and Configuration**                                                                                                     | Drivetrain reads your org's remaining API quota before syncing |
| **Read** on each object you'll sync (at least **Accounts**, **Leads**, **Opportunities**), plus field-level **Read** on their fields | Hidden objects or fields sync empty                            |
| **View All Users**                                                                                                                   | Syncs the **User** object                                      |
| **View All Data**, or sharing rules that let the user see the records                                                                | A user that owns no records syncs empty tables                 |
| **Run Reports**, and access to the report folders                                                                                    | Only if you sync reports                                       |

No create, edit or delete permission is needed: Drivetrain only reads. It requests Salesforce's `api` and `refresh_token` OAuth scopes. The `api` scope allows whatever the user's permissions allow, so a read-only user keeps the connection read-only.

{% hint style="info" %}
**Where to find these:** Setup > **Users** > **Profiles** > your profile. In the enhanced profile view they're under **System Permissions** and **Object Settings**; in the original view, under **Administrative Permissions**, **General User Permissions** and **Standard Object Permissions**. **Opportunity History** and **Opportunity Field History** follow access to Opportunities. Field history fills only for fields you track in Object Manager > **Opportunity** > **Fields & Relationships** > **Set History Tracking**.
{% endhint %}

<figure><img src="https://4220329029-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FmBZR0D9lq6jrI895OuOU%2Fuploads%2Fgit-blob-313b66e6a6867420f30e708db881103d38fa6727%2FSalesforce%20Integration%20(6).gif?alt=media" alt=""><figcaption></figcaption></figure>

## Step 1: Connect Salesforce

1. Go to the **Data** page and click the **+** icon at the top of the **Data** panel (or **Add data source** if nothing is connected yet).
2. Select **Salesforce** and click **Login to connect**.
3. The tab opens the Salesforce login page. Log in as the user above, complete MFA if prompted, and allow access.
4. You return to Drivetrain, and Salesforce appears in the **Data** panel. Nothing syncs until you choose data in Step 2.

<figure><img src="https://4220329029-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FmBZR0D9lq6jrI895OuOU%2Fuploads%2Fgit-blob-4ee9fa255f517983f3f9e26e906565c1ad012e23%2FSalesforce%20Integration.gif?alt=media" alt=""><figcaption></figcaption></figure>

<figure><img src="https://4220329029-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FmBZR0D9lq6jrI895OuOU%2Fuploads%2Fgit-blob-75385c75cfa4a0fb26b9466afe2a3cc9439c83a0%2FSalesforce%20Integration%20(3).gif?alt=media" alt=""><figcaption></figcaption></figure>

{% hint style="warning" %}
**If Salesforce blocks the login** (for example `OAUTH_APPROVAL_ERROR_GENERIC`, or a message that the app must be installed), your org doesn't allow uninstalled connected apps. Since September 2025 this is Salesforce's default. A Salesforce admin can fix it either way:

* **Install the app (recommended):** Setup > Quick Find **OAuth** > **Connected Apps OAuth Usage**, find the Drivetrain app (it appears after the first login attempt), click **Install** and confirm. Then try again.
* **Or allow the user:** give the connecting user's profile or permission set **Approve Uninstalled Connected Apps** (or **Use Any API Client** if your org has API Access Control turned on). The standard System Administrator profile has it by default.
  {% endhint %}

## Step 2: Choose what to sync

Click **Add data** on the Salesforce connection (or the three dots next to it > **Add data**). In **Import from**, choose **Objects** or **Reports**.

<figure><img src="https://4220329029-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FmBZR0D9lq6jrI895OuOU%2Fuploads%2Fgit-blob-284b4542c3464f4a247084a5d37f1208ee5e5693%2FSalesforce%20Integration%20(2).gif?alt=media" alt=""><figcaption></figcaption></figure>

### Objects

Use objects for full, unfiltered tables.

1. Select **Objects**, search for the objects you want and move them to **Selected**. You can pick any standard or custom object the user can see.
2. Click **Add**.

**Account**, **Lead**, **Opportunity** and **User** can't be removed once selected.

<figure><img src="https://4220329029-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FmBZR0D9lq6jrI895OuOU%2Fuploads%2Fgit-blob-b0defb9166a6e9a984cb7f276356e7a2d8cec203%2FSalesforce%20Integration%20(5).gif?alt=media" alt=""><figcaption></figcaption></figure>

### Reports

Use a report when you already filter and shape the data in Salesforce.

1. In Salesforce, open the report and copy its Lightning link: `https://<your-org>.lightning.force.com/lightning/r/Report/<report-id>/view`. Salesforce Classic links are rejected.
2. In Drivetrain, select **Reports**, paste the link in **Paste Salesforce report link**.
3. Optional: in **Unique column (optional)**, enter the name of a column that's unique on every row (for example **Opportunity ID**), as it appears in the report.
4. Click **Add**.

<figure><img src="https://4220329029-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FmBZR0D9lq6jrI895OuOU%2Fuploads%2Fgit-blob-2191c235639ae55ece82e7d76040fa50c12cfc9b%2FSalesforce%20Integration%20(4).gif?alt=media" alt=""><figcaption></figcaption></figure>

**Reports over 2,000 rows:** Salesforce returns at most 2,000 report rows per request. Drivetrain pages past that with the unique column: the one you entered, or otherwise the report's first ID column. A report with no ID column syncs only its first 2,000 rows. The note in the window still says reports are limited to 2,000 rows.

If a report still stops at 2,000 rows:

1. **Too many filters:** Salesforce accepts up to 20 filters when a report is run through its API, and Drivetrain adds one to page. Remove a filter.
2. **Cross filters, standard filters or a row limit** block paging through the API. Remove them or sync the object instead.
3. **Unique column:** it must be filled on every row.

## What data comes in

* The objects and reports you choose. Objects sync all their fields.
* After the first sync, each sync brings records changed since the last one. On Saturdays, the scheduled sync re-reads all records.
* Records you delete in Salesforce come through marked as deleted (Salesforce's **IsDeleted** field). Records emptied from the recycle bin disappear at the next Saturday re-read.
* Salesforce's daily API limit is shared by every tool connected to your org. To leave room for them, a sync stops once your org has used about 95% of its daily quota, or once that sync alone has used 25%. Check usage in Setup > **System Overview**.

## Reconnect, disconnect, more connections

* **Reconnect** (after a password change, or if access was revoked): three dots next to the connection > **Edit credentials**, then log in again. Not available while a sync is running.
* **Disconnect:** three dots > **Remove**. This deletes the data synced from it in Drivetrain.
* **More than one Salesforce org:** add another connection. Your subscription may limit how many.
* **Sandbox orgs:** the **Salesforce** tile signs in to production orgs. A separate **Salesforce Sandbox** tile offers objects only (no reports); talk to your Drivetrain team before using it.

## Troubleshooting

Drivetrain shows sync errors in its own words, so the text may differ slightly from below.

| What you see                                                                      | Cause                                                                | Fix                                                                                        |
| --------------------------------------------------------------------------------- | -------------------------------------------------------------------- | ------------------------------------------------------------------------------------------ |
| `OAUTH_APPROVAL_ERROR_GENERIC`, or "app must be installed"                        | Your org blocks uninstalled connected apps                           | Install the app or grant the permission (see Step 1)                                       |
| `API_DISABLED_FOR_ORG`                                                            | Your Salesforce edition has no API access                            | Upgrade, or buy the API add-on (Professional)                                              |
| `API_CURRENTLY_DISABLED`                                                          | The user's profile lacks **API Enabled**                             | Turn on **API Enabled**, then **Edit credentials**                                         |
| `REQUEST_LIMIT_EXCEEDED`, or a message that the Salesforce API quota is used up   | Your org's daily API quota is (nearly) used up, often by other tools | Wait for quota to free up; to raise the limit, buy API add-ons or licences from Salesforce |
| A message that the daily API call limit was reached and the sync resumes tomorrow | Drivetrain's own daily call budget for this connection               | The sync resumes the next day; ask your Drivetrain team if you need a higher budget        |
| Tables sync empty (often only **User** has data)                                  | Missing object or field **Read**, or the user can't see the records  | Check the permissions table above                                                          |
| A report fails with a permission error                                            | No **Run Reports**, or no access to the report's folder              | Grant both                                                                                 |
| **Invalid report link. It must contain a report ID**                              | Not a Lightning report link                                          | Copy the link from Lightning Experience                                                    |
| `uniqueColumn '<name>' not found in report columns`                               | The unique column doesn't match a report column                      | Enter the column name exactly as the report shows it                                       |
| An authentication error after a password change                                   | The stored login no longer works                                     | **Edit credentials** and log in again                                                      |
| **A sync is in progress, please try again once it completes.**                    | You edited credentials during a sync                                 | Wait for the sync to finish                                                                |

**Still stuck?** Contact your Drivetrain onboarding partner with a screenshot of the error.

### Need to grant temporary access?

Rarely, for example to investigate a data issue, your Drivetrain team may ask for temporary access to your Salesforce org. See [Grant temporary access to Salesforce](/integration-guide/readme/crm/integrating-with-salesforce/grant-temporary-access-to-salesforce.md). It isn't needed to connect.


---

# 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 by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://integrations.drivetrain.ai/integration-guide/readme/crm/integrating-with-salesforce.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.