> For the complete documentation index, see [llms.txt](https://docs.coupler.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.coupler.io/sources/category/project-management/bamboo-hr/best-practices.md). # 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 {% hint style="danger" %} 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. {% endhint %} {% columns %} {% column %} **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 {% endcolumn %} {% column %} **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 {% endcolumn %} {% endcolumns %} --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.coupler.io/sources/category/project-management/bamboo-hr/best-practices.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.