Topo's native Salesforce integration makes your CRM the system of record for everything your outbound team does in Topo: the people and accounts they work, every email and LinkedIn touch, the tasks they owe and who owns what. Nothing is installed in your org, Topo acts only with the rights of the user you connect, and your org's own rules apply to every write.

The business logic is the same as Topo's HubSpot and Pipedrive integrations. Where Salesforce's data model differs (Leads and Contacts, Opportunities, list views, API quotas), the integration follows Salesforce's model. This article covers every setting.

Overview

What syncs, in which direction, how often

How the integration behaves

• Salesforce stays the system of record. Before writing, Topo looks for an existing record: people are matched on email, accounts on website domain. If one exists, Topo updates it. It never creates a second one.

• Nothing reaches Salesforce before outreach starts. Importing, enriching or adding leads to a sequence writes nothing to your CRM. A record is created or updated when the first sequence step actually runs.

• You decide every field Topo writes. Fields you leave unmapped are never touched.

• Your org's rules apply to Topo. Duplicate rules, validation rules, restricted picklists, required fields and field-level security govern every write.

• Zero footprint. No managed package, Apex, trigger, custom object or field. Topo uses the REST API and SOQL through an OAuth connection you can revoke at any time.

Before you connect

• A Salesforce edition with API access. Enterprise, Unlimited, Performance and Developer editions include it. Professional edition needs the API add-on.

• A dedicated integration user (recommended). A user with API Enabled, without View All Data, with rights limited to Contact, Account, Lead, Task, EmailMessage, Event and Opportunity, plus read access to User for owner mapping. Give it a recognisable name such as "Topo Integration": it becomes the Created By on every record Topo writes, and the connection survives staff changes. A System Administrator account also works for a pilot.

• Email and Website visible to that user. Topo matches people on Email and accounts on Website. Hiding either with field-level security degrades matching and raises a warning in Topo.

• Admin rights in Topo.

• Two decisions made in advance: whether Topo creates Leads or Contacts (see Provider below), and which custom fields you want Topo to fill (see Fields below).

Connecting to Salesforce

Connect your org

1. In Topo, go to Settings > Integrations and find the Salesforce card.

2. To test first, tick Connect to a sandbox (test.salesforce.com). To connect production, leave it unticked.

3. Click Connect and sign in to Salesforce. Topo uses Salesforce's standard OAuth flow and never sees your password.

4. Accept the permissions. Topo requests the scopes api, refresh_token and offline_access. Salesforce has no read-only API scope, so the real boundary is the connected user's profile, permission sets, field-level security and sharing rules. The connection takes 15 to 30 seconds.

5. Click the settings icon next to the integration and work through the tabs described below. Click Save when you're done.

Start in a sandbox

The sandbox option lets you check exactly what Topo writes before it touches production. It takes an afternoon.

1. Refresh a sandbox from production, so fields, picklists, validation rules, duplicate rules and list views match.

2. Tick Connect to a sandbox and sign in with the sandbox copy of your integration user.

3. Create your custom fields in the sandbox, then configure every tab as you intend to in production.

4. Run one short sequence on two or three test leads (colleagues' work addresses are ideal) and let the first step run.

5. Check the result in Salesforce: the Lead or Contact, the Account, the activity timeline, the Task list and the Owner field. Then read Sync history in Topo.

6. Disconnect the sandbox, connect production and apply the same configuration. Deploy your custom fields to production before mapping them.

7. Keep lead approval on for your first production sequences.

Reconnecting

If the authorisation is revoked in Salesforce or the integration is deactivated in Topo, the integration shows as needing reconnection. Go to Settings > Integrations > Salesforce, click Connect and sign in with the integration user. Syncing resumes, including imported lists.

Activities logged in Topo while the connection was down are not pushed afterwards, so reconnect promptly.

One CRM per workspace

Connect Salesforce only. Running HubSpot or Pipedrive alongside it is technically possible but strongly discouraged: activity sync needs a single source of truth, and Owner Sync won't start while a second CRM is connected.

If your company has several business units with separate data in one org, use one Topo organisation per unit, each connected with its own integration user whose sharing is limited to that unit. Inside one Topo organisation, every member sees the same synced records.

Troubleshooting the connection

Sign-in fails with an approval error. Usually one of these:

• Connected app policy. Your org may block apps that aren't pre-approved. In Salesforce Setup, check Connected Apps OAuth Usage and make sure Topo isn't blocked.

• Single sign-on. Strict SSO policies can block the approval screen. Try with an admin account that can sign in without SSO.

• Missing permission. The user's profile may not be allowed to approve new connected apps. Connect with a System Administrator, or ask your admin to grant the permission.

• API-only licence. Users that can't sign in interactively can't complete the approval screen. Use a user with a full Salesforce licence.

The Owners tab shows a reconnect prompt. The connected user can't read Users. Grant read access to User, then reconnect.

The integration shows as needing reconnection. The authorisation was revoked or expired. Reconnect as described above.

Configuring the integration

Click the settings icon next to the integration to open the configuration drawer. It has nine tabs: Provider, Exclusion, Activity, Entities, Fields, Tasks, Owners, Issues and Sync history.

Provider: Leads or Contacts

The Provider tab holds the settings specific to Salesforce. Create contacts as decides which object Topo creates for a prospected person. Contact mode is the default.

Both modes use the same matching: if a Lead or Contact with that email already exists, Topo updates it, and a converted Lead is resolved to the Contact it became.

Why changes from Salesforce aren't instant. Salesforce doesn't send webhooks to third parties, so Topo reads your org on a schedule. Everything done in Topo reaches Salesforce right away. Changes made in Salesforce arrive on the next check:

Exclusion

Controls which Salesforce records are blocked from receiving Topo outreach. Exclusions are checked when leads are imported and re-read every 15 minutes: a person who becomes excluded while a sequence is running is stopped.

Salesforce has no lifecycle stage on the Account, so "customer or live deal" is read from the Opportunity object.

Once you've picked an option, set how long an exclusion lasts: from 3 to 730 days.

How list views work as exclusions. Topo offers the Contact and Account list views the integration user can see, except Recently Viewed and views whose filters can't be expressed as a query. Views over 2,000 rows are read in full. People are matched on email, accounts on domain. To exclude by a tag or custom field, build a list view filtered on that field.

Protecting customer accounts while still prospecting them. Use the Opportunity rule or an Account list view to protect whole companies, and a Contact list view for the people you're already in touch with at customer accounts. The rest of the organisation stays reachable for the account manager. Add lead approval on those sequences so the account manager has the last word.

Activity

Every Topo activity becomes a native Salesforce object on the activity timeline of the person and their Account, so your existing activity reports, dashboards and Flows see it.

Message bodies over 32,000 characters are truncated, the Salesforce limit for long text.

Choosing what to sync. Everything is on by default. Untick what you don't need.

• Outbound activities: emails sent, LinkedIn messages sent, LinkedIn invitations sent, manual actions.

• Inbound activities: email replies, email opens, email link clicks, LinkedIn replies, LinkedIn opens, LinkedIn invitations accepted, hot-lead alerts.

Turning a whole direction off also skips the contact or account write that event would have triggered.

Reply categories. Topo classifies every reply as Positive, Negative, Neutral, Out of office or Bounced, and you choose which categories reach Salesforce. Either untick Bounced and Out of office to keep the timeline clean, or sync everything and let a Flow act on the category. For example, Bounced sets Email Opt Out, and Neutral (bad timing) creates a follow-up Task three months out.

Topo's own lead status is not pushed, because Salesforce already has Lead Status. Use Last Campaign and the activity history to see where a person stands with Topo.

Entities

Two switches, both on by default:

• Auto-push Contacts: when a synced activity needs a person record, Topo creates one if none exists. It's a Contact or a Lead depending on your Provider setting.

• Auto-push Accounts: Topo creates new Accounts, matched on website domain first.

Turn a switch off and Topo only updates records that already exist in your org.

How Topo finds existing records:

• People are matched on email across both Leads and Contacts. If several records share an email, Topo takes the most recently modified one.

• Converted Leads are resolved to their Contact.

• Accounts are matched on the root domain of the Website field. www., http and trailing slashes all resolve to the same account.

• Matching only covers what the integration user can see. A user that's too restricted matches less well.

How your org's rules apply:

Fields

Map Topo fields to your Salesforce fields. Topo reads your org's real fields, standard and custom, so the dropdowns show their real labels. Remove a row and that field is never touched. After creating new fields in Salesforce, click Refresh CRM fields so they appear.

Matching keys. Two rows are locked because they're how Topo finds existing records: Email to Email for people, and Domain to Website for accounts.

Person fields (defaults in Contact mode):

In Lead mode, standard fields map to the Lead's own Title, Phone, Company and address fields, and the configurable rows are your custom fields.

Account fields:

Two fields worth creating. These don't exist in Salesforce until you create them. Name them after the Topo fields, then map them:

• Lead from Topo (checkbox or Yes/No picklist): Yes on people Topo found and added to your org. Records already in Salesforce keep their original source.

• Last Campaign (text, 255 characters): the name of the last Topo sequence the person was enrolled in, updated on every new enrolment. The most reliable field for reports, list views and Flows. If the field doesn't exist, the mapping switches itself off after the first rejection.

Static values. Below the mappings, Add static value writes a fixed value on every record Topo creates, for example Lead Type = Topo Outbound to separate Topo's pipeline in every report, or a default for a required custom field. Static values are written at creation only, so existing records keep their values.

Tasks

Turn on Sync Tasks to CRM and pick the task types to sync. Topo creates native Salesforce Tasks on the person's record, with a subtype (Email, Call or Task), priority, status, due date, and the lead and sequence details.

Sync works both ways: completing a Task in Salesforce completes it in Topo (within 15 minutes), and the other way round. Each synced task in Topo has a View in Salesforce link.

Owners

Owner Sync keeps account and person owners matched between Topo and Salesforce, in both directions. It's off until an admin turns it on.

1. Map your users under Owners > User mapping. Topo matches active Salesforce users to Topo teammates by email. Fix any row marked Needs attention by hand. Manual choices survive every re-scan.

2. Turn it on with Sync owners with your CRM. If Topo already holds owners, you're asked once how to resolve existing records: Trust Salesforce's owners or Trust Topo's owners.

3. Choose the source of truth separately for accounts and people. The side you choose wins when the two disagree. A change from the other side is flagged for review, never silently applied or discarded.

Salesforce specifics:

• Topo always uses Salesforce's standard Owner field.

• A Salesforce record can't have a blank owner, so Topo never clears an owner in your org.

• Owner changes made in Salesforce reach Topo within 10 minutes.

• In Lead mode, the owner is set at creation only. Later reassignments happen in Salesforce until conversion.

• Owner and sender are different. Reassigning an owner never changes the mailbox or LinkedIn identity a running sequence sends from.

For the full detail, see CRM Owner Sync: Feature Overview.

Issues

Records that need a human decision, split into Accounts, Contacts and Tasks.

Sync history

Every exchange between Topo and Salesforce: each sync run with its outcome, duration, and counts of processed and failed records. Each rejected write names the record, the operation, the error category and Salesforce's exact message. This is the first place to look when a record didn't arrive, and it's what Topo support reads when you contact us, so we never need access to your org.

Importing Salesforce list views

A list view is a saved segment whose criteria update on their own. Import one as an inclusion list to scope lead searches and sequences, for example so account managers prospect inside their own book.

1. Go to Settings > Lists, or click Import on the Accounts or Contacts page.

2. Create a company or contact list and pick the Salesforce option. It only shows when the integration is connected.

3. Select the list view. Topo syncs its members in the background, whatever the size.

Imported lists refresh every 60 minutes. From the list's action menu you can pause syncing, detach the list to make it a standard Topo list, or open the list view in Salesforce. If the integration is deleted and reconnected, imported lists become standard lists and must be re-imported.

Reports, Campaigns and Data Cloud segments can't be imported. Rebuild the logic as list view filters. For cross-object conditions, a formula or roll-up field keeps the filter simple.

Picklists, required fields and validation rules

Most Salesforce write errors come from these. Every rejection is logged in Sync history with Salesforce's exact message, and the rest of the batch continues.

• Picklist values must match exactly. The value Topo writes must be an accepted value of the target picklist. For Industry, compare Topo's values with yours, or map to the custom Company Industry field instead.

• Match field types. Map numbers to Number fields and text to Text fields. If Employees is a picklist in your org, map Number of Employees to a separate numeric or text field, or leave it unmapped.

• Required fields are satisfied with static values.

• Validation rules apply to Topo as to any user. Share them with your onboarding manager during setup.

API quotas and batch processing

Salesforce caps the API calls an org can make over 24 hours, and every integration you run shares that quota. Topo reads its consumption on every call and protects it:

Topo also keeps its footprint small: records are read and written in batches of 200, with a status per record, so one rejected record never blocks the other 199. Full recalculation of list exclusions runs on Sunday nights, when quota is least contended.

Opportunities and the Topo agent

The sync never creates an Opportunity. With Salesforce connected, the Topo agent can, when a rep asks:

• Search opportunities (won, lost or open) to analyse your pipeline and sharpen your ideal customer profile.

• Qualify accounts against the deals you've won, using live Salesforce data.

• Create an opportunity, with the person as primary contact role when the record is a Contact.

• Log a note, saved as a completed Task.

Opportunity data is read live and not stored in Topo. Salesforce has one list of opportunity stages per org, so the agent works with a single pipeline, and a search returns up to 2,000 results.

Finding Topo activity in Salesforce

Every record and activity is a native Salesforce object, so your existing reports and dashboards cover Topo. To find Topo-sourced records, filter on any of:

• Lead from Topo equals Yes

• Last Campaign is not blank

• Your static value, such as Lead Type equals Topo Outbound

• Created By equals your integration user (no setup needed)

To attribute pipeline to sequences in Lead mode, map Last Campaign for conversion and report on Opportunities by Last Campaign. In Contact mode, report through Opportunity Contact Roles or the Account.

From Topo, the View in Salesforce link on the lead, contact page, tasks, inbox and Chrome extension opens the matching Salesforce record.

Best practices

• Pilot in a sandbox. One sequence, two or three test leads, first step allowed to run. Read Sync history before going to production.

• Use a dedicated integration user. Clean audit trail, no dependency on one employee, and Topo sees only what you decide.

• Create the two custom fields before connecting, and map them for Lead conversion if you use Lead mode.

• Check exclusion list views for activity-based criteria and missing domain variants.

• Keep lead approval on for the first production sequences.

• Agree on ownership: who resolves Issues, who maintains exclusion list views, who watches API quota alerts.

Known limits

• No real time from Salesforce to Topo. Salesforce is read on a schedule, from every 10 minutes to once a day depending on the data.

• Leads created by Topo aren't read back until converted. Bulk record creation is available in Contact mode only.

• Person Accounts are not supported.

• Campaign Members are not written. Attribution runs through Last Campaign, Lead Type, Lead Source and Created By.

• Campaigns, Reports and Data Cloud segments can't be used as lists. List views can.

• Topo sees what the integration user sees. Records, fields and list views outside its access are invisible to Topo.

• No retroactive push. Connecting never back-fills history. Export earlier data from the Contacts page as CSV and import it with Data Import Wizard or Data Loader.

FAQ

Will connecting Topo overwrite our Salesforce data?

Not without an explicit choice from you. Only mapped fields are written, existing records are updated rather than duplicated, static values only go on records Topo creates, and Owner Sync is off by default. You can prove all of it in a sandbox first.

Why are my Topo leads not appearing in Salesforce?

Topo writes a person when they receive the first step of a sequence, not at import. If the first step has run, check the integration is connected, check your exclusion rules, and look the person up in Sync history.

Why does "Leads contacted" in Topo exceed the count in Salesforce?

Leads contacted counts first messages sent from sequences. Salesforce only holds records that reached a first step and weren't excluded. Filter the sequence to people with at least one email or LinkedIn action, review exclusions, then spot-check a few missing people.

Excluded accounts are still being contacted. Why?

Check the list view criteria, confirm the right list is selected under Exclusion, and cover every domain variant. The Opportunity rule excludes open and won opportunities, not lost ones. Also check the exclusion lifetime.

What happens when Topo hits a duplicate rule?

Topo attaches to the existing record your rule points to, instead of failing or creating a second one.

The phone number or company data looks wrong.

Check the mappings under Fields. Phone must map to Business Phone, not Mobile, and phone numbers only sync with the phone numbers add-on. For account fields, check picklist targets accept Topo's values.

Why don't LinkedIn messages show in the Sales Navigator app?

Topo sends standard LinkedIn messages, which Sales Navigator doesn't track. Topo logs them itself on the Salesforce record as completed Tasks.

Does Topo change anything about our Salesforce users?

No. Topo reads active users to build the owner mapping. It never creates, edits or deactivates a user.

A mapped field was renamed in Salesforce. What now?

You'll get a CRM alert. Open Fields, click Refresh CRM fields, re-map the field, save, and check in Sync history that writes resume. If the alert persists, contact support with the alert message and the recent changes made in your org. See also Troubleshooting CRM Integration Alerts.

For anything else, see FAQ: CRM Integrations or reach out through the in-app chat.