Production company synchronization – guidance on Batch APIs, rate limits, and caching

Developer Support APIs & Integrations
1

Production company synchronization – guidance on Batch APIs, rate limits, and caching

Hello HubSpot Support Team,

We are preparing a production synchronization of platform companies to HubSpot and would appreciate your recommendation on the safest API approach.

Our use case

  • Initial synchronization of approximately 8,000–9,000 companies for Belgium.
  • Other country portals will be processed afterward.
  • After the initial migration, we will run smaller daily updates and single-company synchronization actions.

Synchronization flow

For each company, we:

  1. Search by the platform company hash.
  2. If no hash match exists, search by normalized Company Name + Street Address + Postal Code.
  3. Create or update the company.
  4. For customer companies, create/update their related leasing company.
  5. Associate the customer with the leasing company using the Leasing bank association.
  6. Set platform_synchronization=true only after the required operations succeed.

Business-data conflicts are logged and not overwritten automatically.

Approaches being considered

Individual API calls

  • Simpler to debug and retry.
  • Easier to resume from a specific company.
  • Requires more API requests and takes longer.

HubSpot Batch APIs

  • Faster and requires fewer API requests.
  • More complicated when only some records in a batch fail.
  • Requires careful handling of retries, indexing delays, and associations.

Redis and caching

Our batch implementation uses Redis to:

  • Lock leasing-company creation between queue workers.
  • Temporarily share a leasing-company HubSpot ID between jobs.
  • Prevent multiple workers from creating the same leasing company while HubSpot search indexing is delayed.
  • Coordinate API rate limits.

During testing, we experienced this situation:

  1. A leasing company was created and its HubSpot ID was cached.
  2. The leasing company was manually deleted in HubSpot.
  3. Redis still contained the deleted ID.
  4. Customer association failed with:
    COMPANY=<id> is not valid

We added recovery to remove the stale ID, recreate/find the leasing company, and retry the association once. However, we want to confirm the recommended production approach.

Other observations

  • Newly created companies may not immediately appear in HubSpot search.
  • Concurrent workers may search for the same leasing company before it is indexed.
  • HubSpot hash searches appear case-insensitive, but our platform may contain distinct hashes that differ only by letter case.
  • A batch request can partially succeed, requiring per-record error handling.

Questions

  1. For an initial production migration of approximately 9,000 companies, do you recommend individual API calls or HubSpot Batch APIs?

  2. What batch sizes and worker-concurrency limits do you recommend for company search, creation, update, and association?

  3. Can we immediately associate a company using the ID returned by a batch-create response, or should we wait for HubSpot indexing?

  4. What is the recommended way to prevent duplicate creation when a newly created company is not yet available through search?

  5. Is caching HubSpot company IDs in Redis recommended? If yes, should we validate them before every association or only after receiving an invalid-ID error?

  6. Can a HubSpot company ID become invalid due to deletion, archiving, or merging? Are webhooks available to notify us so we can invalidate our cache?

  7. Are custom-property EQ and IN searches always case-insensitive? Is there a supported way to perform an exact case-sensitive hash match?

  8. What retry strategy do you recommend for partial batch failures, rate limits, timeouts, and temporary 5xx responses?

  9. Can retrying a create request after a timeout create duplicates if HubSpot accepted the original request but the response did not reach us?

  10. Would you recommend Batch APIs only for the initial migration and individual API calls for daily or single-record synchronization?

Our priority is data correctness and preventing duplicate, partially associated, or incorrectly marked successful records. Please suggest the safest production approach and any safeguards you recommend.

3

Hey @VGupta39,

Thanks for posting in the Community!

While we may not be able to answer every question in one go round, I’m happy to tag in some experts to start getting you as much context as possible! Additionally (just in case you haven’t yet), I’d highly recommend using the Docs Assistant in this Developer doc to see if we can get some foundational context going.

@ChrisoKlepke, @BarryGrennan, and @nickdeckerdevs1 - are any of you able to support @VGupta39 with any of their inquiries?

Shane, Senior Community Moderator

4

The other measure I would like to add is idempotence from your side for the synchronization.

In case of create actions, timeout does not imply that the action has failed; it could be that HubSpot accepted the request, but the response was never received by your application. In case of retrying a create action, this may lead to duplication unless you validate that record first with your synchronization key (platform hash).

It is also important that you wait until all dependent actions have been executed before setting the platform_synchronization=true flag.

I’m curious about how HubSpot recommends setting up batch sizes and concurrency in such a scenario

5

Hi, Can give someone from Hubspot official team share their opinion even partial inputs will works for. Just need some opinions of others. Thanks