> 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/ashby/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>Join Applications with Candidates and Jobs</strong></td><td>These three entities together give you the most complete pipeline view. Use the Join transformation in Coupler.io to link them on Candidate ID and Job ID — this way every row has full context without needing separate lookups.</td></tr><tr><td><strong>Use Archive reasons and Sources as lookup tables</strong></td><td>Export Archive reasons and Sources as separate entities, then join them to your Applications data. They contain the human-readable labels that make rejection analysis and source-of-hire reporting meaningful.</td></tr><tr><td><strong>Set a start date for ongoing syncs</strong></td><td>Once you've done an initial full export, use the start date parameter to limit future syncs to recent records. This keeps your data flow fast and avoids re-processing records that haven't changed.</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 hiring campaigns, daily or twice-daily refreshes keep your pipeline data current. For slower periods or headcount planning reports, weekly syncs are usually enough.</td></tr><tr><td><strong>Use Append for interview and offer history</strong></td><td>If you want to track changes over time — like offer status changes or stage progressions — use the Append transformation to accumulate snapshots rather than overwriting with the latest state.</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>Avoid pulling all entities in a single run if not needed</strong></td><td>Entities like Candidates and Applications can be large. Only add entities you actually use in your reports — pulling Feedback form definitions or Locations every hour adds overhead without benefit if those rarely change.</td></tr><tr><td><strong>Use AI destinations for unstructured analysis</strong></td><td>If you want to summarize candidate feedback, identify patterns in archive reasons, or draft hiring summaries, send your Ashby data to ChatGPT, Claude, or Gemini via Coupler.io's AI destinations instead of building complex formulas.</td></tr></tbody></table>

## Common pitfalls

{% hint style="danger" %}
Don't use a scoped or limited API key for your data flow. If the key was created with restricted entity access, some entities will silently return no data rather than throwing an error — making it look like a data issue rather than a permissions issue.
{% endhint %}

{% columns %}
{% column %}
**Do**

* Join Applications to Candidates and Jobs for complete pipeline rows
* Use Archive reasons and Sources entities as lookup tables
* Set a start date after your initial full export to limit re-processing
* Test with a single entity first before building a multi-entity data flow
  {% endcolumn %}

{% column %}
**Don't**

* Export all entities on a high-frequency schedule if most of them rarely change
* Overwrite historical data if you need to track stage or offer status changes over time
* Rely on Coupler.io record counts to match Ashby's built-in reports without checking Ashby's filter defaults first
  {% 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/ashby/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.