# Best Practices

## Recommended setup

<table data-card-size="large" data-view="cards"><thead><tr><th></th><th></th></tr></thead><tbody><tr><td><strong>Use Candidate ID as your primary key</strong></td><td>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.</td></tr><tr><td><strong>Join Candidates with Positions</strong></td><td>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.</td></tr><tr><td><strong>Filter by State for active-only reports</strong></td><td>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.</td></tr></tbody></table>

## Data refresh and scheduling

<table data-card-size="large" data-view="cards"><thead><tr><th></th><th></th></tr></thead><tbody><tr><td><strong>Match refresh frequency to hiring pace</strong></td><td>For active recruiting periods, daily syncs keep your reports current. For slower periods or evergreen role tracking, weekly syncs are usually sufficient.</td></tr><tr><td><strong>Run a manual sync after bulk changes</strong></td><td>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.</td></tr></tbody></table>

## Performance optimization

<table data-card-size="large" data-view="cards"><thead><tr><th></th><th></th></tr></thead><tbody><tr><td><strong>Split large data flows by entity</strong></td><td>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.</td></tr><tr><td><strong>Use Aggregate for funnel metrics</strong></td><td>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.</td></tr></tbody></table>

## Common pitfalls

{% hint style="danger" %}
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.
{% endhint %}

{% columns %}
{% column %}
**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
  {% endcolumn %}

{% column %}
**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
  {% endcolumn %}
  {% endcolumns %}