> ## Documentation Index
> Fetch the complete documentation index at: https://docs.raycaster.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Salesforce Integration

> Sync contacts and accounts between Salesforce and your Raycaster sheets

## Overview

The Salesforce integration provides bidirectional sync between your Salesforce CRM and Raycaster sheets. Pull contacts and accounts into your workspace, enrich them with AI-powered research, and push updates back to Salesforce.

## Setting Up Salesforce

<Steps>
  <Step title="Open Integration Settings">
    Navigate to **Settings → Integrations** in the sidebar.
  </Step>

  <Step title="Add Salesforce">
    Find the Salesforce section and click **"Add Integration"**.
  </Step>

  <Step title="Authorize">
    Sign in to your Salesforce account and grant Raycaster access. You'll be redirected to Salesforce's OAuth page.
  </Step>

  <Step title="Confirmation">
    Once authorized, the integration becomes active and is available to all members of your organization.
  </Step>
</Steps>

<Note>
  Salesforce integrations are always organization-scoped. Each organization has a single Salesforce connection shared by all members.
</Note>

## Using CRM Templates

The fastest way to get started with Salesforce sync is to use a CRM template:

1. Create a new sheet and select **"From Template"**
2. Choose **"Company/Accounts Template for CRMs"** or **"People Template for CRMs"**
3. The template includes columns pre-mapped to common CRM fields

## Syncing Data

### Configuring Sync

<Steps>
  <Step title="Open a Sheet">
    Open the sheet you want to sync with Salesforce. For best results, use a CRM template.
  </Step>

  <Step title="Open CRM Settings">
    Click the **CRM** button in the sheet toolbar to open the sync configuration.
  </Step>

  <Step title="Select Entity Type">
    Choose what you want to sync:

    * **Contacts** — Individual people in your Salesforce
    * **Accounts** — Organizations in your Salesforce
  </Step>

  <Step title="Map Fields">
    Map your sheet columns to Salesforce fields. The field mapping interface shows available standard and custom fields.

    **Example mappings:**

    | Sheet Column | Salesforce Field |
    | ------------ | ---------------- |
    | First Name   | `FirstName`      |
    | Last Name    | `LastName`       |
    | Email        | `Email`          |
    | Company      | `Account.Name`   |
    | Job Title    | `Title`          |
  </Step>

  <Step title="Choose Sync Direction">
    Select the sync direction:

    * **Pull** — Import data from Salesforce into your sheet
    * **Push** — Export data from your sheet to Salesforce
    * **Bidirectional** — Sync in both directions
  </Step>

  <Step title="Run Sync">
    Click **Sync** to execute. Progress is tracked in real-time.
  </Step>
</Steps>

### Sync Directions

<Tabs>
  <Tab title="Pull (Salesforce → Sheet)">
    Import contacts or accounts from Salesforce into your sheet:

    * All mapped fields are pulled from Salesforce
    * New rows are created for each record
    * Both standard and custom Salesforce fields are supported
  </Tab>

  <Tab title="Push (Sheet → Salesforce)">
    Export data from your sheet to Salesforce:

    * Creates new records in Salesforce for each sheet row
    * Mapped columns are sent as Salesforce field values
    * Useful for adding AI-enriched data back to your CRM
  </Tab>

  <Tab title="Bidirectional">
    Sync in both directions:

    * Pulls new/updated records from Salesforce
    * Pushes new/updated rows from your sheet
    * Use with caution to avoid data conflicts
  </Tab>
</Tabs>

## Custom Fields

Salesforce custom fields are fully supported:

* Custom fields appear alongside standard fields in the field mapping interface
* Map them to any sheet column just like standard fields
* Custom field values are synced in both pull and push directions
* Salesforce custom fields typically end in `__c` (e.g., `Research_Area__c`)

## Sync Tracking

Each sync operation is tracked with:

* **Event type** — Pull, push, or bidirectional
* **Records processed** — Number of contacts/accounts synced
* **Errors** — Any records that failed to sync, with error details
* **Timestamp** — When the sync occurred

View sync history from the integrations settings page.

## Troubleshooting

<AccordionGroup>
  <Accordion title="Fields not appearing in mapping">
    * Verify the field exists in your Salesforce org
    * Check that your Salesforce user profile has field-level security access
    * Custom fields need to be visible to the API user — check field accessibility settings
  </Accordion>

  <Accordion title="Sync creates duplicates">
    * Ensure your field mappings include a unique identifier (typically `Email` for contacts)
    * Use the pull direction first to import existing records before pushing new data
  </Accordion>

  <Accordion title="Permission errors">
    * Verify the Salesforce account used has API access enabled
    * Check that the user profile has CRUD access on the relevant objects (Contact, Account)
    * Salesforce API access requires appropriate edition (Enterprise, Unlimited, or Developer)
    * Try disconnecting and reconnecting the integration
  </Accordion>

  <Accordion title="API limits">
    Salesforce enforces daily API call limits based on your edition:

    * Large syncs may consume significant API calls
    * Monitor your API usage in Salesforce Setup under "API Usage Notifications"
    * Consider syncing during off-peak hours for large datasets
  </Accordion>
</AccordionGroup>

## Disconnecting

To remove the Salesforce integration:

1. Go to **Settings → Integrations**
2. Find the Salesforce integration
3. Click **Disconnect**
4. Confirm the removal

<Warning>
  Disconnecting does not delete any data that was already synced to your sheets or pushed to Salesforce. It only prevents future sync operations.
</Warning>