> 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/other/breezy-hr/best-practices.md).

# 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 %}


---

# 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/other/breezy-hr/best-practices.md?ask=<question>&goal=<endgoal>
```

`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.