Skip to main content

​
Field Mapping

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
BenefitFlow provides two distinct renewal date fields:
FieldFormatExample
Benefit Renewal MonthMonth name (string)“January”
Employer Renewal DateFull date01/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.
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.
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
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.
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:
CRMSolution
SalesforceChange the picklist field to unrestricted (accepts any value up to 255 characters) or change it to a text field
HubSpotEnsure the dropdown property allows custom values, or switch to a single-line text property
DynamicsUse a Custom Value mapping rule to push a known valid value, or accept that mismatches will cause failures
  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 for details.
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.
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.
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.

​
Sync Status & Troubleshooting

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.
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.
This is typically caused by one of the following:
CauseHow to Check
Missing contact dataContacts 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 reachedYou’ll see a message like “This request exceeds your Credit Allocation.” Contact your admin to purchase more credits.
Expired CRM credentialsIf your OAuth token has expired, reconnect your CRM under Integrations → Connection. Expiration timelines vary by CRM platform.
Field mapping errorsA 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 issuesThe 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 syncIn 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.
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.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).
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 so we can review your account matching configuration.
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.
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.
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.
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 for the full steps.
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 for the full connection walkthrough.

​
CRM-Specific Questions

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).
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.
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.
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.

​
Permissions & Visibility

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.
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
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.
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.
BenefitFlow assigns the Contact Owner based on the user that originally clicked “Get Contact” on the contact — not necessarily the user who initiates the sync. BenefitFlow does not set an Account Owner when syncing to the Account object.For more detail, see the CRM Integration Overview.
The user who connects BenefitFlow to Salesforce needs the following minimum permissions:
Object / PermissionAccess Level
AccountsRead / Write
ContactsRead / Write
Salesforce UsersRead Only (required for contact owner assignment)
API EnabledRequired (system permission)
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.
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.

​
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:
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.
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.
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
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.

CRM Integrations: Getting Started

Step-by-step guide to connecting your CRM and syncing your first records.

CRM Integrations: Overview Guide

How duplicate detection, field mapping, and contact ownership work.

Salesforce Setup

Detailed Salesforce integration setup instructions.

HubSpot Setup

Detailed HubSpot integration setup instructions.

Dynamics Setup

Detailed Microsoft Dynamics integration setup instructions.
Last modified on March 31, 2026