Best Practices

Recommended setup

Use an admin API key

Standard user keys often miss HR-sensitive data like absences, holiday quotas, and overtime. Using an admin-level key ensures you get a complete dataset across all entities.

Start with Entries + one lookup entity

Entries is the most data-rich entity but needs context. Join it with Customers or Projects in the same data flow to make the output immediately useful without extra post-processing.

Use Customers projects as a bridge table

When building reports that span customers, projects, and entries, pull Customers projects as a separate source and use it as a relational lookup to avoid duplicating customer data across rows.

Data refresh and scheduling

Scope Entries by year, not open-ended

Entries can accumulate into very large datasets over time. Use the Years parameter to pull only the current or relevant year, then append prior years as separate sources if you need historical comparisons.

Schedule HR entities less frequently

Entities like Holidays quota, Target hours, and Teams change rarely. A weekly or monthly refresh is sufficient — daily syncs add API load without meaningful data updates.

Performance optimization

Aggregate in Coupler.io before sending to your destination

Use Coupler.io's Aggregate transformation to sum hours or count entries by user or project before writing to Google Sheets. This keeps your destination lean and avoids row limits on large Entries exports.

Split multi-year history into separate sources

If you need several years of Entries data, add each year as a separate source in the same data flow and use Append to combine them. This prevents single large requests from hitting rate limits or timing out.

Common pitfalls

Duration fields in Entries and Work times are in seconds, not hours. Forgetting to convert (divide by 3600) is the most common source of incorrect reports — always add a calculated column in your destination.

Do

• Use an admin API key for complete data access

• Convert duration fields from seconds to hours in your destination

• Join Entries with Customers or Projects for meaningful reports

• Use the Years or Start date parameter to limit Entries data volume

Don't

• Pull all Entries without a date range on large accounts

• Rely on User reports as your only source — they're pre-aggregated and less flexible

• Ignore the is_billable flag when calculating client-facing revenue totals

• Schedule daily refreshes for entities that change infrequently (quotas, teams, targets)