Salesforce Integration

Fathom's Salesforce integration writes call summaries, action items, and selected meeting content into Salesforce so reps don't have to manually input them. Once connected, Fathom matches each external meeting to the appropriate Contact, Account, and open Opportunity records using the meeting attendees' names, email addresses, and company, then writes a logged Task containing the AI-generated call summary.

This guide is intended for Salesforce administrators. It covers the OAuth scopes Fathom requests, the object matching logic, supported field types, Deal View setup, expected behavior for edge cases, and a reference of Salesforce API errors that can surface during sync.

1. Confirm the Salesforce prerequisites 

   • Salesforce edition must have the REST API enabled (standard on Enterprise, Performance, Unlimited, and Developer editions).

   • The authorizing user needs read and write access to Contact, Account, Opportunity, and Task.

   • If your org uses Territory Management, the authorizing user must have access to the territories of any Opportunities they expect to sync to.
     ‍

2. Configure team-level sync

   • Admins on a Business plan can connect Salesforce at the team level under Organization Settings → Integrations. A team-level connection lets every team member's calls sync under the same connection, even if a member doesn't have their own Salesforce seat. It's also a prerequisite for Deal View.

   • Multiple Salesforce Instances: Fathom supports one Salesforce connection per team. Organizations using multiple Salesforce instances can have users connect their own Salesforce accounts in personal settings, allowing meetings to sync to different instances. Deal View and team-level field mapping require a shared team-level Salesforce connection and are not supported in this setup.
     ‍

3. Choose sync mode

   • Automatic sync writes to Salesforce as soon as a meeting ends and the summary is generated. This is the default and the recommended path for every team.

   • Manual sync is available whenever users need to push data to Salesforce outside of the automatic sync workflow. Users can click “Sync to CRM” on the Fathom call page before any data is written. This option is available to Fathom account admins across all calls they can access, and to call owners for their own calls.

Fathom uses the standard Salesforce OAuth 2.0 flow and requests four scopes:

• api – read/write access via the REST API.

• id – basic profile to identify the connecting user.

• custom_permissions – the user's custom permission assignments.

• refresh_token – maintains the connection without re-prompting on token expiry.

Beyond the scopes, the connecting user needs object-level edit permissions on Contact, Account, Opportunity, and Task.

The fastest source of "insufficient privileges" errors is a missing API Enabled system permission. If your security model uses permission sets, confirm the connecting user's permission set grants both object-level access and API Enabled.

When a meeting ends, Fathom takes each external attendee (anyone outside your team's email domains) and walks the matching logic in order:

1. Contact – match on the attendee's primary email address.

2. Account – follow the Contact's Account.Id.

3. Open Opportunity – follow the Contact's OpportunityContactRole records to any open Opportunities.

Each step depends on the prior one. If a Contact isn't found, Fathom writes nothing. If the Contact exists but isn't explicitly linked to an open Opportunity via OpportunityContactRole, deal-level info does not sync to that Opportunity.

A few specifics worth knowing:

• Matching uses the attendee's primary email on their Salesforce profile. Secondary or alternate emails are not used.

• Fathom does not match against Leads. Only Contact, Account, and Opportunity records are written to.

• Only open Opportunities receive new activity. Closed-Won and Closed-Lost are excluded.

• Person Accounts work when the Person Account is related to a Contact via the standard Account.Id reference. Custom relationships outside the standard model are not supported.

• Meeting summary: The AI call summary is written as a Task (logged call) on the matched Contact.

• Deal summary: When Deal View is configured and the Contact is linked to an open Opportunity, the deal summary (and any mapped fields) writes to that Opportunity.

• Action items

  • If the Contact is linked to one or more open Opportunities, each action item from the call is written as a separate Task on each open Opportunity and its associated Contact.

  • If there are no open Opportunities for the Contact, each action item is written as a Task on each external Contact on the call.

  • Action items only write when the Create Tasks setting is enabled.

• Tasks are created by the Fathom integration service user but owned/assigned to the call host. That means activity-by-rep reporting in Salesforce attributes the call correctly, even though the write was made by the integration.

• Secondary or sub-calendars are not synced. Only events on the user's primary connected calendar are eligible.

• Impromptu calls without a calendar event behind them don't match to Salesforce records. If meetings booked via a third-party scheduler appear in Fathom as impromptu, confirm the scheduler is writing events to the user's primary calendar.

• Internal-only meetings (no external attendees) are not synced.

Deal View maps specific sections of Fathom's AI-generated deal summary to Salesforce fields on the Opportunity. For example, map "Pain Points" to a custom text area, or "Next Steps" to a custom field used by reps and forecast reports.

• Deal View is available on Fathom's Business plan (formerly Pro).

• Salesforce must be connected at the team level by an admin in Organization Settings.

• Field mapping is configured by a Fathom team admin and applies across the team.

• Long Text Area (textarea) – fully supported.

• Text (single line) – supported as of November 2025.

If a field doesn't appear in Fathom's mapping dropdown, verify in Setup → Object Manager → Opportunity → Fields & Relationships that it's one of the supported types and is editable by the connecting user.

Fathom can map only sections of the AI summary that are structured as H3 or H4 headings in your deal template. When customizing a template, instruct the AI to use H3 or H4 headers for any section you intend to map (for example, "Use ### headers for sections like Competition, Pain Points, Next Steps, and Decision Criteria"). Sections built from H1, H2, plain bold text, or unstructured paragraphs cannot be mapped.

Salesforce Long Text Area fields have a default limit of 32,000 characters. Long summaries are auto-truncated to fit and the summary content is preserved. Custom fields may have lower configured limits – check the field definition if a section appears cut short. Any custom validation rules on the Opportunity must also accept the content Fathom is writing; if not, the sync will fail for that record.

When Fathom writes a mapped deal summary section to a Salesforce field, any existing value in that field is overwritten. As new meetings occur and updated summaries are generated, Fathom refreshes the mapped field with the latest content from the corresponding section of the deal summary.

1. Open any deal in Fathom (the deal you choose doesn't matter for setup).

2. Hover over the section heading you want to map.

3. Click Map to Salesforce.

4. Select the Salesforce field that section should write to.

Validation rules on Contact, Account, Opportunity, or Task can block Fathom's write. The most common patterns: rules that require specific picklist values, rules that require a field be populated on every edit, and rules tied to specific record types or stages. The error message Fathom surfaces in these cases comes from Salesforce – review the rule definition in Setup.
‍

Different record types on the same object can have different page layouts and different required fields. Confirm the record types used by your team allow Tasks to be created by the connecting Fathom user and don't require fields Fathom cannot populate.

If Opportunities are auto-assigned to territories and the connecting user lacks access to a given territory, sync to those Opportunities will fail. Either grant the user access to the relevant territories, or use a team-level connection with a user who has broad territory access.

Fathom writes call summaries as Salesforce Tasks (logged calls), so they appear in the Activity Timeline on Contacts, Accounts, and Opportunities. On orgs using the modern Notes experience, the summary also appears in the Notes & Attachments related list.

• Once connected, Fathom syncs calls going forward by default.

• Individual older calls can be pushed manually: open the call in Fathom and click Sync to CRM.

• Disconnecting and reconnecting Salesforce does not re-sync historical calls.

When a sync fails, your Salesforce admin can check Salesforce logs for the error. If nothing surfaces there, send an example call URL to help@fathom.video and the team will check backend logs from the Fathom side. 

The codes below are the ones most likely to surface as real Fathom sync failures. 

When a user reports calls aren't syncing, work through these in order:

1. Connection state – In Fathom, confirm the Salesforce integration is connected and the OAuth token hasn't been revoked.
   ‍

2. Attendee match – Confirm the external attendee exists as a Contact in Salesforce with the same primary email address used on the meeting invite.
   ‍

3. OpportunityContactRole link – If deal-level info is missing, confirm the Contact is linked to the open Opportunity via OpportunityContactRole.
   ‍

4. Opportunity state – The Opportunity must be open – Closed-Won and Closed-Lost are excluded.
   ‍

5. Calendar source – The meeting was on the user's primary calendar (not a sub-calendar), and was a scheduled event rather than an impromptu call.
   ‍

6. Field mapping – If only mapped fields are missing, verify the template uses H3/H4 headings for the mapped sections and that target fields still exist and are editable.
   ‍

7. Validation & territory rules – Audit any recent changes to validation rules, page layouts, record types, or territory assignments.
   ‍

8. Send Fathom an example – If the Salesforce-side checks come back clean, send an example call to help@fathom.video for backend log review.