Best Practices

Recommended setup

Use Meta fields before building custom reports

Run the Meta fields entity once to see every available field alias in your BambooHR account. This prevents silent column drops caused by mismatched field names in your custom report configuration.

Join Employees directory with other entities

Most entities return only an Employee ID — not names or departments. Use Coupler.io's Join transformation to enrich Timesheet entries or Time off requests with employee details from the directory.

Append across subsidiaries or accounts

If your organization has multiple BambooHR accounts (e.g., different regions or entities), add each as a separate source in one data flow and use the Append transformation to get a unified workforce view.

Data refresh and scheduling

Set a meaningful start date for time off data

The default 30-day lookback for Time off requests is fine for operational monitoring, but set a longer range (e.g., the start of the fiscal year) if you're building annual leave reports or trend analysis.

Don't run multiple BambooHR flows simultaneously

BambooHR has per-account API rate limits. Stagger scheduled syncs — for example, run employee directory at the top of the hour and timesheet entries 15 minutes later — to avoid rate limit failures.

Performance optimization

Limit custom report fields to what you need

The Custom reports entity pulls every field you specify in one API call. Including unnecessary fields increases payload size and slows your sync. Only list fields you actively use in your destination.

Use Aggregate for headcount metrics in BigQuery

If you're loading employee directory data into BigQuery or Looker Studio, apply the Aggregate transformation to pre-calculate headcount by department, location, or status — rather than doing it in the BI layer every time.

Common pitfalls

Never use an API key generated by a non-admin user for production data flows. Permission gaps at the BambooHR user level will cause silent data loss — entities will return empty results without an obvious error message.

Do

• Validate custom report field aliases using the Meta fields entity before configuring your report

• Use a dedicated BambooHR admin account to generate your API key

• Join Timesheet entries with the Employees directory to add department and name context

• Check your BambooHR plan supports time tracking before building timesheet-based reports

Don't

• Assume the Employees directory includes terminated employees — verify your account configuration

• Use the same API key across multiple integrations if you're hitting rate limits

• Skip the manual run before scheduling — a successful test run confirms your field configuration is correct

• Hardcode a date range for time off requests without considering fiscal year or reporting period boundaries