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

# CRM Integration FAQ

> Answers to the most common questions about syncing BenefitFlow data to your CRM.

## Field Mapping

<AccordionGroup>
  <Accordion title="Can I combine multiple BenefitFlow fields into one CRM field?">
    No. The **Custom Value** (constant) mapping type pushes a single static string to a CRM field — for example, setting Lead Source to "BenefitFlow" for every synced record. It does not support concatenation, templates, or computed values.

    If you need to combine fields (e.g., merging first name and last name into a full name field), set up a post-sync automation on your CRM side:

    * **Salesforce:** Use a Flow or Formula Field
    * **HubSpot:** Use a Workflow with a "Copy property value" action
    * **Dynamics:** Use a Power Automate flow
  </Accordion>

  <Accordion title="Which renewal date field should I map?">
    BenefitFlow provides two distinct renewal date fields:

    | Field                     | Format              | Example    |
    | ------------------------- | ------------------- | ---------- |
    | **Benefit Renewal Month** | Month name (string) | "January"  |
    | **Employer Renewal Date** | Full date           | 01/01/2025 |

    **Which should you use?** Map whichever field matches your CRM field's data type. If your CRM field expects a date, use Employer Renewal Date. If it expects a text string, use Benefit Renewal Month.

    <Warning>
      **Known issue:** The Benefit Renewal Month field has caused silent sync failures in HubSpot when the target field type is incompatible. If your HubSpot syncs are failing without an error message, check whether you have a Benefit Renewal Month mapping and confirm your target field accepts text values.
    </Warning>
  </Accordion>

  <Accordion title="Is there a location field I can map to my CRM?">
    Yes — BenefitFlow has a wide range of location fields available for mapping, depending on the object type:

    **All Contacts:**

    * City, State, State Code, Country, Country Long, Zip Code

    **Broker Contacts only:**

    * Office Address, Office City, Office State, Office State Code, Office Zip Code

    **Broker Office Locations (Child Account):**

    * Street Address, City, State, State Code, Zip Code, Country Code, Country Long

    **Employer (Parent Account):**

    * Street Address, City, State, State Code, Zip Code

    <Tip>
      **Use "State Code" instead of "State"** if your CRM field expects a two-letter abbreviation (e.g., "TX" instead of "Texas"). Mapping the full state name to an abbreviation field will cause sync failures.
    </Tip>
  </Accordion>

  <Accordion title="Why isn't my data pushing to picklist / dropdown fields?">
    Your CRM requires a **100% exact match** between the data BenefitFlow sends and the values defined in your CRM's picklist. If a value doesn't match, the **entire operation for that record fails** — not just that one field. Worse, if the mismatch comes from a global mapping rule (e.g., a Custom Value that applies to every record), it can cause the **entire bulk sync to fail** across all records in the batch.

    Since BenefitFlow data is unlikely to perfectly align with your custom picklist values (with exceptions like state codes or months of the year), mapping to picklists is **prone to failure**.

    **How to fix this:**

    | CRM            | Solution                                                                                                            |
    | -------------- | ------------------------------------------------------------------------------------------------------------------- |
    | **Salesforce** | Change the picklist field to **unrestricted** (accepts any value up to 255 characters) or change it to a text field |
    | **HubSpot**    | Ensure the dropdown property allows custom values, or switch to a single-line text property                         |
    | **Dynamics**   | Use a **Custom Value** mapping rule to push a known valid value, or accept that mismatches will cause failures      |
  </Accordion>

  <Accordion title="How should I set up my field mappings to avoid errors?">
    1. **Avoid picklist/dropdown target fields** unless you're certain BenefitFlow's values will match exactly. Use text fields instead.
    2. **Use State Code, not State** if your CRM expects abbreviations (e.g., "TX" not "Texas").
    3. **Map only the fields you need.** Every additional mapping is a potential failure point. Start small and add mappings as needed.
    4. **Test with a small batch first.** Sync 5–10 records before doing a bulk push. Check the Activity Log for errors.
    5. **Review your matching fields.** BenefitFlow uses website domain for employer accounts and email for contacts to detect duplicates. For broker accounts, matching uses website domain + city + state (since the same brokerage may have multiple offices). Don't change these unless you understand the implications.
    6. **Enable Allow Overwrite intentionally.** Only turn on overwrite for fields where you want BenefitFlow to update existing CRM data on future syncs. See the [Overview Guide](/knowledge-base/crm-integration-overview) for details.
  </Accordion>

  <Accordion title="Why does 'Company Website' have no mapping targets in Dynamics?">
    The website domain field is used as a **matching field** for account deduplication, which is why it may not appear as a mappable target. If you need website data in a separate CRM field, contact support at **[customerteam@benefit-flow.com](mailto:customerteam@benefit-flow.com)**.
  </Accordion>

  <Accordion title="Why are my URLs being rejected by HubSpot?">
    HubSpot properties with URL validation rules require values to include `http://` or `https://`. BenefitFlow stores URLs **without** the protocol prefix (e.g., `benefit-flow.com` instead of `https://benefit-flow.com`), so the sync fails silently when HubSpot's validation rejects the value.

    **How to fix this:**

    * **Option 1:** Remove the URL validation rule on the HubSpot property. Go to Settings → Properties → find the field → Edit → remove the URL format requirement.
    * **Option 2:** Keep the validation but add a HubSpot Workflow that prepends `https://` to the field value after BenefitFlow pushes it.
  </Accordion>

  <Accordion title="A field shows data in BenefitFlow but pushes blank to my CRM — why?">
    Some fields visible on an employer or contact profile in BenefitFlow are **not available at the sync level**. This happens when a field is derived from policy-level data (e.g., Covered Lives, Carrier) rather than employer-level data. Since syncing operates at the employer/contact level, policy-level fields may appear blank or inconsistent.

    **Fields with known limitations:**

    * **Covered Lives** — This is a policy-level metric and does not reliably map to a single employer value. Do not map this field — it will push blank or inconsistent data.
    * **Carrier** — When an employer has multiple policies, the synced value may not match the carrier shown on the profile. If you rely on this field, verify the synced value in your CRM after each push.
    * **5500 Signor Name** — We identified a mismatch between the profile display and the synced value, and are fixing it. Avoid mapping this field until the fix ships.

    If a different mapped field is consistently pushing blank, check the Activity Log for errors and contact support at **[customerteam@benefit-flow.com](mailto:customerteam@benefit-flow.com)**.
  </Accordion>
</AccordionGroup>

## Sync Status & Troubleshooting

<AccordionGroup>
  <Accordion title="How do I know if my sync succeeded or failed?">
    BenefitFlow provides several ways to check sync status:

    1. **Toast notification** — After syncing, a message appears showing how many records were pushed successfully and how many were skipped or failed.
    2. **Tab indicators** — Records move between the **Net New**, **Updates**, and **Synced** tabs after a sync. If a record stays in its original tab after syncing, something went wrong.
    3. **Activity Log** — Click the **Activity Log** tab (visible when your CRM is connected) to see a full history of sync operations. You can filter by date, triggered by, object, action (Insert/Update), and result (Success/Error). Click on a failed operation to see error details.
    4. **"View in CRM" link** — Successfully synced contacts show a "View in CRM" button that opens the record directly in your CRM.

    <Tip>
      If you synced a batch and the Activity Log shows errors, check whether picklist mismatches or permission issues are the cause — these are the most common failure reasons.
    </Tip>
  </Accordion>

  <Accordion title="Accounts synced but contacts didn't — what happened?">
    This is typically caused by one of the following:

    | Cause                       | How to Check                                                                                                                                                                                                                                                                                               |
    | --------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
    | **Missing contact data**    | Contacts missing required information (such as email address) are grayed out and cannot be synced. Hover over the contact to see what's missing.                                                                                                                                                           |
    | **Credit limit reached**    | You'll see a message like "This request exceeds your Credit Allocation." Contact your admin to purchase more credits.                                                                                                                                                                                      |
    | **Expired CRM credentials** | If your OAuth token has expired, reconnect your CRM under Integrations → Connection. Expiration timelines vary by CRM platform.                                                                                                                                                                            |
    | **Field mapping errors**    | A mapping targeting an incompatible field type (e.g., picklist mismatch) can cause the entire contact operation to fail. Check the Activity Log for error details.                                                                                                                                         |
    | **CRM permission issues**   | The connected CRM user may not have write access to certain fields or objects. In Salesforce, check that fields aren't set to Read-Only for the API user.                                                                                                                                                  |
    | **Partial batch sync**      | In rare cases, a bulk sync may not push all records in a single batch. If your Updates tab still shows records after syncing, push the remaining records in a smaller batch or individually. If this recurs, contact support at **[customerteam@benefit-flow.com](mailto:customerteam@benefit-flow.com)**. |
  </Accordion>

  <Accordion title="I'm getting duplicate errors — how do I fix this?">
    Duplicate errors come from **your CRM's duplicate detection rules**, not from BenefitFlow. BenefitFlow checks for duplicates using:

    * **Employer accounts:** Website domain
    * **Broker accounts:** Website domain + city + state (since the same brokerage may have multiple offices)
    * **Contacts:** Email address

    For more on how duplicate detection works, see the [CRM Integration Overview](/knowledge-base/crm-integration-overview).

    When your CRM also has its own duplicate/matching rules enabled, it may reject records that BenefitFlow considers net-new. To troubleshoot:

    1. **Check your CRM's duplicate rules.** In Salesforce, go to Setup → Duplicate Rules. In HubSpot, check Settings → Properties for deduplicate settings.
    2. **Try creating the record manually** in your CRM. If the CRM blocks manual creation too, the issue is with your CRM rules, not BenefitFlow.
    3. **Look at what field triggered the match.** CRM duplicate rules often match on fields like company name or phone number — not just the fields BenefitFlow uses (website/email).
  </Accordion>

  <Accordion title="Parent accounts are auto-creating instead of prompting — is that expected?">
    Yes — this is expected in most cases. When BenefitFlow can clearly identify the correct parent account (e.g., there is exactly one match by website domain), it creates the parent account automatically. You will only see a prompt when BenefitFlow detects **ambiguity** — for example, if multiple potential parent accounts exist for the same domain and the system needs you to choose.

    If parent accounts are being created that don't look correct, contact support at **[customerteam@benefit-flow.com](mailto:customerteam@benefit-flow.com)** so we can review your account matching configuration.
  </Accordion>

  <Accordion title="My HubSpot sync is spinning and never completes — what's wrong?">
    A bulk sync that spins indefinitely in HubSpot is almost always caused by a **bad field mapping** that causes the entire batch to fail silently.

    **How to troubleshoot:**

    1. **Try syncing a single record** instead of a bulk push. If individual syncs work but bulk doesn't, a mapping issue is the likely cause.
    2. **Check your field mappings** under Integrations → Integration Settings → Mapping. Look for mappings targeting dropdown, date, or URL-validated fields.
    3. **Check the Activity Log** for any error entries.

    If you can't identify the problem, contact support. The most common fix is removing or correcting the offending mapping rule.
  </Accordion>

  <Accordion title="My integration stopped working after a team member left — how do I fix it?">
    The CRM connection is tied to the **specific user who authenticated it**. If that person leaves the company or their CRM account is deactivated, the OAuth token can no longer refresh and all syncs will fail. You may see an error like: *"Unable to refresh session due to: inactive user."*

    **How to fix this:**

    1. Go to **Integrations → Connection**.
    2. Click **Disconnect** to remove the expired connection.
    3. Log out of all CRM sessions in your browser.
    4. Log in to your CRM as an **active user** with the appropriate permissions.
    5. Return to BenefitFlow and re-establish the connection.

    <Tip>
      **Prevention:** Connect the integration using a dedicated service account or shared integration user rather than a personal account. This way, the connection survives individual team member departures.
    </Tip>
  </Accordion>

  <Accordion title="My Dynamics connection says 'Active' but nothing syncs — what happened?">
    This is a known issue where the Dynamics connection status shows **"Active"** even though the setup never fully completed. The most common cause is that the Azure AD user who authenticated is **not a member of the Dynamics organization**.

    **How to fix this:**

    1. Confirm the user who set up the connection is a member of your Dynamics 365 organization (not just Azure AD).
    2. Go to **Integrations → Connection** and click **Update Connection**.
    3. Re-authenticate using a user who has both Azure AD access and Dynamics org membership.

    If the issue persists, you may need to walk through the setup from scratch with your Dynamics admin. See the [Dynamics Setup Guide](/knowledge-base/dynamics-integration-setup-instructions) for the full steps.
  </Accordion>

  <Accordion title="I'm getting 'REST API is not enabled' when connecting to Salesforce — how do I fix it?">
    This error means your Salesforce organization doesn't have the REST API enabled, which is a **prerequisite** for the BenefitFlow integration. The connection may appear to succeed initially but will fail when attempting to sync data.

    **How to fix this:**

    1. Log in to Salesforce as a System Administrator.
    2. Go to **Setup → Users → Profiles** → select the profile of the integration user.
    3. Under **Administrative Permissions**, ensure **"API Enabled"** is checked.
    4. If your Salesforce edition doesn't include API access by default, you may need to contact Salesforce to enable it.

    After enabling the API, return to BenefitFlow and reconnect under **Integrations → Connection**. See the [Salesforce Setup Guide](/knowledge-base/salesforce-integration-setup-instructions) for the full connection walkthrough.
  </Accordion>
</AccordionGroup>

## CRM-Specific Questions

<AccordionGroup>
  <Accordion title="Can BenefitFlow add synced records to Salesforce Campaigns?">
    Not directly. BenefitFlow syncs records as **Accounts** and **Contacts** in Salesforce — it does not create Campaign Members or add records to Campaigns.

    To automatically add BenefitFlow-synced contacts to a Campaign, set up a Salesforce Flow that triggers when a new Contact is created with a Lead Source of "BenefitFlow" (you can set this using a **Custom Value** mapping rule).
  </Accordion>

  <Accordion title="Does the broker office location become the primary company in HubSpot?">
    BenefitFlow creates **Company** records in HubSpot for broker office locations and creates associations between Companies and Contacts. However, BenefitFlow does not override your existing primary company assignments in HubSpot.

    If a contact is associated with multiple companies after a sync, check HubSpot's association settings to control which company appears as primary.
  </Accordion>

  <Accordion title="Can I sync as Leads instead of Contacts in HubSpot?">
    Not in HubSpot. A "Lead" in HubSpot is simply a flag on the Contact object, not its own object type — so BenefitFlow syncs records as **Contacts** in HubSpot.

    <Note>
      If you use **Salesforce**, the integration does support syncing to the Lead object (which is a separate object type in Salesforce). See your field mapping configuration for setup details.
    </Note>
  </Accordion>
</AccordionGroup>

## Permissions & Visibility

<AccordionGroup>
  <Accordion title="Who needs to set up the integration?">
    Setting up the integration requires two things:

    1. **BenefitFlow Admin role** — Only Admin users in BenefitFlow can access **Integrations** (via the user menu) to connect the CRM and configure field mappings.
    2. **CRM permissions** — The user who authenticates the connection needs read/write access to the relevant CRM objects (Accounts, Contacts). See "What Salesforce permissions does the integration user need?" below for specifics, or see the setup guide for your CRM.

    Standard BenefitFlow users can sync records after the integration is configured, but cannot change connection settings, field mappings, or sync permissions. Admins can control what sync operations standard users are allowed to perform under **Integration Settings > Preferences**. For more detail, see the [CRM Integration Overview](/knowledge-base/crm-integration-overview).
  </Accordion>

  <Accordion title="Why can I sync some contacts but not others?">
    Your BenefitFlow admin controls which sync operations standard users can perform for each object type (Contacts and Accounts). By default, standard users can only create **Net New** records. If a record requires an operation you don't have permission for, you'll see a **"Restricted"** indicator and the **"Push to CRM"** button will be disabled for those records.

    This is the most common reason a user can sync some records on a list but not others — the ones that work match your allowed sync operations, and the ones that don't require a permission your admin hasn't granted.

    **To resolve this:**

    * Ask your BenefitFlow Admin to adjust your sync permissions under **Integration Settings > Preferences > Sync Permissions for Standard Users**
    * Ask a BenefitFlow Admin to push the records on your behalf
    * Have your admin upgrade your account to Admin under **Team Management**
  </Accordion>

  <Accordion title="Can I see what's already in my CRM before using credits?">
    Yes. BenefitFlow's **CRM Filter** lets you filter contacts by "In my CRM" or "Not in my CRM" on the Broker Contacts and Employer Contacts tabs. This helps you identify which contacts already exist in your CRM before spending credits.

    <Warning>
      **Unlocking a contact always costs a credit**, even if that contact already exists in your CRM. The CRM Filter helps you prioritize which contacts to unlock, but it does not make unlocks free.
    </Warning>
  </Accordion>

  <Accordion title="How is contact ownership assigned when syncing?">
    When BenefitFlow creates a new contact in your CRM, it assigns the Contact Owner from the **owner of the associated Account** in your CRM. If that account has no owner yet, BenefitFlow leaves the field blank and your CRM's own default assignment rules apply.

    A few things that follow from this:

    1. Ownership is set only when the contact is first created. Syncing updates to an existing contact never changes its owner.
    2. Ownership is not based on who clicked "Get Contact", who added the contact to a list, or who initiated the sync.
    3. To set owners explicitly, use **Assign Owner** on the list before syncing. Admins can also use it to reassign contacts that have already been synced.

    BenefitFlow does not set an Account Owner when syncing to the Account object.

    For more detail, see the [CRM Integration Overview](/knowledge-base/crm-integration-overview).
  </Accordion>

  <Accordion title="What Salesforce permissions does the integration user need?">
    The user who connects BenefitFlow to Salesforce needs the following minimum permissions:

    | Object / Permission  | Access Level                                      |
    | -------------------- | ------------------------------------------------- |
    | **Accounts**         | Read / Write                                      |
    | **Contacts**         | Read / Write                                      |
    | **Salesforce Users** | Read Only (required for contact owner assignment) |
    | **API Enabled**      | Required (system permission)                      |

    <Tip>
      **Recommended:** Create a dedicated **Integration User** in Salesforce with a scoped permission set. This prevents the connection from breaking when individual team members leave (see "My integration stopped working after a team member left" above). When connecting, log out of all Salesforce sessions first, then log in as the Integration User before completing the BenefitFlow setup flow.
    </Tip>
  </Accordion>

  <Accordion title="Why does Salesforce ask for broad permissions during setup?">
    During the OAuth connection flow, Salesforce displays a permissions modal requesting access to your identity URL, data via APIs, and the ability to perform requests at any time. These are **standard Salesforce OAuth scopes** required for any integration that reads and writes CRM data:

    * **api** — Allows BenefitFlow to create and update Accounts and Contacts
    * **refresh\_token** — Keeps the connection alive without requiring you to re-authenticate daily
    * **id** — Identifies the connected user for owner assignment
    * **web** — Enables the browser-based OAuth callback

    These scopes cannot be narrowed further — they are the minimum required for CRM syncing. To limit what the integration can actually do, use a **dedicated Integration User** with a restricted permission set in Salesforce. The OAuth scopes grant API access, but the permission set controls which objects and fields that user can read or write.
  </Accordion>
</AccordionGroup>

## Current Integration Limitations

BenefitFlow's CRM integration is designed for **outbound data enrichment** — pushing BenefitFlow data into your CRM. It's a one-way sync. Here are some common requests that fall outside the current integration scope:

<AccordionGroup>
  <Accordion title="Can I import CRM records into BenefitFlow? (Reverse sync)">
    No. BenefitFlow does not pull data from your CRM. The integration is one-way: BenefitFlow → CRM. You cannot import CRM records into BenefitFlow to enrich them.
  </Accordion>

  <Accordion title="Can I use a different unique identifier besides website or email?">
    Not currently. BenefitFlow uses **website domain** to match employer accounts, **website domain + city + state** to match broker accounts, and **email address** to match contacts. These are the only supported matching fields for duplicate detection.

    If your CRM uses a different unique identifier (e.g., a custom external ID), BenefitFlow cannot match against it today. This means records may appear as "Net New" in BenefitFlow even if they already exist in your CRM under a different identifier.

    **Workaround:** Ensure your CRM records have website domain populated on Accounts and email addresses populated on Contacts. BenefitFlow will match against these fields even if your CRM's primary key is something else.
  </Accordion>

  <Accordion title="Can I create CRM workflows from within BenefitFlow?">
    No. BenefitFlow pushes data to your CRM, but it does not create or manage CRM-side automation. To trigger actions based on synced data (e.g., creating tasks, sending emails, adding to campaigns), use your CRM's native automation tools:

    * **Salesforce:** Flows
    * **HubSpot:** Workflows
    * **Dynamics:** Power Automate

    For a worked example, see [Linking Employers to Their Primary Broker Office](/knowledge-base/crm-employer-broker-linking), which uses these native tools to associate each employer with its broker office from synced BenefitFlow IDs.
  </Accordion>

  <Accordion title="Can BenefitFlow merge duplicate accounts that already exist in my CRM?">
    No. BenefitFlow creates and updates records but does not merge existing CRM records. If you have duplicate accounts in your CRM, you'll need to merge them using your CRM's built-in deduplication tools before or after syncing.
  </Accordion>
</AccordionGroup>

## Related Resources

<CardGroup>
  <Card title="CRM Integrations: Getting Started" icon="circle-play" href="/knowledge-base/crm-integrations-getting-started" horizontal={true}>
    Step-by-step guide to connecting your CRM and syncing your first records.
  </Card>

  <Card title="CRM Integrations: Overview Guide" icon="book-open-lines" href="/knowledge-base/crm-integration-overview" horizontal={true}>
    How duplicate detection, field mapping, and contact ownership work.
  </Card>

  <Card title="Salesforce Setup" icon="salesforce" href="/knowledge-base/salesforce-integration-setup-instructions" horizontal={true}>
    Detailed Salesforce integration setup instructions.
  </Card>

  <Card title="HubSpot Setup" icon="hubspot" href="/knowledge-base/hubspot-integration-setup-instructions" horizontal={true}>
    Detailed HubSpot integration setup instructions.
  </Card>

  <Card title="Dynamics Setup" icon="microsoft" href="/knowledge-base/dynamics-integration-setup-instructions" horizontal={true}>
    Detailed Microsoft Dynamics integration setup instructions.
  </Card>
</CardGroup>