# 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 a dedicated API token</strong></td><td>Create a Zendesk API token specifically for Coupler.io under an admin account. This makes it easy to revoke access without disrupting other integrations.</td></tr><tr><td><strong>Pick the right entity for your goal</strong></td><td>Use Calls for historical analysis, Agents activities for performance reviews, and Current queue activities only for real-time dashboards — don't mix these in the same report.</td></tr><tr><td><strong>Join Calls to Zendesk Support tickets</strong></td><td>The `ticket_id` field in the Calls entity matches ticket IDs in Zendesk Support. Use Coupler.io's Join transformation to connect call outcomes to ticket resolution data.</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>Schedule queue snapshots during business hours</strong></td><td>Current queue activities and Agents overviews reflect live state. Scheduling runs during peak hours (e.g., every 15–30 minutes mid-day) gives you meaningful data — overnight runs will mostly show zeros.</td></tr><tr><td><strong>Use a rolling start date for Calls</strong></td><td>For ongoing call reporting, set your start date to the beginning of your current reporting period (week or month). Avoid pulling all-time data on every run — it increases processing time and can approach rate limits.</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>Separate Calls and Call legs into different data flows</strong></td><td>Call legs can contain significantly more rows than Calls. Keeping them in separate data flows prevents large leg exports from slowing down your main call reporting flow.</td></tr><tr><td><strong>Use Append for period-over-period analysis</strong></td><td>Export weekly agent activity snapshots and use Coupler.io's Append transformation to stack them into a single dataset. This is more reliable than pulling a long date range in one shot.</td></tr></tbody></table>

## Common pitfalls

{% hint style="danger" %}
Don't rely on Current queue activities for historical reporting — it only captures the state at the moment the data flow runs and will not reflect what happened earlier in the day.
{% endhint %}

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

* Set a specific start date when exporting Calls or Call legs
* Use an admin-level API token to avoid 403 errors
* Join Call legs to Calls on `call_id` when you need full routing detail
* Account for UTC timestamps when comparing to Zendesk dashboards
  {% endcolumn %}

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

* Pull open-ended Calls exports without a start date — results may be empty
* Use the same data flow for both real-time queue monitoring and historical call analysis
* Expect IVR entities to have data if IVRs aren't configured in your account
* Assume `recording_url` will be populated — it depends on your plan and line settings
  {% endcolumn %}
  {% endcolumns %}