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

# Connecting Salesforce

How to connect Spara to Salesforce and configure lead syncing.

This guide walks you through connecting Spara to Salesforce so that lead conversations and field data sync automatically to your CRM.

For a full feature reference, see [Salesforce](https://docs.spara.com/integrations/crm-integrations/salesforce.md).

## What Syncs

Once connected, Spara can:

* Write conversation data and field values to matching Salesforce Leads and Contacts (Push)
* Create new Salesforce records when no match is found
* Import existing Salesforce records into Spara as Leads (Import)
* Read Account and Owner data to personalize agent behavior

{% stepper %}
{% step %}

#### Navigate to Integrations

Go to [**Settings > Integrations**](https://app.spara.co/settings/integrations) and find the Salesforce card. Click **Authorize**.

{% hint style="info" %}
You need Manager or Integrator permissions to connect integrations. See [User Management](https://docs.spara.com/platform/settings/user-management.md) for role details.
{% endhint %}
{% endstep %}

{% step %}

#### Enter your Salesforce URL and authorize

Enter your Salesforce instance URL (e.g., `https://yourcompany.salesforce.com`). Use your main Salesforce domain, not a `.force.com` URL.

Click **Authorize** and complete the Salesforce authentication flow.
{% endstep %}

{% step %}

#### Turn on sync

On the Manage page, use the **Contacts** and **Leads** tabs to configure each object type independently:

* **Sync Leads** / **Sync Contacts** (top of the tab): turn on to sync linked records both ways according to your write rules; turn off to stop all sync for that record type
* **Create & update**, **Update only**, or **Create only** (under **Writing to Salesforce Leads** / **Contacts**): choose whether Spara creates Salesforce records when no existing one matches, only updates existing records, or always creates new records without matching

Spara matches records by Salesforce ID, email address, or phone number automatically.
{% endstep %}

{% step %}

#### Map fields

Field mappings are set on each field in the [**Data Model**](https://app.spara.co/data-model), not on the Salesforce settings page.

1. Open a Lead field (e.g., First name, Company, or any custom field) in the Data Model
2. In its **Salesforce sync** section, choose the **Salesforce field** in the **Contact** and **Lead** slots. Contacts and Leads are mapped independently
3. Set the write rule for each direction, **Salesforce → Spara** and **Spara → Salesforce**: **Overwrite**, **Set if empty**, or **Read-only** (never write in that direction)
4. Click **Save changes**

To map several fields at once, click **Suggest fields** on the Data Model's **Lead** tab and pick from the AI-suggested Salesforce mappings. Picks save immediately, creating Spara fields where needed.

To sync the full conversation history across every channel, map the **Conversation transcript (all channels)** Spara field to any Salesforce long-text field.

A record type the connected Salesforce user can't see stays off, and its tab is read-only until that user is granted access to it. If its sync was already on, you can still turn it off.

The Salesforce settings page lists the fields synced with each object, with any mapping problems first. See [Data Model](https://docs.spara.com/build/data-model.md#crm-field-mappings) for details.
{% endstep %}

{% step %}

#### Save and verify

Click **Save** to activate the connection. New lead activity will begin syncing to Salesforce immediately.

To verify, have a test lead interact with your Spara agent and confirm that a corresponding Lead or Contact record appears or is updated in Salesforce.
{% endstep %}
{% endstepper %}

## Troubleshooting

### OAuth Error

If you see an OAuth Error, have your Salesforce admin connect directly from Spara, or create an external connected app with API read/create/edit access on Leads and Contacts.

### Reconnection required

Go to [**Settings > Integrations > Salesforce**](https://app.spara.co/settings/integrations/salesforce/manage), click **Deauthorize**, then authorize again.

### Disconnecting

Click **Deauthorize** on the Salesforce manage page. Your sync configuration and field mappings are preserved for when you reconnect.


---

# 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://docs.spara.com/integrations/crm-integrations/connecting-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.
