# Best Practices

## Recommended setup

<table data-card-size="large" data-view="cards"><thead><tr><th></th><th></th></tr></thead><tbody><tr><td><strong>Start with your anchor entity</strong></td><td>Events is the core of Circa's data model. Build your first data flow around Events, then use Join to bring in Event contacts and Contacts for a complete picture.</td></tr><tr><td><strong>Pull field definitions separately</strong></td><td>Add Event fields, Contact fields, or Company fields as a separate source in your data flow. This lets you reference custom field metadata without cluttering your main entity output.</td></tr><tr><td><strong>Use Join for relationship data</strong></td><td>Company contacts and Event contacts only contain IDs. Always pair them with a Join transformation against the Contacts entity so your output includes actual names and contact details.</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>Set your start date thoughtfully</strong></td><td>A start date that's too far back will pull years of event history on every refresh. Set it to match the reporting window you actually need — for example, the start of the current quarter or fiscal year.</td></tr><tr><td><strong>Run a manual sync first</strong></td><td>Before scheduling, complete a successful manual run and verify the row counts match what you'd expect in Circa. This catches configuration issues before they silently affect your scheduled reports.</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</strong></td><td>If you're pulling many entities — Events, Contacts, Companies, and their relationship tables all at once — consider splitting them across two data flows to stay within Circa's API rate limits.</td></tr><tr><td><strong>Use Append for multi-account reporting</strong></td><td>If your organization has more than one Circa account, use Coupler.io's Append transformation to combine data from all accounts into a single destination without manual merging.</td></tr></tbody></table>

## Common pitfalls

{% hint style="danger" %}
Don't use relationship entities (Event contacts, Company contacts) as your primary reporting table — they only contain IDs and will produce unreadable reports without a Join against Contacts.
{% endhint %}

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

* Join Event contacts with Contacts to get full attendee details
* Pull custom field definition entities separately from value entities
* Verify row counts with a manual run before scheduling
* Use Aggregate to count contacts per event or company
  {% endcolumn %}

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

* Rely on relationship entities alone without joining to Contacts
* Set a start date at the beginning of time — pull only what you need
* Put every Circa entity into a single data flow if you're hitting rate limits
* Ignore the updated\_at field — it's your best signal for detecting changed records
  {% endcolumn %}
  {% endcolumns %}