Salesforce

How Spara syncs lead data with Salesforce, creates records, and imports records with Import 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 (Import).

For step-by-step setup instructions, see Guide: Connecting Salesforce.

The Salesforce integration settings page (Leads tab), showing sync, writing, and import settings.

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

Sync Leads and Contacts

Lead and Contact sync are configured separately under the Contacts and Leads tabs in Settings > Integrations > Salesforce. The Sync Leads / Sync Contacts toggle at the top of each tab turns sync on or off for that record type:

• On: Salesforce records linked to a Spara Lead sync both ways according to each field's write rule (see Fields synced to/from CRM).
• Off: Nothing syncs between Spara and that record type in either direction, and the settings below it don't apply.

Writing to Salesforce Leads and Contacts

While sync is on, the Writing to Salesforce Leads and Writing to Salesforce Contacts panels set which Salesforce records Spara can update or create:

• Create & update: Spara updates the Salesforce record linked to a Spara Lead, or one that matches by email address or phone number, and creates a new record when none matches.
• Update only: Spara updates linked and matching records, but never creates new ones. Use this when you want Salesforce record creation to stay under your team's control.
• Create only: Spara creates a new Salesforce record for every Spara Lead not yet linked, without matching existing records. Records Spara created stay in sync.

These settings are limited by the permissions of the Salesforce user that authorized the connection. If that user cannot edit Leads in Salesforce, Lead sync is turned off. If the user can edit Leads but not create them, Lead sync is set to Update only.

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 settings, 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.
• Import Rules run every few minutes. New Salesforce records matching your Import Rules are imported as Spara Leads continuously.
• Linked records stay in sync. While sync is on for a record type, Salesforce Leads and Contacts already linked to a Spara Lead have their changes pulled every few minutes according to your write rules, whether or not they match your Import Rules.
• 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
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.

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:

• Use data from Salesforce objects Spara doesn't support: map fields from custom objects, Campaigns, or Opportunities onto Spara's core objects (Enterprise).
• Require fields before a record is created: hold record creation until more than an email is known (Enterprise).
• Keep Spara from overwriting Salesforce data: use the "Update if field is empty" write rule, or turn off Sync Leads / Sync Contacts.
• Write to Accounts, Opportunities, or other objects: route data through Webhooks, the API workflow step, or the Web API.
• Log Spara activity in Salesforce: sync transcripts to a text field, enable Task logging, or build activity records from Webhooks.
• Control which Salesforce records enter Spara: Import Rules filter on any Lead or Contact field; configured with your Spara team.

Import Rules

Import Rules control which existing Salesforce records are imported into Spara as new Leads. This is useful for leads that exist in Salesforce but have not yet interacted with a Spara agent. Spara can import them so your agents and workflows can proactively reach out.

Import 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 imports records that have an email address. The Import Leads / Import Contacts toggle turns importing on or off.

Import Rules only decide which records become new Spara Leads. They don't affect how records already linked to a Spara Lead sync; that is controlled by the Sync Leads / Sync Contacts toggle in Sync Leads and Contacts.

Import Rules are configured by your Spara customer success representative. Contact your Spara team to set up or change them.

Fields synced to/from CRM

The Fields synced to/from CRM 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.

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 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 page.

Opportunity Data

Spara reads Salesforce Opportunity data nightly to power pipeline and revenue reporting in Analytics, 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 Fields synced to/from CRM 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.

For practical workarounds to each of these, see Guide: Working Around CRM Sync Limitations.

Sync Logs

The Logs tab on the Salesforce settings page 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 settings, 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. Leads and Contacts are configured independently, 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 Fields synced to/from CRM table and map it to any text field in Salesforce, or ask your Spara team to enable Task logging. See Conversation and Email Sync.

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 with your own automation. See Guide: Working Around CRM Sync Limitations.

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. Choose Update only for Leads or Contacts, and Spara will sync 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 settings 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:

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, click Deauthorize, then authorize again.

Disconnecting

To disconnect Salesforce, go to Settings > Integrations > Salesforce and click Deauthorize. Your field mappings and sync configuration are preserved if you reconnect later.