Dheeraj Sudan and Meenu Hinduja-How can I troubleshoot missing contacts in HubSpot sync?

Apps HubSpot Native Apps
1

Hi Everyone, I am Dheeraj Sudan, a UK-based software developer, I’m currently facing an issue with HubSpot sync where some contacts are missing after synchronization. A portion of the expected contacts are not appearing in HubSpot even though they exist in the source system.

Regards

Dheeraj Sudan and Meenu Hinduja

2

Hi @DheerajSudan,
Thank you for posting to the Community!
I’d like to tag in some of our Champions to take a look here. Hi @KlemenHrovat, @Jonas_De_Mets, and @DanMYD, do any of you all have any ideas on next troubleshooting steps for @DheerajSudan?
Thank you in advance!
Cassie, Community Manager

3

@DheerajSudan
A few ideas what I’d check

1. Confirm whether the contacts are truly missing or just matched/merged

HubSpot Data Sync matches contacts by email by default. During initial sync, HubSpot indexes matching identifiers, then compares source records against that index. If a matching email exists, it may update or match an existing contact instead of creating a new one. HubSpot also notes that duplicate source records can be treated as duplicates, where the first returned record is syncable and later ones may not be.

Action:

  • Take 20 missing source contacts.
  • Search HubSpot by:
    • primary email
    • secondary/additional email
    • source system ID, if mapped
    • name/company as a fallback
  • Export HubSpot contacts including all email addresses if needed, because secondary emails can hide the match. HubSpot says additional emails are also used for deduplication, and multiple contacts cannot share the same additional email.

2. Check sync filters and “Limit” settings

HubSpot’s matching docs explicitly say filters in the Limit section determine which records are included in the sync. That is a common reason contacts “exist in source” but never enter HubSpot.

Action:

  • Review inclusion filters in the sync setup.
  • Look for filters like lifecycle stage, owner, list membership, status, last modified date, active/inactive, region, email present, or opt-in status.
  • Temporarily create a test sync/view with the missing contacts and loosen the filters.

3. Check whether the initial sync actually finished

For large databases, HubSpot says initial syncs can take time, and syncs with millions of records may take several days. HubSpot also says saving the sync restarts the initial sync.

Action:

  • Confirm the initial sync completion email or sync status.
  • Avoid repeatedly saving/changing sync settings while investigating, because that can restart indexing.

4. Inspect sync errors, not just the final contact count

For integrations like Salesforce, HubSpot exposes sync health and error details, including affected records, exportable error CSVs, and resync actions after fixing errors. The same principle applies generally: missing records usually have a reason somewhere in sync health/logs.

Action:

  • Go to Settings > Integrations > Connected Apps > [integration] > Sync Health.
  • Export sync errors.
  • Group errors by type.
  • Prioritize the top 1 to 3 error categories before touching mappings.

5. Verify required fields and field mappings

If contacts are failing validation, the sync may skip or error them. Typical causes:

  • missing email
  • invalid email format
  • required custom property missing
  • enum/dropdown value mismatch
  • lifecycle stage conflict
  • owner/user mismatch
  • company/account dependency not synced yet

HubSpot’s contacts API docs recommend including email because email is the primary unique identifier used to avoid duplicate contacts.

6. If this is a custom API sync, check pagination, batching, and upsert logic

This is the biggest engineering-side culprit. HubSpot’s batch operations are limited to 100 contacts per request, so a custom sync must paginate source records correctly and process batches reliably.

Action:

  • Confirm the source API query returns all expected contacts, not just page 1.
  • Check for off-by-one pagination bugs.
  • Log every source contact ID before sending to HubSpot.
  • Log every HubSpot response, including partial failures.
  • Use idempotent upserts instead of blind creates where possible. HubSpot supports upsert by email or a custom unique identifier property.
  • If email is not stable or contacts can share/change email, use a custom unique ID from the source system as the identity key.

7. Check user permissions and views

Sometimes contacts exist, but the user cannot see them because of permissions or filtered views. HubSpot permissions can control what users can view, create, edit, or delete, including limiting a rep to contacts they own.