Best Practices

Recommended setup

Use Candidate ID as your primary key

Candidates can appear multiple times if they've applied to more than one position. Always use Candidate ID — not name or email — when joining or deduplicating records.

Join Candidates with Positions

On their own, candidate records show a position reference but not the full role details. Use Coupler.io's Join transformation on Position ID to enrich candidate data with department, location, and job type.

Filter by State for active-only reports

The Positions entity includes draft, closed, and archived roles. Apply a filter on the State field in your destination (or in Coupler.io's transformation step) to keep your dashboards focused on live roles.

Data refresh and scheduling

Match refresh frequency to hiring pace

For active recruiting periods, daily syncs keep your reports current. For slower periods or evergreen role tracking, weekly syncs are usually sufficient.

Run a manual sync after bulk changes

If you've just imported a batch of candidates or updated multiple positions in Breezy HR, trigger a manual run immediately rather than waiting for the next scheduled sync.

Performance optimization

Split large data flows by entity

If you have thousands of candidates, keep Candidates and Positions as separate sources within one data flow rather than chaining them in a single large pull. This makes troubleshooting easier if one entity fails.

Use Aggregate for funnel metrics

Instead of pulling raw candidate records into a spreadsheet and counting manually, use Coupler.io's Aggregate transformation to calculate counts per pipeline stage — reducing destination file size and formula complexity.

Common pitfalls

Avoid sharing or hardcoding your Breezy HR API key in shared spreadsheets or dashboards. If a key is exposed, regenerate it immediately in Breezy HR's API settings and update your Coupler.io data flow.

Do

• Use Candidate ID as the join key between entities

• Filter by State to exclude closed/draft positions from active reports

• Use the Append transformation to combine data from multiple Breezy HR accounts

• Check the Source field to measure recruiting channel effectiveness

Don't

• Rely on candidate name or email as a unique identifier — duplicates will cause row mismatches

• Ignore disqualified candidates in your pipeline counts — they're included in the API response

• Assume pipeline stage names are consistent across positions — stages are customizable per role in Breezy HR