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

# Salesforce integration

> Set up Sofie access to Salesforce CRM records and custom-object workflows through a Salesforce OAuth app.

The Salesforce integration lets Sofie search, read, and prepare changes for Salesforce records when your organization enables the provider and users connect authorized Salesforce accounts.

Use this guide if you administer Salesforce OAuth apps, manage Sofie integrations, or need to coordinate setup with a Salesforce admin.

<Note>
  Salesforce may show **Connected Apps** or **External Client Apps** depending on your org and Salesforce release. Use the Salesforce app type that supports API OAuth, authorization code flow, callback URLs, scopes, PKCE, a client ID, and an optional client secret.
</Note>

## What Sofie can use

Depending on Salesforce permissions and Sofie configuration, Sofie may help with:

* Listing available standard and custom Salesforce objects.
* Describing object fields, picklists, relationships, and supported actions.
* Searching Salesforce records with keyword search.
* Querying Salesforce records with read-only SOQL.
* Reading specific records by object name and record ID.
* Preparing create, update, upsert, or delete actions for review.
* Using Salesforce context in chat or workflow handoff.

<Warning>
  Salesforce write actions can change external records. Review record names, object API names, fields, values, and timing before approving any update.
</Warning>

## Before you start

You need:

* Salesforce administrator access.
* Permission to create or manage the Salesforce OAuth app.
* A Salesforce user policy for who can authorize the app.
* The Sofie domain users open in the browser.
* Access to Sofie **Organization Settings** > **Integrations**.
* The **Integrations** feature and **Salesforce** integration feature enabled in Sofie.
* A decision about production, sandbox, or My Domain login.

Users who connect Salesforce also need Salesforce API access and permission to the objects and fields they want Sofie to use.

## Callback URL

Add this callback URL to the Salesforce app:

```text theme={null}
https://<your-sofie-domain>/api/integrations/callback/salesforce
```

Use the exact Sofie environment domain. Add staging and production callback URLs separately when needed.

## Set up the app in Salesforce

Create the Salesforce app before entering values in Sofie.

<Steps>
  <Step title="Open app setup in Salesforce">
    In Salesforce **Setup**, open **App Manager** or the app setup area your org uses for OAuth API integrations.
  </Step>

  <Step title="Create the app">
    Create a new Salesforce app for Sofie. Use a clear name such as `Sofie Salesforce Integration`.
  </Step>

  <Step title="Enter contact details">
    Add the administrator contact email and any required support or policy details for your org.
  </Step>

  <Step title="Enable OAuth API settings">
    Enable the API or OAuth settings for the app. Choose the authorization code or web server flow when Salesforce asks for the OAuth flow type.
  </Step>

  <Step title="Add the callback URL">
    Add `https://<your-sofie-domain>/api/integrations/callback/salesforce` as a callback URL.
  </Step>

  <Step title="Require PKCE when available">
    Enable **Require Proof Key for Code Exchange (PKCE)** if your Salesforce app setup offers it. Sofie sends a PKCE code challenge during authorization and a code verifier during token exchange.
  </Step>

  <Step title="Add OAuth scopes">
    Add `api` and `refresh_token` or `offline_access`.
  </Step>

  <Step title="Save the app">
    Save the app and wait for Salesforce to make the app available.
  </Step>

  <Step title="Copy OAuth values">
    Copy the consumer key and, if your policy requires it, the consumer secret.
  </Step>
</Steps>

Salesforce app changes can take several minutes to propagate. If user connection fails immediately after saving, wait and retry before changing the Sofie settings.

## Configure OAuth scopes

Sofie requests these Salesforce OAuth scopes:

| Scope            | Why Sofie needs it                                                                            |
| ---------------- | --------------------------------------------------------------------------------------------- |
| `api`            | Access Salesforce data through Salesforce APIs according to the connected user’s permissions. |
| `refresh_token`  | Keep the connection available after the initial sign-in.                                      |
| `offline_access` | Support continued access where your Salesforce OAuth policy uses this scope name.             |

Use the least access that supports your approved Sofie workflows. Do not add broad scopes such as full access unless your Salesforce admin approves them for a documented reason.

## Configure app access in Salesforce

After creating the app, review its Salesforce access policy.

* Decide whether all approved users can self-authorize or whether access is limited to assigned profiles or permission sets.
* Confirm connected users have Salesforce API access.
* Confirm object permissions and field-level security for the records Sofie should use.
* Review refresh token policy so users do not need to reconnect too often.
* Review IP, session, SSO, and MFA policies that can affect OAuth sign-in.

<Tip>
  Test with a Salesforce user whose permissions match a real target user. A Salesforce administrator can often see records that normal users cannot.
</Tip>

## Copy Salesforce values

After saving the app, copy these values from Salesforce.

| Sofie field       | Salesforce value                                                                                          |
| ----------------- | --------------------------------------------------------------------------------------------------------- |
| **Client ID**     | Consumer Key.                                                                                             |
| **Client Secret** | Consumer Secret when your Salesforce policy requires a secret.                                            |
| **Auth Base URL** | Login host, such as `https://login.salesforce.com`, `https://test.salesforce.com`, or your My Domain URL. |

<Note>
  **Client Secret** is optional for Salesforce in Sofie because Sofie supports PKCE-style authorization. If Salesforce requires a secret for your app policy, enter the consumer secret in Sofie.
</Note>

## Choose the auth base URL

Use the URL that matches the Salesforce org users should connect.

| Salesforce environment | Auth base URL                             |
| ---------------------- | ----------------------------------------- |
| Production             | `https://login.salesforce.com`            |
| Sandbox                | `https://test.salesforce.com`             |
| My Domain              | `https://<your-domain>.my.salesforce.com` |

Use My Domain when your Salesforce org requires it for authentication policy, branding, or SSO. Do not include a trailing slash.

## Add values in Sofie

In Sofie, go to **Organization Settings** > **Integrations** and open Salesforce.

<Steps>
  <Step title="Enable Salesforce">
    Turn on the Salesforce integration.
  </Step>

  <Step title="Choose the OAuth app source">
    Use the organization OAuth app when your Sofie environment should use your Salesforce app instead of default credentials.
  </Step>

  <Step title="Enter OAuth values">
    Enter **Client ID**, **Client Secret** if required, and **Auth Base URL**.
  </Step>

  <Step title="Save changes">
    Save the integration settings. Sofie may require step-up authentication before saving integration secrets.
  </Step>
</Steps>

## Configure a group override

Use a group override when a specific group should connect to a different Salesforce app, sandbox, production org, or My Domain than the organization default.

In Sofie, open the group, configure Salesforce in the group integration settings, and enter:

* **Client ID**.
* **Client Secret** if required.
* **Auth Base URL** when the group should use a specific Salesforce login host.

Group Salesforce credentials override the organization default for members of that group. If the group integration is disabled, members use the organization default.

## Ask users to connect Salesforce

After the admin setup is saved, users connect their own Salesforce accounts from Sofie **Integrations**.

When a user connects:

* Sofie redirects the user to the configured Salesforce auth base URL.
* Salesforce asks the user to authorize the Sofie app.
* Sofie stores the user connection and Salesforce instance details.
* Sofie can only use Salesforce records available to that connected user.

If Sofie shows **Reconnect Salesforce to enable offline refresh**, ask the user to reconnect. The current connection is missing `refresh_token` or `offline_access`.

## Test the connection

<Steps>
  <Step title="Connect a representative test user">
    Use a Salesforce user whose permissions match a real target user.
  </Step>

  <Step title="List available objects">
    Ask Sofie to list Salesforce objects the test user can access.
  </Step>

  <Step title="Describe an object">
    Ask Sofie to describe a known object, such as `Account`, `Case`, or a custom object ending in `__c`.
  </Step>

  <Step title="Search or query known records">
    Ask Sofie to find a known account, contact, opportunity, case, task, event, order, or custom-object record.
  </Step>

  <Step title="Read record details">
    Confirm Sofie can summarize only fields the test user can see.
  </Step>

  <Step title="Test write behavior carefully">
    If write actions are enabled, use a test record and require Sofie to preview all field changes before updating anything.
  </Step>
</Steps>

## User prompt examples

```text theme={null}
List the Salesforce objects I can access and identify which ones support search, query, create, update, and delete.
```

```text theme={null}
Find Salesforce records for this account and summarize open quality-related follow-ups. Do not update any record.
```

```text theme={null}
Search Salesforce for customer records related to this product issue. Return record name, object type, relevant fields, and questions for the account owner.
```

```text theme={null}
Prepare a Salesforce update for this follow-up note, but show me the exact record, object API name, fields, and values before making any change.
```

## Troubleshooting

<Accordion title="Users cannot connect Salesforce">
  Confirm Salesforce is enabled in Sofie, the callback URL matches exactly, the auth base URL points to the right Salesforce org, the app has `api` and refresh scopes, and the Salesforce app policy allows the user to authorize the app.
</Accordion>

<Accordion title="Salesforce reports an invalid callback or redirect URI">
  Compare the Salesforce callback URL with the Sofie domain users opened in the browser. The scheme, host, and path must match. Add separate callback URLs for staging, production, and any custom Sofie domains.
</Accordion>

<Accordion title="Sofie asks users to reconnect Salesforce">
  The connection is missing `refresh_token` or `offline_access`. Confirm the Salesforce app includes the refresh scope, then ask users to reconnect.
</Accordion>

<Accordion title="Sofie cannot find a record">
  Confirm the connected Salesforce user can see the record directly in Salesforce. Sofie follows the connected account’s object permissions, field-level security, sharing rules, and API access.
</Accordion>

<Accordion title="A sandbox user reaches production">
  Check **Auth Base URL**. Use `https://test.salesforce.com` or your sandbox My Domain for sandbox testing.
</Accordion>

<Accordion title="Record updates fail">
  Check Salesforce object permissions, field-level security, validation rules, required fields, duplicate rules, assignment rules, and whether the app policy allows the requested action.
</Accordion>

## Official Salesforce references

* [Enable OAuth Settings for API Integration](https://help.salesforce.com/s/articleView?id=xcloud.connected_app_create_api_integration.htm\&type=5)
* [Proof Key for Code Exchange (PKCE) Extension](https://help.salesforce.com/s/articleView?id=xcloud.remoteaccess_pkce.htm\&type=5)
* [OAuth 2.0 Web Server Flow for Web App Integration](https://help.salesforce.com/s/articleView?id=xcloud.remoteaccess_oauth_web_server_flow_ca.htm\&type=5)
* [OAuth scopes](https://help.salesforce.com/s/articleView?id=sf.remoteaccess_oauth_scopes.htm\&type=5)