Best Practices

Recommended setup

Use internal field names for custom columns

When specifying columns manually, always use HubSpot's internal API field names (e.g., `hs_deal_stage_probability`), not the display labels you see in the HubSpot UI. The Coupler.io help guide shows you how to look these up.

Join Deals with Owners for rep-level reporting

The Deals entity only returns an owner ID by default. Add a second source (Owners entity) to the same data flow and use the Join transformation to map owner names and emails onto your deal records.

Keep custom fields specific

Leaving the custom fields input blank imports every custom property, which can add dozens of empty columns. List only the internal field names you actually need to keep your destination clean and your data flow fast.

Use Append to combine data from multiple portals

If your organization uses more than one HubSpot portal, add each as a separate source in the same data flow and use the Append transformation to stack records into a single unified dataset.

Data refresh and scheduling

Filter by Updated after date for incremental-style runs

For large datasets like Contacts or Deals, set an "Updated after" date filter to pull only recently changed records. This keeps each run fast and avoids re-processing your entire CRM on every refresh.

Use period splitting for email reports

For the Email statistics by period entity, choose a split granularity (weekly or monthly) that matches your reporting cadence. Daily splits for long date ranges generate very large outputs.

Performance optimization

Limit columns to what you need

HubSpot records can have 100+ properties. Use the Columns selector to pull only the fields your report actually uses. This reduces payload size and speeds up every run.

Separate high-volume entities into their own data flows

Contacts databases can be very large. Keep Contacts in a dedicated data flow rather than combining it with Deals in the same run — this way a slow Contacts pull won't delay your pipeline dashboard.

Common pitfalls

HubSpot's API enforces a 2-filter maximum. If you combine a date filter with an advanced filter, you've used both slots. Adding a third filter will cause the run to fail with no records returned.

Do

• Use the Owners entity joined to Deals to get readable rep names

• Use internal HubSpot API field names when specifying columns manually

• Test with a narrow date range before pulling your full historical dataset

• Use Aggregate on Deals to pre-calculate pipeline totals before loading to your destination

Don't

• Apply more than 2 filters at once (date + advanced filter counts as 2)

• Leave custom fields blank if your portal has many custom properties — you'll get columns you don't need

• Pull Contacts without a date filter if your database has tens of thousands of records

• Rely on display labels when naming columns — use internal API names