> 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/salesforce.md). # Salesforce How Spara syncs lead data with Salesforce using Push and Pull Rules. Spara integrates with Salesforce to keep your CRM in sync with lead activity. Once connected, Spara can write conversation data and field values to Salesforce Lead and Contact objects (Push), and import existing Salesforce records into Spara as Leads (Pull). For step-by-step setup instructions, see [Guide: Connecting Salesforce](https://docs.spara.com/guides/connecting-salesforce).

The Salesforce integration settings page (Leads tab), showing Push Rules sync modes and Pull Rules.

| Salesforce Object | Spara writes to Salesforce | Spara reads from Salesforce | | ----------------- | -------------------------- | --------------------------------------- | | Lead | Any mapped field | Any mapped field | | Contact | Any mapped field | Any mapped field | | Account | *None* (read-only) | Specific fields; see Account Data below | | Owner (User) | *None* (read-only) | Specific fields; see Owner Data below | | Opportunity | *None* (read-only) | Deal fields; see Opportunity Data below | ## Push Rules Push Rules control how Spara writes data to Salesforce when a Spara Lead interacts with your agents. Spara supports independent Push Rules for Lead and Contact objects. You configure them separately under the Contacts and Leads tabs in [**Settings > Integrations > Salesforce**](https://app.spara.co/settings/integrations/salesforce/manage). For each record type, choose one of four sync modes: * **Create or update**: Update a matching, pre-existing Salesforce record when one is found; create a new one when no match is found. * **Update only**: Update matching records, but never create new ones. Use this when you want Salesforce record creation to stay under your team's control. * **Create only**: Always create a new Salesforce record for each Spara Lead, without matching to existing records. * **Off**: Do not sync to this record type. Sync modes are limited by the permissions of the Salesforce user that authorized the connection. If that user cannot create or edit Leads in Salesforce, the corresponding modes are unavailable in Spara. ### How the sync operates Spara's sync is event-driven, not scheduled. Understanding the timing helps you predict exactly what appears in Salesforce and when: * **A record is created or matched as soon as Spara knows an email address.** The first time an email is captured, whether in chat, on a call, or via a webform, Spara looks for a matching Salesforce record and, depending on your Push Rules, updates it or creates a new one. Spara does not wait for other fields like name or company to be gathered first. * **Field updates push immediately.** Every time a mapped Spara field changes (a new answer in conversation, a booked meeting, an enrichment result), Spara writes it to Salesforce right away. * **Conversation transcripts push shortly after the conversation goes quiet.** Transcript syncs are batched, so Salesforce receives one consolidated update a few minutes after the last message rather than one write per message. * **Pull Rules run every few minutes.** New and modified Salesforce records matching your Pull Rules are imported continuously. * **Opportunity data syncs nightly.** ### How matching works When looking for an existing record, Spara matches in this order: 1. **Salesforce ID**: a stored Salesforce Lead ID (`salesforce_lead_id`) or Contact ID (`salesforce_contact_id`), captured from a previous sync or passed in via [Developer: Query Parameters](https://docs.spara.com/developers/spara-api/query-parameters) 2. **Email address** 3. **Phone number** Matching is automatic. You do not need to set up explicit ID syncing. If multiple Salesforce records share the same email or phone number, Spara syncs to the most recently created one. {% hint style="info" %} **Common CRM integration concerns** The behaviors above are the defaults. Each has a control or workaround, covered in full in [Guide: Working Around CRM Sync Limitations](https://docs.spara.com/guides/crm-sync-workarounds): * [**Use data from Salesforce objects Spara doesn't support**](https://docs.spara.com/guides/crm-sync-workarounds#use-data-from-crm-objects-spara-doesnt-support): map fields from custom objects, Campaigns, or Opportunities onto Spara's core objects (Enterprise). * [**Require fields before a record is created**](https://docs.spara.com/guides/crm-sync-workarounds#require-fields-before-a-crm-record-is-created): hold record creation until more than an email is known (Enterprise). * [**Keep Spara from overwriting Salesforce data**](https://docs.spara.com/guides/crm-sync-workarounds#keep-spara-from-overwriting-crm-data): use the "Update if field is empty" write rule or the Update only sync mode. * [**Write to Accounts, Opportunities, or other objects**](https://docs.spara.com/guides/crm-sync-workarounds#write-to-accounts-opportunities-or-other-objects): route data through Webhooks, the API workflow step, or the Web API. * [**Log Spara activity in Salesforce**](https://docs.spara.com/guides/crm-sync-workarounds#log-spara-activity-in-your-crm): sync transcripts to a text field, enable Task logging, or build activity records from Webhooks. * [**Control which Salesforce records enter Spara**](https://docs.spara.com/guides/crm-sync-workarounds#control-which-crm-records-enter-spara): Pull Rules filter on any Lead or Contact field; configured with your Spara team. {% endhint %} ## Pull Rules Pull Rules control which existing Salesforce records are imported into Spara as Leads. This is useful for leads that exist in Salesforce but have not yet interacted with a Spara agent. Spara can pull them in so your agents and workflows can proactively reach out. Pull Rules are defined as a filter on any Salesforce Lead or Contact field, for example only records from a specific lead source, region, or campaign. By default, Spara only pulls records that have an email address. {% hint style="info" %} Pull Rules are configured by your Spara customer success representative. Contact your Spara team to set up or change them. {% endhint %} ## Data Model Sync The Data Model Sync section maps individual Spara Lead fields to Salesforce fields. Mappings are configured independently for Contacts and Leads using the tabs in the Salesforce settings page. Each row in the mapping table defines: * **Spara fields**: the field Spara gathers during conversations (e.g., First name, Company, or any custom field) * **Salesforce fields**: the corresponding Salesforce field to write to * **Write rule**: whether Spara should overwrite any existing value, or only write when the Salesforce field is empty The Email field is always mapped automatically. You can add as many additional field mappings as needed, including the full conversation history via the **Conversation** Spara field.

The Data Model Sync table, mapping Spara Lead fields to Salesforce fields with a write rule per row.

Field mappings work in both directions: the same mapping that pushes a Spara field to Salesforce also pulls that Salesforce field into Spara. Mappings with the "Update if field is empty" write rule never overwrite existing values in either system. For a full list of available Spara fields, visit your [**Data Model**](https://app.spara.co/data-model). ## Account Data When a matching Salesforce Account is found, Spara reads and stores the following fields automatically: * `salesforce_account_id`: the unique identifier of the Salesforce Account * `salesforce_account_name`: the Account name (usually the company name) * `salesforce_account_owner_email`: the email of the Account's assigned owner Accounts are matched using this priority order: 1. Converted Lead: if the Lead was previously converted, the associated Account is returned 2. Matching Contact: the Account linked to the most recently created Contact with the same email 3. Matching Company Name: if the user provides a company name that exactly matches an Account name When account syncing is enabled, matched Accounts also appear on the [Accounts](/pipeline/accounts.md) page with their firmographics (website, industry, employee count, annual revenue, and billing city). Account data is read-only: Spara never creates or updates Salesforce Accounts. ## Owner Data When a matching Salesforce Owner (assigned sales rep) is found and active, Spara reads and stores: * `salesforce_assigned_sales_rep_id` * `salesforce_assigned_sales_rep_name` * `salesforce_assigned_sales_rep_email` If a matching Account also has an assigned owner: * `salesforce_account_owner_id` * `salesforce_account_owner_name` * `salesforce_account_website` Owner data is available in workflow conditions and agent personalization, so you can reference a lead's assigned rep by name in emails, chat, or routing logic. Owners also appear on the [Owners](/pipeline/owners.md) page. ## Opportunity Data Spara reads Salesforce Opportunity data nightly to power pipeline and revenue reporting in [Analytics](/pipeline/analytics.md), including which deals Spara-engaged leads influenced. Spara reads each Opportunity's name, amount, stage, close date, currency, and open/closed/won status. Two things to know: * Opportunities are linked to leads through Salesforce **Contact Roles**, so deal reporting requires Contact sync to be enabled. * Opportunity data is read-only. Spara never creates or updates Salesforce Opportunities. ## Conversation and Email Sync Spara can write conversation activity to Salesforce in three ways: * **Conversation transcript to a text field.** Map the **Conversation** Spara field to any Salesforce long-text field in the Data Model Sync table. Spara writes the full chat and email transcript, updated as the conversation progresses. * **Conversation transcript as a Salesforce Task.** Spara can additionally log each conversation as a Task attached to the Lead or Contact, assigned to the lead's Salesforce owner. Contact your Spara team to enable this; it requires the lead to have an assigned owner in Salesforce. * **Emails as Salesforce email records.** Emails exchanged between Spara and a lead are logged to the matched Lead or Contact as native Salesforce email activity. ## Limitations The native Salesforce integration is intentionally opinionated. Current limitations to plan around: * **Writes are Lead and Contact only.** Accounts, Owners, Opportunities, and Campaigns are read-only. Spara cannot update them when it learns something new about a company or deal. * **No Campaign support.** Salesforce Campaigns and Campaign Members are not read or written, so campaign attribution is not available in Spara. * **Unsupported objects require custom mapping.** Fields from Salesforce objects Spara doesn't model (custom objects, Opportunities beyond analytics, etc.) can be mapped onto Spara's Lead, Account, and Owner objects by Spara's engineering team, available for Enterprise customers. * **Records are created as soon as an email is known.** Salesforce requires a last name (and company, for Leads) on every record, so when Spara creates a record before those fields are captured, it fills them with the placeholder `UNKNOWN` and updates them as the real values arrive. Requiring specific fields before creation is available as Enterprise custom work. * **Spara Events are not synced as structured activity.** Individual events (page visits, calls, meetings booked) are recorded in Spara and power Analytics and workflows, but are not written to Salesforce as Task or Event records. Conversation activity reaches Salesforce through the mechanisms in [#conversation-and-email-sync](#conversation-and-email-sync "mention"). For practical workarounds to each of these, see [Guide: Working Around CRM Sync Limitations](https://docs.spara.com/guides/crm-sync-workarounds). ## Sync Logs The **Logs** tab on the [**Salesforce settings page**](https://app.spara.co/settings/integrations/salesforce/manage) shows every sync between Spara and Salesforce, newest first. Each entry records what happened (a record created or updated, fields that didn't sync, a sync skipped because of your Push Rules, or a connection problem like an expired token) along with the Lead it affected, the Salesforce record, and how many fields synced.

The Sync Logs tab, showing each sync's status, direction, Lead, Salesforce record, and field counts.

Filter the list by status (**Synced**, **Needs attention**, or **Failed**), direction, or timeframe. Search covers the technical detail behind each entry as well as its summary, so you can look up a Salesforce error code or a field name and find every record hitting the same problem. Select an entry to see its details: * A plain-language explanation of what happened, and what to do about it, with a link to the setting that fixes it * The Lead and the Salesforce record involved * Every field the sync moved, shown as the Spara field, the Salesforce field it maps to, and the value * For any field Salesforce rejected, the reason Salesforce gave. For example, a field that no longer exists, or a value that isn't one of its picklist options Each Lead also has a **CRM sync** row in its details showing that Lead's most recent sync outcome, which opens the same view. That answers "did this Lead reach Salesforce?" without leaving the Lead. ## FAQ ### How does Spara match a Lead to a Salesforce record? Spara matches by stored Salesforce ID first, then email address, then phone number. Matching is automatic; you do not need to configure ID syncing in the field mapping table. ### Can I sync to both Lead and Contact objects? Yes. Push Rules are configured independently for each object type, and a Spara Lead can sync to both a Salesforce Lead and a Contact simultaneously. ### Can Spara sync the full conversation history to Salesforce? Yes. Select the **Conversation** Spara field in the Data Model Sync table and map it to any text field in Salesforce, or ask your Spara team to enable Task logging. See [#conversation-and-email-sync](#conversation-and-email-sync "mention"). ### Will Spara overwrite existing data in Salesforce? By default, yes. New field mappings use "Overwrite existing value." Change individual mappings to "Update if field is empty" to protect existing Salesforce data. ### Can Spara update Salesforce Accounts or Opportunities? No. Spara only writes to Lead and Contact records. Account, Owner, and Opportunity data is read-only. If you need Spara data written to other objects, use [Developer: Webhooks](https://docs.spara.com/developers/spara-api/webhooks) with your own automation. See [Guide: Working Around CRM Sync Limitations](https://docs.spara.com/guides/crm-sync-workarounds). ### Why do some Spara-created records show "UNKNOWN" as the name or company? Salesforce requires those fields on every record, and Spara creates the record as soon as it captures an email, sometimes before a name or company is known. Spara fills the gaps with `UNKNOWN` and replaces them automatically as the real values are gathered. ### Can I stop Spara from creating new Salesforce records? Yes. Set the sync mode to **Update only** and Spara will update matching records but never create new ones. ## Troubleshooting ### Integration user setup and permissions The most common cause of sync problems is an integration user that isn't set up correctly or doesn't have the permissions Spara needs. Sync modes and field access are limited by the permissions of the Salesforce user that authorized the connection, so a misconfigured user can silently block record creation or updates. This walkthrough covers how to check and fix the integration user: {% embed url="" %} ### OAuth Error on connect If you see an OAuth Error during authorization, two options: **Option 1:** Have your Salesforce admin log into Spara and connect directly. **Option 2:** Your Salesforce admin creates an external connected app and grants API permissions. The connected app should enable read/create/edit access on Leads and Contacts. ### Reconnection required If the Salesforce card shows "Reconnection required," Spara's access token has expired. Go to [**Settings > Integrations > Salesforce**](https://app.spara.co/settings/integrations/salesforce/manage), click **Deauthorize**, then authorize again. ### Disconnecting To disconnect Salesforce, go to [**Settings > Integrations > Salesforce**](https://app.spara.co/settings/integrations/salesforce/manage) and click **Deauthorize**. Your field mappings and sync configuration are preserved if you reconnect later. --- # 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, and the optional `goal` query parameter: ``` GET https://docs.spara.com/integrations/crm-integrations/salesforce.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. 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.