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

# Salesforce Integration

> Learn how to connect BoothMaven with Salesforce and synchronize contacts and other supported data.

# BoothMaven & Salesforce Integration — User Guide & Setup Manual

> **Effortless Event Lead Synchronization**: Connect BoothMaven with Salesforce once via secure OAuth, and your captured contacts, accounts, trade show campaigns, booth meetings, and voice/text notes will synchronize automatically in real time — **zero manual CSV exports or imports required**.

***

## Table of Contents

1. [Overview & Key Benefits](#1-overview--key-benefits)
2. [How the Integration Works](#2-how-the-integration-works)
3. [One-Time Setup: Connecting BoothMaven to Salesforce (Package & OAuth 2.0)](#3-one-time-setup-connecting-boothmaven-to-salesforce-package--oauth-20)
   * [3.1 Architecture: Schema Package vs. Private Connected App](#31-architecture-schema-package-vs-private-connected-app)
   * [3.2 Step 1: Install the BoothMaven Salesforce Package](#32-step-1-install-the-boothmaven-salesforce-package)
   * [3.3 Step 2: Create a Private Connected App in Salesforce](#33-step-2-create-a-private-connected-app-in-salesforce)
   * [3.4 Step 3: Retrieve Consumer Key & Consumer Secret](#34-step-3-retrieve-consumer-key--consumer-secret)
   * [3.5 Step 4: Configure Connected App OAuth Policies](#35-step-4-configure-connected-app-oauth-policies)
   * [3.6 Step 5: Connect BoothMaven to Salesforce](#36-step-5-connect-boothmaven-to-salesforce)
4. [What Gets Synchronized Automatically?](#4-what-gets-synchronized-automatically)
   * [4.1 Automatic Contact & Account Matching](#41-automatic-contact--account-matching)
   * [4.2 Campaign & Campaign Member Attribution](#42-campaign--campaign-member-attribution)
   * [4.3 Two-Way Meeting & Calendar Sync](#43-two-way-meeting--calendar-sync)
   * [4.4 Voice Memos & Text Notes Sync](#44-voice-memos--text-notes-sync)
   * [4.5 Content Engagement Signals](#45-content-engagement-signals)
5. [Deduplication & Data Integrity](#5-deduplication--data-integrity)
6. [Managing Custom Field Mappings & Qualification Questions](#6-managing-custom-field-mappings--qualification-questions)
7. [Required Salesforce Permissions](#7-required-salesforce-permissions)
8. [Troubleshooting & Frequently Asked Questions](#8-troubleshooting--frequently-asked-questions)

***

## 1. Overview & Key Benefits

Trade show leads often sit in spreadsheets for days or weeks before reaching your sales team. BoothMaven's direct Salesforce integration eliminates this lag entirely.

```
┌─────────────────────────────────┐                 ┌─────────────────────────────────┐
│        BOOTHMAVEN APP           │                 │         SALESFORCE CRM          │
│                                 │                 │                                 │
│  • Badge Scans & Lead Forms     │ ──────────────► │  • Contacts & Accounts          │
│  • Trade Show Event             │ ──────────────► │  • Campaigns & Campaign Members │
│  • Booth Meetings               │ ◄─────────────► │  • Events / Tasks (2-Way)       │
│  • Text Notes & Voice Memos     │ ──────────────► │  • Notes & Audio Files          │
│  • Brochure & QR Views          │ ──────────────► │  • Activity Tasks & Signals     │
└─────────────────────────────────┘                 └─────────────────────────────────┘
                   Real-Time Synchronization (Zero CSV Uploads)
```

### Key Highlights:

* **Immediate Speed-to-Lead**: Attendees scanned at the booth appear in Salesforce within seconds.
* **Instant Event ROI Attribution**: Automatically creates or links a Salesforce Campaign and marks leads as Campaign Members (`Responded`).
* **Complete Conversation History**: Text notes and audio voice memos recorded on the floor attach directly to the Contact record.
* **Two-Way Meeting Sync**: Meetings scheduled in BoothMaven appear in Salesforce calendars; meeting outcomes updated by sales reps in Salesforce sync back to BoothMaven.
* **Automatic Session Healing**: Connection refreshes automatically in the background without needing re-authentication.

***

## 2. How the Integration Works

Once OAuth authentication is authorized, BoothMaven continuously monitors for activity in your event booth. Every time a booth representative performs an action, BoothMaven dispatches an intelligent, asynchronous background sync job to your Salesforce org:

1. **Email Lookup**: BoothMaven checks if the attendee's email already exists in Salesforce.
2. **Contact & Account Action**: If found, it enriches the existing record; if new, it creates a new Contact and matches/creates the Account.
3. **Campaign Attribution**: Links the Contact to the Salesforce Campaign representing the trade show.
4. **Activity & Notes Attachment**: Schedules meetings, uploads notes, and logs digital engagement signals directly under the Contact's activity timeline.

***

## 3. One-Time Setup: Connecting BoothMaven to Salesforce (Package & OAuth 2.0)

Connecting BoothMaven to any customer Salesforce organization involves two quick steps:

1. **Install the Schema Package (1-Click)**: Deploys the required custom objects, fields, and tabs.
2. **Create a Private Connected App (2 Minutes)**: Issues dedicated OAuth 2.0 credentials (`client_id` & `client_secret`) directly in the customer's org.

***

### 3.1 Architecture: Schema Package vs. Private Connected App

* **Can we include the Connected App in the package?**
  **No.** Salesforce strictly forbids Connected Apps in Unmanaged Packages. In Managed Packages, Connected Apps cannot be authorized by external customer orgs without an expensive, multi-month **Salesforce AppExchange Security Review** (otherwise external orgs receive `OAUTH_APP_ACCESS_DENIED`).
* **Do we create an app for each user or for each organization?**
  **ONE Connected App per Customer Organization.** You do **NOT** create an app for every individual user. The customer's Salesforce Admin creates ONE Connected App named `BoothMaven Integration` inside their org once. All users and event staff in that company share this integration.
* **The Solution**:
  1. **Schema Package (Unmanaged)**: Deploys Custom Objects (`BM_Event__c`, `BM_Event_Attendee__c`, `Event_Note__c`, `Meeting__c`) and 49 custom fields in 1 click.
  2. **Private Connected App**: Created once per customer organization in 2 minutes to provide secure OAuth 2.0 credentials (`client_id` & `client_secret`).

***

### 3.2 Step 1: Install the BoothMaven Salesforce Package

BoothMaven provides **two package options** depending on your customer's Salesforce edition and available custom tab quota:

#### Package Options Comparison

| Feature | Option A: Standard Package (With Tab) | Option B: Lightweight Package (Zero Tabs) |
| :- | :- | :- |
| **Custom Objects** | `BM_Event__c`, `BM_Event_Attendee__c`, `Event_Note__c`, `Meeting__c` | `BM_Event__c`, `BM_Event_Attendee__c`, `Event_Note__c`, `Meeting__c` |
| **Custom Fields** | 49 Custom Fields across all objects & Contact | 49 Custom Fields across all objects & Contact |
| **Custom Tabs** | **1 Custom Tab** (`BM Events Page`) | **0 Custom Tabs** (No tabs included) |
| **Tab Quota Required** | **Required: 1 Tab** | **Required: 0 Tabs (Zero Quota Needed)** |
| **Best For** | Unlimited, Performance, Developer, and Enterprise orgs with free tab slots. | Starter, Essentials, Professional, or **any customer org hitting `Custom Tab Limit Exceeded`**. |
| **API Data Sync** | ✅ 100% Full Real-Time Sync | ✅ 100% Full Real-Time Sync |
| **Installation Link** | **[Install Option A (With Tab)](https://login.salesforce.com/packaging/installPackage.apexp?p0=04tg5000000ErpF)**-`https://login.salesforce.com/packaging/installPackage.apexp?p0=04tg5000000ErpF` | **[Install Option B (Zero Tabs)](https://login.salesforce.com/packaging/installPackage.apexp?p0=04tg5000000F4cn)**-`https://login.salesforce.com/packaging/installPackage.apexp?p0=04tg5000000F4cn` |

#### How to Choose the Right Package for Your Customer:

1. **Default Recommendation**: Send **Option A (With Tab)** (`04tg5000000ErpF`).
   * If the customer's Salesforce org has free custom tab slots, it installs smoothly and provides the convenient `BM Events Page` tab in their navigation bar.
2. **If the Customer Encounters `Custom Tab Limit Exceeded: (Required: 1, Available: 0)`**:
   * This error means their Salesforce plan (e.g. Professional with 10 tabs, or Essentials with 5 tabs) has already used 100% of their allowed custom tabs.
   * **Immediate Fix**: Provide **Option B (Zero Tabs)** (`04tg5000000F4cn`). Because Option B requires 0 tabs, it installs with 100% success on any organization without touching their tab quota!
   * *Alternative*: The customer's admin can go to **Setup $\rightarrow$ Tabs**, delete 1 unused custom tab from another tool, and re-run Option A.

#### Installation Instructions:

1. Open the installation link in your web browser.
2. Log in with your Salesforce System Administrator credentials.
3. On the **Install Package** page:
   * Select **Install for All Users** *(Recommended: This ensures sales reps, event coordinators, and admins have access to trade show event records)*.
   * If prompted with third-party or component access disclosures, check the confirmation checkbox.
4. Click **Install** (or **Upgrade** if a previous version was present).
5. Installation completes in 30–90 seconds (**"Installation Complete!"**).
6. **Verify Installation:** In Salesforce, go to **Setup $\rightarrow$ Installed Packages** and verify the package is listed with Status **Active**.

***

### 3.3 Step 2: Create a Private Connected App in Salesforce

*(This is performed **once** per customer organization, not per user)*

1. In Salesforce, open **Setup** (gear icon in the top right $\rightarrow$ **Setup**).
2. In the left **Quick Find** search box, type **App Manager** and click on it.
3. Click the **New Connected App** button (top-right corner).
4. Fill in **Basic Information**:
   * **Connected App Name**: `BoothMaven Integration`
   * **API Name**: `BoothMaven_Integration` (populates automatically)
   * **Contact Email**: Enter your company administrator email (e.g., `admin@company.com`)
5. Enable **API (Enable OAuth Settings)**:
   * Check: **\[x] Enable OAuth Settings**.
   * In the **Callback URL** textarea, paste both URLs (one per line):
     ```text theme={null}
     https://api.boothmaven.com/v5/salesforce/redirect
     ```
     *(Salesforce Connected Apps natively support multiple callback URLs separated by a newline).*
   * Under **Selected OAuth Scopes**, find and add:
     * **`Manage user data via APIs (api)`** — Allows BoothMaven to sync Contacts, Events, and Notes.
     * **`Perform requests at any time (refresh_token, offline_access)`** — Allows BoothMaven to automatically refresh access tokens in the background without requiring users to log in again.
   * Check: **\[x] Require Secret for Web Server Flow**
   * Check: **\[x] Require Proof Key for Code Exchange (PKCE) Extension for Supported Authorization Flows** (BoothMaven natively supports PKCE SHA-256).
6. Scroll down and click **Save**, then click **Continue**.

> \[!IMPORTANT]
> Salesforce takes **2 to 5 minutes** to propagate a newly created Connected App across its authentication servers globally. Please wait 3 minutes before testing the OAuth flow.

***

### 3.4 Step 3: Retrieve Consumer Key & Consumer Secret

1. From the Connected App view page (or via **Setup $\rightarrow$ App Manager $\rightarrow$ BoothMaven Integration $\rightarrow$ View**):
2. In the **API (Enable OAuth Settings)** section, click **Manage Consumer Details**.
3. Salesforce will prompt for two-factor authentication (email/SMS code). Enter the code and submit.
4. Copy your credentials:
   * **Consumer Key**: This is your `client_id`.
   * **Consumer Secret**: This is your `client_secret`.
5. Store both keys securely.

***

### 3.5 Step 4: Configure Connected App OAuth Policies (Prevents Session Expiry)

1. In Salesforce Setup, go to **App Manager** $\rightarrow$ find `BoothMaven Integration` $\rightarrow$ click the arrow on the right $\rightarrow$ click **Manage**.
2. Click **Edit Policies** at the top of the detail page.
3. Set the following policies:
   * **IP Relaxation**: Select **Relax IP restrictions** *(Ensures cloud servers from BoothMaven can connect reliably)*.
   * **Refresh Token Policy**: Select **Refresh token is valid until revoked** *(Prevents the connection from expiring every few hours)*.
4. Click **Save**.

***

### 3.6 Step 5: Connect BoothMaven to Salesforce

#### Option A: Via BoothMaven Web Dashboard (UI)

1. Log in to the [BoothMaven Web Dashboard](https://app.boothmaven.com/).
2. Navigate to **Settings $\rightarrow$ Integrations $\rightarrow$ Salesforce**.
3. Enter your **Consumer Key** and **Consumer Secret**.
4. Select your environment:
   * **Production / Developer Edition** (`https://login.salesforce.com`)
   * **Sandbox** (`https://test.salesforce.com`)
5. Click **Connect with Salesforce**.
6. On the Salesforce consent screen, click **Allow**.
7. You will be redirected back to BoothMaven with a green **"Connected & Active"** badge!

#### Option B: Via Direct API Call / Postman

1. Request the authorization URL:
   ```http theme={null}
   GET /v5/integration/salesforce?client_id=YOUR_CONSUMER_KEY&client_secret=YOUR_CONSUMER_SECRET
   Host: api.boothmaven.com
   Authorization: Bearer YOUR_BOOTHMAVEN_JWT_TOKEN
   ```
2. The API responds with the authorization URL:
   ```json theme={null}
   {
     "url": "https://login.salesforce.com/services/oauth2/authorize?response_type=code&client_id=...&redirect_uri=https%3A%2F%2Fapi.boothmaven.com%2Fv5%2Fsalesforce%2Fredirect&scope=api+refresh_token+offline_access&state=...&code_challenge=...&code_challenge_method=S256"
   }
   ```
3. Open the `url` in your browser, log in to Salesforce, and click **Allow**.
4. BoothMaven automatically exchanges the code, encrypts credentials, and activates the integration.

***

## 4. What Gets Synchronized Automatically?

***

### 4.1 Automatic Contact & Account Matching

When a rep scans a badge or submits a contact card:

* **Contact Creation / Update**:
  * Scans search for an existing Contact by **Email**.
  * If found, existing fields are preserved and event context (Booth, Rep, Event Name, Lead Score) is enriched.
  * If new, a Contact is created with `LeadSource = "boothmaven"`.
* **Account Matching**:
  * BoothMaven extracts the company name and corporate email domain.
  * Searches Salesforce for a matching `Account.Name` or domain website.
  * Automatically associates the Contact to the appropriate company Account.

#### Standard Fields Synchronized:

| BoothMaven Field | Salesforce Target | Salesforce Field API Name |
| :- | :- | :- |
| First Name | Contact | `FirstName` |
| Last Name | Contact | `LastName` |
| Email Address | Contact | `Email` |
| Phone Number | Contact | `Phone` / `MobilePhone` |
| Title / Designation | Contact | `Title` |
| Company | Contact / Account | `BM_Company__c` / `Account.Name` |
| Lead Source | Contact | `LeadSource` (`boothmaven`) |
| Lead Score | Contact | `BM_Lead_Score__c` |
| Captured By Rep | Contact | `BM_Captured_By__c` |
| Capture Method | Contact | `BM_Capture_Method__c` (e.g. `badge_scan`, `kiosk`) |

***

### 4.2 Campaign & Campaign Member Attribution

Every event configured in BoothMaven connects directly to the Salesforce Campaign hierarchy:

* **Automatic Campaign Association**: BoothMaven links to an existing Salesforce Campaign or auto-creates a Campaign named after your event (e.g. *"CES 2026 — Booth #5012"*).
* **Instant Campaign Member Creation**: Every attendee scanned at the booth is added as a `CampaignMember` with status **`Responded`**.
* **ROI Visibility**: Marketing teams can immediately view total event reach, pipeline influenced, and won revenue directly in Salesforce Campaign reports.

***

### 4.3 Two-Way Meeting & Calendar Sync

When booth staff book an on-site demo or follow-up call with an attendee:

* **Calendar Event Created**: BoothMaven creates a Salesforce `Event` or `Task` record linked directly to the attendee's Contact record (`WhoId`).
* **Complete Meeting Details**: Includes meeting title, date, start/end time, duration, meeting pod/room location, and agenda notes.
* **Two-Way Status Sync**: If an account executive updates the meeting status in Salesforce (e.g., *Completed*, *Rescheduled*, or *No-Show*), the outcome flows back into BoothMaven so booth managers have accurate daily reporting.

***

### 4.4 Voice Memos & Text Notes Sync

Booth conversations contain invaluable qualitative context that standard forms miss:

* **Text Notes**: Rep notes taken in BoothMaven immediately sync as standard Salesforce `Note` records attached to the Contact.
* **Audio Voice Memos**: Reps can record 30-second audio voice memos right after talking to an attendee. BoothMaven uploads the audio file as a Salesforce `ContentVersion` document linked to the Contact, allowing field reps and account executives to listen to the prospect's exact requirements and tone.

***

### 4.5 Content Engagement Signals

When booth visitors interact with your digital assets:

* When a prospect scans your digital card, downloads a PDF product brochure, or watches an embedded demo video after the show, BoothMaven logs a high-priority `Task` in Salesforce.
* Shows the exact document viewed, duration spent reading, and timestamp so your sales reps can follow up while interest is peak.

***

## 5. Deduplication & Data Integrity

To keep your Salesforce database clean:

1. **Email-First Deduplication**: BoothMaven checks `Email = '{attendee_email}'` before creating any new Contact record.
2. **Safe Field Updates**: BoothMaven does not overwrite existing telephone numbers, titles, or company names unless specifically configured. It safely updates event-specific fields (e.g., latest event visited, lead score, qualification responses).
3. **Audit Trail**: Every synchronized record logs a sync transaction in BoothMaven (`CrmLog`) with the Salesforce Record ID and timestamp for total traceability.

***

## 6. Managing Custom Field Mappings & Qualification Questions

Does your booth team ask qualifying survey questions (e.g., *"What is your purchasing timeline?"*, *"What is your current vendor?"*)?

* In **BoothMaven Dashboard → Settings → Integrations → Salesforce → Field Mapping**, you can map each qualification question directly to any custom field on your Salesforce Contact or Campaign Member object (e.g., `Purchasing_Timeline__c`, `Budget_Approved__c`).

***

## 7. Required Salesforce Permissions

For the connection to synchronize smoothly, the connecting Salesforce user profile must have the following standard permissions:

* **API Enabled**: Permission to use the Salesforce REST API.
* **Standard Object Permissions**:
  * **Contacts**: Read, Create, Edit.
  * **Accounts**: Read, Create, Edit.
  * **Campaigns & Campaign Members**: Read, Create, Edit.
  * **Events & Tasks (Activities)**: Read, Create, Edit.
  * **Notes & Files (ContentVersion)**: Read, Create.

***

## 8. Troubleshooting & Frequently Asked Questions

### Q: How do I know if a lead synchronized successfully?

**A:** In the BoothMaven web portal, go to **Contacts**. Next to each contact, a Salesforce cloud icon indicates sync status:

* 🟢 **Green**: Synchronized successfully (hover to view the Salesforce Contact ID).
* 🟡 **Yellow**: In queue for delivery.
* 🔴 **Red**: Failed (click to see the exact error message from Salesforce, e.g., missing required field or validation rule).

### Q: What happens if a Salesforce validation rule blocks a contact?

**A:** If a custom Salesforce validation rule rejects a record (for example, a mandatory custom field), BoothMaven records the error in the activity log and retains the lead. Once the field mapping or validation rule is adjusted, click **Retry Sync** in the BoothMaven dashboard to push the lead without data loss.

### Q: Can I disconnect or switch to another Salesforce instance?

**A:** Yes. In **Settings → Integrations → Salesforce**, click **Disconnect**. You can then reconnect to a different Sandbox or Production environment at any time.

### Q: What does "Custom Tab Limit Exceeded: (Required: 1, Available: 0)" mean during package installation?

**A:** This error occurs when the customer's Salesforce edition has reached 100% of its custom tab quota (e.g. Professional has 10 tabs, Essentials has 5 tabs, Enterprise has 25 tabs). Custom tabs in unmanaged packages count directly against the customer's edition limit.

* **Immediate Fix (Option B)**: Provide **Option B: Lightweight Package (Zero Tabs)** ([Install Option B](https://login.salesforce.com/packaging/installPackage.apexp?p0=04tg5000000F4cn)). Because Option B requires 0 tabs, it installs with 100% success on any organization without touching their tab quota.
* **Alternative**: The customer's admin can go to **Setup $\rightarrow$ Tabs**, delete 1 unused custom tab from another tool, and re-run Option A.

### Q: What causes "error=redirect\_uri\_mismatch"?

**A:** The redirect URI sent by BoothMaven did not match the callback URLs listed in the customer's Salesforce Connected App. Ensure `https://api.boothmaven.com/v5/salesforce/redirect` is entered on separate lines in the Connected App's **Callback URL** field without trailing slashes or extra spaces.

### Q: What causes "error=invalid\_client"?

**A:** The Consumer Key (`client_id`) or Consumer Secret (`client_secret`) was copied with leading/trailing spaces, or the Connected App was just created and Salesforce is still propagating it across global authentication servers (takes 2–5 minutes). Wait 3 minutes, re-copy both credentials cleanly, and retry.

### Q: What causes "OAUTH\_APP\_ACCESS\_DENIED"?

**A:** In Salesforce Setup $\rightarrow$ **App Manager** $\rightarrow$ `BoothMaven Integration` $\rightarrow$ **Manage** $\rightarrow$ **Edit Policies**, verify that **Permitted Users** is set to **"All users may self-authorize"** and IP Relaxation is set to **"Relax IP restrictions"**.

### Q: Does BoothMaven count against my Salesforce API limits?

**A:** BoothMaven optimizes API usage with efficient payload batching and targeted query calls, using negligible API call volume even for high-traffic booths with thousands of scans per day.

***

## Need Support?

* **BoothMaven Integration Support**: [support@boothmaven.com](mailto:support@boothmaven.com)
* **Knowledge Base & Help**: [https://boothmaven.com/help](https://boothmaven.com/help)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.