Syncing Audiences to Your CRM

This guide walks you through building a targeted audience in SignalSmith and syncing it to a CRM platform like Salesforce or HubSpot. By the end, you’ll have an automated pipeline that keeps your CRM lists in sync with your warehouse-defined audience segments.

When to Use This

CRM audience syncs are the right approach when you need to:

• Push high-value account lists to your sales team’s CRM
• Keep marketing lists in HubSpot or Salesforce updated automatically
• Sync customer segments for personalized outreach campaigns
• Maintain suppression lists to prevent contacting opted-out customers
• Feed lead scoring models in your CRM with warehouse-computed traits

Prerequisites

• A configured warehouse connected to your data warehouse
• At least one entity type defined in your schema (e.g., User or Account)
• A CRM account with API access (Salesforce, HubSpot, or another supported CRM)

Step 1: Choose Your CRM Destination

SignalSmith supports several CRM destinations out of the box:

Connect the Destination

1. Navigate to Destinations in the left sidebar
2. Click Add Destination
3. Select your CRM (e.g., Salesforce)
4. Complete the authentication flow:
   • Salesforce: Click “Connect with Salesforce” and authorize via OAuth. Select your environment (Production or Sandbox).
   • HubSpot: Click “Connect with HubSpot” or enter a Private App access token with the required scopes (crm.objects.contacts.write, crm.lists.write).
5. Click Save

Step 2: Build a Relevant Audience

Build an audience that represents the customer segment you want in your CRM. Here are some common CRM audience patterns:

Example: High-Value Accounts

Entity Type: Account
WHERE
  annual_revenue > 100000
  AND contract_status = 'active'
  AND health_score >= 70

Example: Sales Qualified Leads

Entity Type: User
WHERE
  lead_score >= 80
  AND demo_requested = true
  AND days_since_signup <= 30

Example: Renewal Candidates

Entity Type: Account
WHERE
  contract_end_date <= DATE_ADD(CURRENT_DATE, INTERVAL 90 DAY)
  AND contract_status = 'active'
  AND churn_risk_score < 50

Building the Audience

1. Navigate to Segment → Audiences
2. Click Create Audience
3. Select the entity type (e.g., “Account”)
4. Use the filter builder to add conditions — combine trait values and attributes with AND/OR logic
5. Click Estimate to check the audience size
6. Click Preview to inspect sample members and verify the segment
7. Name your audience descriptively (e.g., “High-Value Active Accounts”) and click Save

Step 3: Configure the Audience Sync with Mirror Mode

Mirror mode is recommended for CRM syncs because it keeps the destination list perfectly synchronized — adding new members, updating existing records, and removing members who no longer qualify.

1. Navigate to Segment → Audience Syncs
2. Click Create Audience Sync
3. Select your audience (e.g., “High-Value Active Accounts”)
4. Select your CRM destination (e.g., Salesforce)
5. Choose Mirror as the sync mode

Why Mirror Mode for CRMs?

For most CRM use cases, Mirror is the right choice. It ensures your sales team always sees the current state of each segment without stale records.

Step 4: Map Audience Fields to CRM Properties

Field mapping tells SignalSmith how to translate your entity attributes and traits into CRM-native fields.

1. In the audience sync configuration, go to the Field Mapping section
2. Map your identifier field to the CRM’s primary key:
   • Salesforce: Map email to Email on the Lead/Contact object
   • HubSpot: Map email to email on the Contact object
3. Map additional attributes and traits to CRM properties:

4. For custom fields, ensure they exist in your CRM before syncing. SignalSmith will not create custom fields automatically.
5. Set the sync schedule — common choices for CRM syncs:
   • Every 1 hour — For time-sensitive sales workflows
   • Every 6 hours — For general marketing lists
   • Daily — For reporting-oriented segments

Step 5: Monitor Sync Runs

After saving and running the sync, monitor its execution to ensure data is flowing correctly.

1. Navigate to the Sync Runs tab on your audience sync
2. Review the first run summary:
   • Members Added — New records created in the CRM
   • Members Updated — Existing records updated with new field values
   • Members Removed — Records removed from the CRM list (Mirror mode)
   • Errors — Records that failed to sync
3. Click into the run details to see per-record status if needed
4. Check Insights → Sync Health for trend monitoring across all runs

What a Healthy Sync Looks Like

• First run: large number of “Members Added” (initial population)
• Subsequent runs: small numbers of adds, updates, and removes (incremental changes)
• Error rate below 1%
• Run duration consistent across executions

Step 6: Handle Common Errors

CRM syncs can encounter several types of errors. Here’s how to diagnose and resolve the most common ones.

Duplicate Records

Symptom: Sync reports “duplicate value” errors or creates multiple records for the same person.

Cause: The identifier field you’re matching on has duplicates in your audience, or the CRM already has records with the same identifier.

Resolution:

1. Check your audience for duplicate identifiers — add a deduplication step to your model’s SQL query
2. In Salesforce, check your duplicate rules under Setup → Duplicate Management
3. Use a unique, stable identifier as the match key (e.g., email address or external ID)

Missing Required Fields

Symptom: Sync reports “required field missing” errors for some records.

Cause: The CRM object has required fields that aren’t included in your field mapping, or some records have NULL values for mapped required fields.

Resolution:

1. Check which fields are required in your CRM’s object configuration
2. Add the missing fields to your field mapping
3. If some records have NULL values, add a filter to your audience to exclude incomplete records:

   AND email IS NOT NULL
   AND last_name IS NOT NULL

Rate Limiting

Symptom: Sync runs are slow or partially fail with “rate limit exceeded” errors.

Cause: The CRM’s API rate limits have been reached, especially with large audiences.

Resolution:

1. SignalSmith batches API calls automatically, but very large audiences (100K+) may still hit limits
2. Schedule syncs during off-peak hours when API usage is lower
3. For Salesforce, consider requesting a higher API limit from your Salesforce admin
4. For HubSpot, ensure your account tier supports the throughput you need

Authentication Failures

Symptom: Sync fails with “unauthorized” or “token expired” errors.

Cause: OAuth tokens have expired or been revoked.

Resolution:

1. Navigate to Destinations and click on the affected CRM destination
2. Click Reconnect to re-authenticate
3. Verify the connected user has the necessary permissions in the CRM

Best Practices

• Start with a small audience — Test with a limited segment (e.g., 100 records) before syncing your full audience to catch mapping issues early.
• Use custom fields for traits — Create custom fields in your CRM for SignalSmith-computed traits rather than overwriting standard fields.
• Set up alerts — Configure sync failure notifications so your team is notified immediately when a sync encounters errors.
• Document field mappings — Maintain a record of which SignalSmith fields map to which CRM properties, especially for custom fields.
• Review before Mirror deletes — If using Mirror mode, be aware that members who exit the audience will be removed from the CRM list. Ensure this is the intended behavior.

Next Steps

• Audience Syncs documentation — Deep dive into sync modes and configuration
• Retargeting Audiences — Extend activation to ad platforms
• Destination Filters — Control which audiences can sync to which destinations
• Salesforce destination — Salesforce-specific configuration details
• HubSpot destination — HubSpot-specific configuration details